Modifier

Partager via

HttpClient.Send(HttpRequestMessage, var HttpResponseMessage) Method

  • Article

Version: Available or changed with runtime version 1.0.

Sends an HTTP request as an asynchronous operation.

Syntax

[Ok := ]  HttpClient.Send(Request: HttpRequestMessage, var Response: HttpResponseMessage)

Parameters

HttpClient
 Type: HttpClient
An instance of the HttpClient data type.

Request
 Type: HttpRequestMessage
The HTTP request message to send.

Response
 Type: HttpResponseMessage
The response received from the remote endpoint.

Return Value

[Optional] Ok
 Type: Boolean
Accessing the HttpContent property of HttpResponseMessage in a case when the request fails will result in an error. If you omit this optional return value and the operation does not execute successfully, a runtime error will occur.

Ways that HttpClient.Send calls can fail

The method HttpClient.Send can fail and return false in the following ways:

  • The requestUri is not an absolute URI.
  • The chosen HTTP method is not supported.
  • The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout.
  • The request failed due to timeout.

Important

Outbound HTTP calls from apps/extensions are blocked by default and must be approved for each extension, otherwise instead of an external call, the system will display the following error message: The request was blocked by the runtime to prevent accidental use of production services.

To enable outbound HTTP calls, go to the Extension Management page in Business Central, and choose Configure. Then, on the Extension Settings page, make sure that Allow HttpClient Requests is selected. This setting must be enabled for each app/extension, including library apps.

Example (HTTP PATCH)

As an example of how to use the HttpClient.Send, we illustrate how to do a HTTP PATCH request. Examples of the other supported HTTP methods (DELETE, GET, POST, or PUT), see the respective articles for their methods (HttpClient.Delete, HttpClient.Get, HttpClient.Post, or HttpClient.Put).

The PATCH request is a partial update to an existing resource. It doesn't create a new resource, and it's not intended to replace an existing resource. Instead, it updates a resource only partially. To make an HTTP PATCH request, given an HttpClient and a URI, use the HttpClient.Send method:

local procedure PatchRequest(json: Text) ResponseText: Text
var
    Client: HttpClient;
    Content: HttpContent;
    ContentHeaders: HttpHeaders;
    RequestMessage: HttpRequestMessage;        
    Response: HttpResponseMessage;
    IsSuccessful: Boolean;
begin
    Content.GetHeaders(ContentHeaders);

    if ContentHeaders.Contains('Content-Type') then ContentHeaders.Remove('Content-Type');
    ContentHeaders.Add('Content-Type', 'application/json');

    if ContentHeaders.Contains('Content-Encoding') then ContentHeaders.Remove('Content-Encoding');
    ContentHeaders.Add('Content-Encoding', 'UTF8');

    // assume that the json parameter contains the following data
    //
    // {
    //    title = "updated title",
    //    completed = true
    // }
    Content.WriteFrom(json);

    RequestMessage.SetRequestUri('https://jsonplaceholder.typicode.com/todos/1');
    RequestMessage.Method('PATCH');
    RequestMessage.Content(Content);

    IsSuccessful := Client.Send(RequestMessage, Response);

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

    if not Response.IsSuccessStatusCode() then begin
        HttpStatusCode := Response.HttpStatusCode();
        // handle the error (depending on the HTTP status code)
    end;

    Response.Content().ReadAs(ResponseText);

    // Expected output
    //   PATCH https://jsonplaceholder.typicode.com/todos/1 HTTP/1.1
    //   {
    //     "userId": 1,
    //     "id": 1,
    //     "title": "updated title",
    //     "completed": true
    //   }
end;

The preceding code:

  • Prepares a HttpContent instance with the JSON body of the request (MIME type of "application/json" and using the character encoding UTF8).
  • Makes a PATCH request to "https://jsonplaceholder.typicode.com/todos/1".
  • Ensures that the response is successful.
  • Reads the response body as a string.

Content headers

By default, the content headers contain a header for 'Content-Type', namely 'text/plain; charset=utf-8'. This is important to adjust if the endpoint you're calling expects a different content type, for example, multipart/form-data or application/json.

The following AL code examples illustrate ways to change the content header.

    local procedure SendRequest(HttpMethod: Text[6]) ResponseText: Text
    var
        Client: HttpClient;
        Content: HttpContent;
        ContentHeaders: HttpHeaders;
    begin
        Content.GetHeaders(ContentHeaders);

        // If you want to set all the headers yourself, do it this way
        ContentHeaders.Clear();
        ContentHeaders.Add('Content-Type', 'multipart/form-data;boundary=boundary');

        // from here on, the method must deal with calling out to the external service. 
    end;

    local procedure SendRequest(HttpMethod: Text[6]) ResponseText: Text
    var
        Client: HttpClient;
        Content: HttpContent;
        ContentHeaders: HttpHeaders;
    begin
        Content.GetHeaders(ContentHeaders);

        // In this example, you just change the headers you need
        if ContentHeaders.Contains('Content-Type') then ContentHeaders.Remove('Content-Type');
        ContentHeaders.Add('Content-Type', 'multipart/form-data;boundary=boundary');

        // from here on, the method must deal with calling out to the external service. 
    end;

When calling an endpoint, 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. In the case of setting the wrong content type header, you'll typically receive the 415 Unsupported Media Type return code. This return code can also be due to the request's Content-Encoding header, or if the data you send doesn't match what the endpoint expects.

Supported HTTP methods

The HttpClient datatype supports the following HTTP methods:

  • DELETE
  • GET
  • PATCH
  • POST
  • PUT

The following table includes links to help you get started with calling external services using different HTTP methods.

To See
Dynamically set the HTTP method from AL, set it on the HttpRequestMessage datatype and use the HttpClient.Send method to call the service. HttpClient.Send(HttpRequestMessage, var HttpResponseMessage) Method
HttpRequestMessage.Method([Text]) Method
Delete data in a service endpoint using the HTTP DELETE method. HttpClient.Delete(Text, var HttpResponseMessage) Method
Read data from a service endpoint using the HTTP GET method. HttpClient.Get(Text, var HttpResponseMessage) Method
Update data in a service endpoint using the HTTP PATCH method (no specific AL method exists for PATCH, so use HttpClient.Send). HttpClient.Send(Text, HttpContent, var HttpResponseMessage) Method
Send data to a service endpoint using the HTTP POST method. HttpClient.Post(Text, HttpContent, var HttpResponseMessage) Method
Send data to a service endpoint using the HTTP PUT method. HttpClient.Put(Text, HttpContent, var HttpResponseMessage) Method

Call external services with the HttpClient data type
HttpClient Data Type
Get Started with AL
Developing Extensions