Codeunit 2350 Rest Client
src/System Application/App/Rest Client/src/RestClient.Codeunit.al420 lines, Copyright (c) Microsoft Corporation. MIT
// ------------------------------------------------------------------------------------------------// Copyright (c) Microsoft Corporation. All rights reserved.// Licensed under the MIT License. See License.txt in the project root for license information.// ------------------------------------------------------------------------------------------------namespace System.RestClient;/// <summary>Provides functionality to easily work with the HttpClient object.</summary>codeunit 2350 "Rest Client"{ Access = Public; InherentEntitlements = X; InherentPermissions = X; var RestClientImpl: Codeunit "Rest Client Impl."; #region Constructors /// <summary>Initializes a new instance of the Rest Client class.</summary> /// <returns>The Rest Client object.</returns> /// <remarks>The default Http Client Handler and anonymous Http authentication will be used.</remarks> procedure Create(): Codeunit "Rest Client" begin RestClientImpl := RestClientImpl.Create(); exit(this); end; /// <summary>Initializes a new instance of the Rest Client class.</summary> /// <param name="HttpClientHandler">The Http Client Handler to use.</param> /// <returns>The Rest Client object.</returns> /// <remarks>The anynomous Http Authentication will be used.</remarks> procedure Create(HttpClientHandler: Interface "Http Client Handler"): Codeunit "Rest Client" begin RestClientImpl := RestClientImpl.Create(HttpClientHandler); exit(this); end; /// <summary>Initializes a new instance of the Rest Client class.</summary> /// <param name="HttpAuthentication">The authentication to use.</param> /// <returns>The Rest Client object.</returns> /// <remarks>The default Http Client Handler will be used.</remarks> procedure Create(HttpAuthentication: Interface "Http Authentication"): Codeunit "Rest Client" begin RestClientImpl := RestClientImpl.Create(HttpAuthentication); exit(this); end; /// <summary>Initializes a new instance of the Rest Client class.</summary> /// <param name="HttpClientHandler">The Http Client Handler to use.</param> /// <param name="HttpAuthentication">The authentication to use.</param> /// <returns>The Rest Client object.</returns> procedure Create(HttpClientHandler: Interface "Http Client Handler"; HttpAuthentication: Interface "Http Authentication"): Codeunit "Rest Client" begin RestClientImpl := RestClientImpl.Create(HttpClientHandler, HttpAuthentication); exit(this); end; #endregion #region Initialization /// <summary>Initializes the Rest Client with the default Http Client Handler and anonymous Http authentication.</summary> procedure Initialize() begin RestClientImpl.Initialize(); end; /// <summary>Initializes the Reest Client with the given Http Client Handler</summary> /// <param name="HttpClientHandler">The Http Client Handler to use.</param> /// <remarks>The anynomous Http Authentication will be used.</remarks> procedure Initialize(HttpClientHandler: Interface "Http Client Handler") begin RestClientImpl.Initialize(HttpClientHandler); end; /// <summary>Initializes the Rest Client with the given Http Authentication.</summary> /// <param name="HttpAuthentication">The authentication to use.</param> /// <remarks>The default Http Client Handler will be used.</remarks> procedure Initialize(HttpAuthentication: Interface "Http Authentication") begin RestClientImpl.Initialize(HttpAuthentication); end; /// <summary>Initializes the Rest Client with the given Http Client Handler and Http Authentication.</summary> /// <param name="HttpClientHandler">The Http Client Handler to use.</param> /// <param name="HttpAuthentication">The authentication to use.</param> procedure Initialize(HttpClientHandler: Interface "Http Client Handler"; HttpAuthentication: Interface "Http Authentication") begin RestClientImpl.Initialize(HttpClientHandler, HttpAuthentication); end; /// <summary>Sets a new value for an existing default header of the Http Client object, or addds the header if it does not already exist.</summary> /// <param name="Name">The name of the request header.</param> /// <param name="Value">The header of request header.</param> /// <remarks>Default request headers will be added to every request that is sent with this Rest Client instance /// The Rest Client will be initialized if it was not initialized before.</remarks> procedure SetDefaultRequestHeader(Name: Text; Value: Text) begin RestClientImpl.SetDefaultRequestHeader(Name, Value); end; /// <summary>Sets a new value for an existing default header of the Http Client object, or addds the header if it does not already exist.</summary> /// <param name="Name">The name of the request header.</param> /// <param name="Value">The header of request header.</param> /// <remarks>Default request headers will be added to every request that is sent with this Rest Client instance /// The Rest Client will be initialized if it was not initialized before.</remarks> procedure SetDefaultRequestHeader(Name: Text; Value: SecretText) begin RestClientImpl.SetDefaultRequestHeader(Name, Value); end; /// <summary>Sets the base address of the Rest Client.</summary> /// <remarks>The base address will be used for every request that is sent with this Rest Client instance. /// Calls to the Get, Post, Patch, Put and Delete methods must use a relative path which will be appended to the base address. /// The Rest Client will be initialized if it was not initialized before.</remarks> /// <param name="Url">The base address to use.</param> procedure SetBaseAddress(Url: Text) begin RestClientImpl.SetBaseAddress(Url); end; /// <summary>Gets the base address of the Rest Client.</summary> /// <returns>The base address of the Rest Client.</returns> procedure GetBaseAddress() Url: Text begin Url := RestClientImpl.GetBaseAddress(); end; /// <summary>Sets the timeout of the Rest Client.</summary> /// <param name="Timeout">The timeout to use.</param> /// <remarks>The timeout will be used for every request that is sent with this Rest Client instance. /// The Rest Client will be initialized if it was not initialized before.</remarks> procedure SetTimeOut(Timeout: Duration) begin RestClientImpl.SetTimeOut(Timeout); end; /// <summary>Gets the timeout of the Rest Client.</summary> /// <returns>The timeout of the Rest Client.</returns> procedure GetTimeOut() Timeout: Duration begin Timeout := RestClientImpl.GetTimeOut(); end; /// <summary>Adds a certificate to the Rest Client.</summary> /// <param name="Certificate">The Base64 encoded certificate</param> /// <remarks>The certificate will be used for every request that is sent with this Rest Client instance. /// The Rest Client will be initialized if it was not initialized before.</remarks> procedure AddCertificate(Certificate: Text) begin RestClientImpl.AddCertificate(Certificate); end; /// <summary>Adds a certificate to the Rest Client.</summary> /// <param name="Certificate">The Base64 encoded certificate</param> /// <param name="Password">The password of the certificate</param> /// <remarks>The certificate will be used for every request that is sent with this Rest Client instance. /// The Rest Client will be initialized if it was not initialized before.</remarks> procedure AddCertificate(Certificate: Text; Password: SecretText) begin RestClientImpl.AddCertificate(Certificate, Password); end; /// <summary>Sets the use of server certificate validation.</summary> /// <param name="Value">If true, the server certificate validation is enabled. False to disable</param> /// <remarks>Use this function to enable or disable the server certificate validation. /// The Rest Client will be initialized if it was not initialized before.</remarks> procedure SetUseServerCertificateValidation(Value: Boolean) begin RestClientImpl.SetUseServerCertificateValidation(Value); end; /// <summary>Sets the user agent header of the Rest Client.</summary> /// <remarks>Use this function to overwrite the default User-Agent header. /// The default user agent header is "Dynamics 365 Business Central - |[Publisher]| [App Name]/[App Version]". /// The Rest Client will be initialized if it was not initialized before.</remarks> /// <param name="Value">The user agent header to use.</param> procedure SetUserAgentHeader(Value: Text) begin RestClientImpl.SetUserAgentHeader(Value); end; /// <summary>Sets the authorization header of the Rest Client.</summary> /// <remarks>Use this function to set the authorization header. /// The Rest Client will be initialized if it was not initialized before.</remarks> /// <param name="Value">The authorization header to use.</param> procedure SetAuthorizationHeader(Value: SecretText) begin RestClientImpl.SetAuthorizationHeader(Value); end; /// <summary>Sets the use of response cookies in subsequent requests.</summary> /// <remarks>Use this function to enable or disable automatically attach cookies received in the response to all subsequent requests. /// The Rest Client will be initialized if it was not initialized before.</remarks> /// <param name="Value">If true, the client automatically attaches cookies received in the response to all subsequent requests. False to disable</param> procedure SetUseResponseCookies(Value: Boolean) begin RestClientImpl.SetUseResponseCookies(Value); end; #endregion #region BasicMethods /// <summary>Sends a GET request to the specified Uri and returns the response message.</summary> /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received. /// If a response was received, then the response message object contains information about the status.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <returns>The response message object</returns> procedure Get(RequestUri: Text) HttpResponseMessage: Codeunit "Http Response Message" begin HttpResponseMessage := Send(Enum::"Http Method"::GET, RequestUri); end; /// <summary>Sends a POST request to the specified Uri and returns the response message.</summary> /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received. /// If a response was received, then the response message object contains information about the status.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send.</param> /// <returns>The response message object</returns> procedure Post(RequestUri: Text; Content: Codeunit "Http Content") HttpResponseMessage: Codeunit "Http Response Message" begin HttpResponseMessage := Send(Enum::"Http Method"::POST, RequestUri, Content); end; /// <summary>Sends a PATCH request to the specified Uri and returns the response message.</summary> /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received. /// If a response was received, then the response message object contains information about the status.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send.</param> /// <returns>The response message object</returns> procedure Patch(RequestUri: Text; Content: Codeunit "Http Content") HttpResponseMessage: Codeunit "Http Response Message" begin HttpResponseMessage := Send(Enum::"Http Method"::PATCH, RequestUri, Content); end; /// <summary>Sends a PUT request to the specified Uri and returns the response message.</summary> /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received. /// If a response was received, then the response message object contains information about the status.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send.</param> /// <returns>The response message object</returns> procedure Put(RequestUri: Text; Content: Codeunit "Http Content") HttpResponseMessage: Codeunit "Http Response Message" begin HttpResponseMessage := Send(Enum::"Http Method"::PUT, RequestUri, Content); end; /// <summary>Sends a DELETE request to the specified Uri and returns the response message.</summary> /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received. /// If a response was received, then the response message object contains information about the status.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <returns>The response message object</returns> procedure Delete(RequestUri: Text) HttpResponseMessage: Codeunit "Http Response Message" begin HttpResponseMessage := Send(Enum::"Http Method"::DELETE, RequestUri); end; #endregion #region BasicMethodsAsJson /// <summary>Sends a GET request to the specified Uri and returns the response content as JsonToken.</summary> /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received. /// The function also fails with a collectible error in case the response does not contain a success status code. /// In case the response contains no content, an empty JsonToken is returned. /// In case the response contains content, then the function fails with a collectible error if the content is invalid JSON.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <returns>The response content as JsonToken</returns> procedure GetAsJson(RequestUri: Text) JsonToken: JsonToken begin JsonToken := RestClientImpl.GetAsJson(RequestUri); end; /// <summary>Sends a POST request to the specified Uri and returns the response content as JsonToken.</summary> /// <remarks>The function fails with an error message if the request could not be sent or a response was not received. /// The function also fails with a collectible error in case the response does not contain a success status code. /// In case the response contains no content, an empty JsonToken is returned. /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send as a JsonObject.</param> /// <returns>The response content as JsonToken</returns> procedure PostAsJson(RequestUri: Text; Content: JsonObject) Response: JsonToken begin Response := PostAsJson(RequestUri, Content.AsToken()); end; /// <summary>Sends a POST request to the specified Uri and returns the response content as JsonToken.</summary> /// <remarks>The function fails with an error message if the request could not be sent or a response was not received. /// The function also fails with a collectible error in case the response does not contain a success status code. /// In case the response contains no content, an empty JsonToken is returned. /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send as a JsonArray.</param> /// <returns>The response content as JsonToken</returns> procedure PostAsJson(RequestUri: Text; Content: JsonArray) Response: JsonToken begin Response := PostAsJson(RequestUri, Content.AsToken()); end; /// <summary>Sends a POST request to the specified Uri and returns the response content as JsonToken.</summary> /// <remarks>The function fails with an error message if the request could not be sent or a response was not received. /// The function also fails with a collectible error in case the response does not contain a success status code. /// In case the response contains no content, an empty JsonToken is returned. /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send as a JsonToken.</param> /// <returns>The response content as JsonToken</returns> procedure PostAsJson(RequestUri: Text; Content: JsonToken) Response: JsonToken begin Response := RestClientImpl.PostAsJson(RequestUri, Content); end; /// <summary>Sends a PATCH request to the specified Uri and returns the response content as JsonToken.</summary> /// <remarks>The function fails with an error message if the request could not be sent or a response was not received. /// The function also fails with a collectible error in case the response does not contain a success status code. /// In case the response contains no content, an empty JsonToken is returned. /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send as a JsonObject.</param> /// <returns>The response content as JsonToken</returns> procedure PatchAsJson(RequestUri: Text; Content: JsonObject) Response: JsonToken begin Response := PatchAsJson(RequestUri, Content.AsToken()); end; /// <summary>Sends a PATCH request to the specified Uri and returns the response content as JsonToken.</summary> /// <remarks>The function fails with an error message if the request could not be sent or a response was not received. /// The function also fails with a collectible error in case the response does not contain a success status code. /// In case the response contains no content, an empty JsonToken is returned. /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send as a JsonArray.</param> /// <returns>The response content as JsonToken</returns> procedure PatchAsJson(RequestUri: Text; Content: JsonArray) Response: JsonToken begin Response := PatchAsJson(RequestUri, Content.AsToken()); end; /// <summary>Sends a PATCH request to the specified Uri and returns the response content as JsonToken.</summary> /// <remarks>The function fails with an error message if the request could not be sent or a response was not received. /// The function also fails with a collectible error in case the response does not contain a success status code. /// In case the response contains no content, an empty JsonToken is returned. /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send as a JsonToken.</param> /// <returns>The response content as JsonToken</returns> procedure PatchAsJson(RequestUri: Text; Content: JsonToken) Response: JsonToken begin Response := RestClientImpl.PatchAsJson(RequestUri, Content); end; /// <summary>Sends a PUT request to the specified Uri and returns the response content as JsonToken.</summary> /// <remarks>The function fails with an error message if the request could not be sent or a response was not received. /// The function also fails with a collectible error in case the response does not contain a success status code. /// In case the response contains no content, an empty JsonToken is returned. /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send as a JsonObject.</param> /// <returns>The response content as JsonToken</returns> procedure PutAsJson(RequestUri: Text; Content: JsonObject) Response: JsonToken begin Response := PutAsJson(RequestUri, Content.AsToken()); end; /// <summary>Sends a PUT request to the specified Uri and returns the response content as JsonToken.</summary> /// <remarks>The function fails with an error message if the request could not be sent or a response was not received. /// The function also fails with a collectible error in case the response does not contain a success status code. /// In case the response contains no content, an empty JsonToken is returned. /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send as a JsonArray.</param> /// <returns>The response content as JsonToken</returns> procedure PutAsJson(RequestUri: Text; Content: JsonArray) Response: JsonToken begin Response := PutAsJson(RequestUri, Content.AsToken()); end; /// <summary>Sends a PUT request to the specified Uri and returns the response content as JsonToken.</summary> /// <remarks>The function fails with an error message if the request could not be sent or a response was not received. /// The function also fails with a collectible error in case the response does not contain a success status code. /// In case the response contains no content, an empty JsonToken is returned. /// In case the response contains content, then the function fails if the content is invalid JSON.</remarks> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send as a JsonToken.</param> /// <returns>The response content as JsonToken</returns> procedure PutAsJson(RequestUri: Text; Content: JsonToken) Response: JsonToken begin Response := RestClientImpl.PutAsJson(RequestUri, Content); end; #endregion #region GenericSendMethods /// <summary>Sends a request with the specific Http method and an empty content to the specified Uri and returns the response message.</summary> /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received. /// If a response was received, then the response message object contains information about the status.</remarks> /// <param name="Method">The HTTP method to use.</param> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <returns>The response message object</returns> procedure Send(Method: Enum "Http Method"; RequestUri: Text) HttpResponseMessage: Codeunit "Http Response Message" begin HttpResponseMessage := RestClientImpl.Send(Method, RequestUri); end; /// <summary>Sends a request with the specific Http method and the given content to the specified Uri and returns the response message.</summary> /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received. /// If a response was received, then the response message object contains information about the status.</remarks> /// <param name="Method">The HTTP method to use.</param> /// <param name="RequestUri">The Uri the request is sent to.</param> /// <param name="Content">The content to send.</param> /// <returns>The response message object</returns> procedure Send(Method: Enum "Http Method"; RequestUri: Text; Content: Codeunit "Http Content") HttpResponseMessage: Codeunit "Http Response Message" begin HttpResponseMessage := RestClientImpl.Send(Method, RequestUri, Content); end; /// <summary>Sends the given request message and returns the response message.</summary> /// <remarks>The function fails with a collectible error if the request could not be sent or a response was not received.</remarks> /// <param name="HttpRequestMessage">The request message to send.</param> /// <returns>The response message object</returns> procedure Send(var HttpRequestMessage: Codeunit "Http Request Message") HttpResponseMessage: Codeunit "Http Response Message" begin HttpResponseMessage := RestClientImpl.Send(HttpRequestMessage); end; #endregion}