httpClient
Overview¶
Used when using an HTTP client to connect to an external service in a "Server Script".
Properties¶
| No | Name | Get | Set | Type | Description |
|---|---|---|---|---|---|
| 1 | RequestUri | Yes | Yes | string | The URI of the destination |
| 2 | Content | Yes | Yes | string | Data to send |
| 3 | Encoding | Yes | Yes | string | Encoding (default is "utf-8") |
| 4 | MediaType | Yes | Yes | string | Media type (default is "application/json") |
| 5 | RequestHeaders | Yes | No | Dictionary | Request header. See below for more details. |
| 6 | ResponseHeaders | Yes | No | Dictionary | Response header. See below for more details. |
| 7 | IsSuccess | Yes | No | bool | Get whether the most recent request was successful. Returns True if the StatusCode is within the range of 200-299. |
| 8 | StatusCode | Yes | No | int | Status code of the response message for the most recent request. |
| 9 | TimeOut | Yes | Yes | int | Specify the timeout of the HTTP request in milliseconds. It can be set within the range from "ServerScriptHttpClientTimeOutMin" to "ServerScriptHttpClientTimeOutMax" in Script.json. (The default value is the value set in "ServerScriptHttpClientTimeOut" in Script.json.) |
| 10 | IsTimeOut | Yes | No | bool | Get whether the most recent request was aborted by a timeout. Returns True if it timed out. |
Example Usage of RequestHeaders Property¶
You can add any request header by using the Add method of the RequestHeaders property as shown below.
Basic Authentication with Authorization Header¶
let base64 = utilities.ConvertToBase64String('userName:password');
httpClient.RequestHeaders.Add("Authorization", "Basic " + base64);
httpClient.RequestUri= "https://servername/api/.....";
let result = httpClient.Get();
*To convert a string to Base64, you can use the "utilities.ConvertToBase64String" method.
Also, if you want to set another header and send it subsequently, reset the header content with the Clear method.
httpClient.RequestHeaders.Clear();
httpClient.RequestHeaders.Add("Authorization", "Bearer " + "X2kKRHGI495Y.......");
Example Usage of ResponseHeaders Property¶
When accessing an external API as shown below, you can get the value of any response header property by using the Item.get method of the ResponseHeaders property.
Getting the Value of the Access-Control-Allow-Origin Property from the Response Header¶
// Connect to the external API
httpClient.RequestUri="https://savername/api/......";
let response = httpClient.Get();
// Get the response header
var value = httpClient.ResponseHeaders.Item.get("Access-Control-Allow-Origin");
context.Log(value[0]);
Also, if you want to send another request subsequently and get the property value of the response header, reset the header content with the Clear method beforehand.
httpClient.RequestUri="https://savername/api/....../123/...";
let response = httpClient.Get();
var value = httpClient.ResponseHeaders.Item.get("Access-Control-Allow-Origin");
context.Log(value[0]);
// Clear ResponseHeaders before sending the next request
httpClient.ResponseHeaders.Clear();
httpClient.RequestUri="https://savername/api/....../456/...";
response = httpClient.Get();
Example Usage of TimeOut Property¶
In the following example, you can change the timeout period of the request by setting a value to the TimeOut property before sending the request.
httpClient.RequestUri= "https://servername/api/.....";
httpClient.TimeOut = 300000;
let result = httpClient.Get();
Example Usage of IsTimeOut Property¶
In the following example, if the request fails, it determines whether the reason for the failure was a timeout, and if so, executes httpClient.Get again.
let response = httpClient.Get();
if (!httpClient.IsSuccess) { // The request failed
if (httpClient.IsTimeOut) { // It was interrupted by a timeout
response = httpClient.Get(); // Retry
}
}
Methods¶
| No | Name | Description |
|---|---|---|
| 1 | ClearCookies | Delete the cookies that are held. |
| 2 | Delete | Issue the DELETE method and receive the results. |
| 3 | Get | Issue the GET method and receive the results. |
| 4 | Patch | Issue the PATCH method and receive the results. |
| 5 | Post | Issue the POST method and receive the results. |
| 6 | Put | Issue the PUT method and receive the results. |
Handling of Cookies and Redirects¶
1.5.10.0
Scope in Which Cookies Are Held¶
httpClient holds the cookies received in responses (Set-Cookie headers) and automatically sends them in subsequent requests. This allows you to continue accessing an external service that manages the login state with cookies after logging in. Cookies are held only during a single process (request). There is no function to save cookies.
| Situation | Carrying over cookies |
|---|---|
| Using httpClient repeatedly in the same script | Carried over |
| Another condition in the same process (such as "Before create" and "After create") | Carried over |
| Another request, such as another screen operation or API call | Not carried over |
| A server script that runs in another table when a record in that table is updated with items.Update() or similar | Not carried over |
| Background Server Script | Carried over within the same run, and not carried over to another run |
When a server script in another table accesses the same external service, log in within that script. To connect to the same host again with another account, delete the cookies with ClearCookies.
Invalid Set-Cookie headers, such as those whose domain does not match, are ignored. The response body can be obtained as usual.
Redirects¶
When a response of 300 (if there is a Location header), 301, 302, 303, 307, or 308 is received, a request is automatically sent to the redirect destination. Cookies received in intermediate responses are also held.
- The maximum number of redirects to follow is specified with "ServerScriptHttpClientMaxRedirectCount" in Script.json (the default value is 50). If "0" is specified, redirects are not followed. When the maximum is reached, the body of the last response received (3xx) is returned. StatusCode contains the 3xx status code, and IsSuccess contains False.
- Redirects from HTTPS to HTTP are not followed. The body of the response received (3xx) is returned.
- When 300, 301, or 302 is received for POST, and when 303 is received for a method other than GET or HEAD, the request is switched to GET. The body is not sent. For 307 and 308, the request is sent without changing the method and body.
- The Authorization header specified with RequestHeaders is not sent to the redirect destination, even if the destination is the same host.
- When redirected to a URL whose host name or port number differs from the URL specified first, the Cookie header specified with RequestHeaders is not sent. Of the cookies held, those that can be sent to the host of the redirect destination are sent.
Supported Versions¶
| Supported versions | Body |
|---|---|
| 1.2.16.0 and later | Added HttpClient |
| 1.3.9.0 and later | Added RequestHeaders |
| 1.3.50.0 and later | Added the Patch method of HttpClient |
| 1.4.8.0 and later | Added ResponseHeaders |
| 1.4.19.0 and later | Added TimeOut |
| 1.4.20.0 and later | Added IsTimeOut |
| 1.5.10.0 and later | Added ClearCookies Added the handling of cookies and redirects |