Skip to content

Latest commit

 

History

History
192 lines (132 loc) · 7.99 KB

devenv-httpclient.md

File metadata and controls

192 lines (132 loc) · 7.99 KB
Raw
title description ms.custom ms.date ms.reviewer ms.topic author ms.author
Call external services with the HttpClient data type
Learn about how to call external services using the HttpClient datatype.
bap-template
01/08/2024
jswymer
conceptual
kennienp
kepontop

Call external services with the HttpClient data type

You can integrate [!INCLUDEprod_short] apps/extensions with external systems by using the HttpClient data type in your AL code.

:::image type="content" source="media/httpclient.svg" alt-text="Shows how AL apps/extensions can call external web services from Business Central" lightbox="media/httpclient.svg":::

The HttpClient data type is simply a wrapper on the .NET class HttpClient.

In this article, you learn how to make HTTP requests using the HttpClient data type and handle responses using the HttpResponseMessage data type.

Set up an external call

The first thing you need to do is to define the HTTP request, that is, which URI to call, set request and content HTTP headers, and choose which HTTP method to use. You do this using the HttpRequestMessage data type.

The following example illustrates ways to prepare the request.

    local procedure SendRequest(HttpMethod: Text[6]) ResponseText: Text
    var
        Client: HttpClient;
        HttpRequestMessage: HttpRequestMessage;
        RequestHeaders: HttpHeaders;
        RequestURI: Text;
        Content: HttpContent;
        ContentHeaders: HttpHeaders;
    begin
        RequestURI := 'https://httpcats.com/418.json';

        // This shows how you can set or change HTTP content headers in your request
        Content.GetHeaders(ContentHeaders);
        if ContentHeaders.Contains('Content-Type') then ContentHeaders.Remove('Content-Type');
        ContentHeaders.Add('Content-Type', 'multipart/form-data;boundary=boundary');

        // This shows how you can set HTTP request headers in your request
        HttpRequestMessage.GetHeaders(RequestHeaders);
        RequestHeaders.Add('Accept', 'application/json');
        RequestHeaders.Add('Accept-Encoding', 'utf-8');
        RequestHeaders.Add('Connection', 'Keep-alive');

        HttpRequestMessage.SetRequestUri(RequestURI);
        HttpRequestMessage.Method(HttpMethod);

        // from here on, the method must deal with calling out to the external service. 
        // see example code snippets below
    end;

For more information about content headers, see HttpContent data type.

Run the call

When you have set up the request, it's time to call out using a supported HTTP method.

[!INCLUDEhttpCallErrors]

The following example shows how to call an external web service from AL. It also illustrates the error handling you need to setup for handling errors when sending the request.

    local procedure GetRequest() ResponseText: Text
    var
        Client: HttpClient;
        Response: HttpResponseMessage;
        IsSuccessful: Boolean;
        ServiceCallErr: Label 'Web service call failed.';
        ErrorInfoObject: ErrorInfo;
    begin
        // assume you have setup the request here

        IsSuccessful := Client.Get('https://httpcats.com/418.json', Response);

        if not IsSuccessful then begin
            ErrorInfoObject.DetailedMessage := 'Sorry, we could not retrieve the cat info right now.';
            ErrorInfoObject.Message := ServiceCallErr;
            Error(ErrorInfoObject);
        end;
    end;

[!INCLUDEallowhttpclientnote]

Supported HTTP methods

[!INCLUDESupportedHTTPmethods]

Parsing the result

If the HttpClient call succeeds, you get a response back from the service you called. The response is saved in the data type HttpResponseMessage, where you can parse it to use the information in your app. The service call itself might not succeed, so make sure that you check the HTTP status code in your AL code.

The following example illustrates the error handling you need to setup for handling errors from the service that you called.

    local procedure GetRequest() ResponseText: Text
    var
        Client: HttpClient;
        IsSuccessful: Boolean;
        ServiceCallErr: Label 'Web service call failed.';
        ErrorInfoObject: ErrorInfo;
    begin
        IsSuccessful := Client.Get('https://httpcats.com/418.json', HttpResponseMessage);

        if not IsSuccessful then begin
            // handle the error
        end;

        if not HttpResponseMessage.IsSuccessStatusCode() then begin
            HttpStatusCode := HttpResponseMessage.HttpStatusCode();
            ErrorInfoObject.DetailedMessage := 'Sorry, we could not retrieve the cat info right now. ';
            ErrorInfoObject.Message := Format(ServiceStatusErr, HttpStatusCode, HttpResponseMessage.ReasonPhrase());
            Error(ErrorInfoObject);
        end;

        HttpResponseMessage.Content().ReadAs(ResponseText);
    end;

HTTP status codes

[!INCLUDEhttpStatusCodes]

Common HTTP status error codes

[!INCLUDEhttpStatusErrorCodes]

Advanced scenarios

Using cookies

Starting from 2024 release wave 1, you can use server-side cookies when calling an external service using HttpClient This allows you to efficiently send and receive cookies in HTTP requests, unblocking scenarios where third-party endpoints require cookie customization. With the Cookie datatype and AL methods for handling cookies, you can automatically re-use response cookies, handle cookies manually, or a mix of both.

Using certificates

It's possible to include a certificate when calling an external service using HttpClient.

[!INCLUDEhttpclient_cert_example]

[!INCLUDEhttpclient_cert_note]

For more information about certificates, see

Which IP addresses or ranges does my environment use?

When you exchange data through external services, you might have to safelist the IP addresses from where the [!INCLUDEprod_short] service is running.

For more information, see

Monitor and troubleshoot

[!INCLUDEhttpclientTelemetry]

Application Insights

You can set up [!INCLUDEprod_short] to send telemetry traces to an Application Insights resource in Azure. Once set up, telemetry data is sent to the resource when web services are called using the HttpClient data type. For more information, see, Analyzing outgoing web service request telemetry.

Troubleshoot errors

[!INCLUDEhttpclientErrors]

Performance considerations

[!INCLUDEhttpclientPerformance]

See also

Supported cipher suites in HTTPS
How-to restrict network access from/to Business Central
HttpClient data type
HttpContent data type
Analyzing outgoing web service request telemetry
Developing extensions
Get started with AL