httpClient
概要¶
サーバスクリプトで外部のサービスと接続するためのHTTPクライアントを利用する際に使用します。
プロパティ¶
| No | Name | Get | Set | Type | Description |
|---|---|---|---|---|---|
| 1 | RequestUri | ○ | ○ | string | 接続先のURI |
| 2 | Content | ○ | ○ | string | 送信するデータ |
| 3 | Encoding | ○ | ○ | string | エンコーディング(既定値は "utf-8") |
| 4 | MediaType | ○ | ○ | string | メディアの種類(既定値は "application/json") |
| 5 | RequestHeaders | ○ | Dictionary | リクエストヘッダ。詳細は下記参照。 | |
| 6 | ResponseHeaders | ○ | Dictionary | レスポンスヘッダ。詳細は下記参照。 | |
| 7 | IsSuccess | ○ | bool | 直前に発行したリクエストが成功したか否かを取得。StatusCodeが200~299の範囲にある場合にTrueを返します | |
| 8 | StatusCode | ○ | int | 直前に発行したリクエストに対する応答メッセージのステータスコード | |
| 9 | TimeOut | ○ | ○ | int | HTTPリクエストのタイムアウト時間をミリ秒で指定。 Script.json に記載された "ServerScriptHttpClientTimeOutMin" ~ "ServerScriptHttpClientTimeOutMax" の範囲で設定可能。 (既定値は、Script.json の "ServerScriptHttpClientTimeOut" に設定された値) |
| 10 | IsTimeOut | ○ | bool | 直前に発行したリクエストがタイムアウトで中断したか否かを取得。タイムアウトした場合にTrueを返します。 |
RequestHeadersプロパティの使用例¶
下記の様に、RequestHeadersプロパティの Add メソッドを使用することで、任意のリクエストヘッダを追加できます。
AuthorizationヘッダでBasic認証を行う場合¶
let base64 = utilities.ConvertToBase64String('userName:password');
httpClient.RequestHeaders.Add("Authorization", "Basic " + base64);
httpClient.RequestUri= "https://servername/api/.....";
let result = httpClient.Get();
※文字列をBase64に変換するには、utilities.ConvertToBase64Stringメソッドが利用可能です。
また、続けて別のヘッダを設定して送信する場合は、Clearメソッドでヘッダの内容をリセットしてください。
httpClient.RequestHeaders.Clear();
httpClient.RequestHeaders.Add("Authorization", "Bearer " + "X2kKRHGI495Y.......");
ResponseHeadersプロパティの使用例¶
下記のように外部APIにアクセスした際、ResponseHeadersプロパティの Item.get メソッドを使用することで、任意のレスポンスヘッダのプロパティ値を取得することができます。
Access-Control-Allow-Originプロパティの値をレスポンスヘッダから取得したい場合¶
// 外部APIに接続
httpClient.RequestUri="https://savername/api/......";
let response = httpClient.Get();
// レスポンスヘッダを取得
var value = httpClient.ResponseHeaders.Item.get("Access-Control-Allow-Origin");
context.Log(value[0]);
また、続けて送信しレスポンスヘッダのプロパティ値を取得する場合は、Clearメソッドであらかじめヘッダの内容をリセットしてください。
httpClient.RequestUri="https://savername/api/....../123/...";
let response = httpClient.Get();
var value = httpClient.ResponseHeaders.Item.get("Access-Control-Allow-Origin");
context.Log(value[0]);
// 続けて送信する前にResponseHeadersをクリア
httpClient.ResponseHeaders.Clear();
httpClient.RequestUri="https://savername/api/....../456/...";
response = httpClient.Get();
TimeOutプロパティの使用例¶
下記の例では、リクエストを送信する前に TimeOut プロパティに値を設定することで、リクエストのタイムアウト時間を変更できます。
httpClient.RequestUri= "https://servername/api/.....";
httpClient.TimeOut = 300000;
let result = httpClient.Get();
IsTimeOutプロパティの使用例¶
下記の例では、リクエストが失敗した場合に失敗した理由がタイムアウトかどうかを判定し、タイムアウトだった場合は再度HttpClientGetを実行します。
let response = httpClient.Get();
if (!httpClient.IsSuccess) { //リクエストに失敗した
if (httpClient.IsTimeOut) { //タイムアウトによる中断だった
response = httpClient.Get(); //リトライ
}
}
メソッド¶
| No | Name | Description |
|---|---|---|
| 1 | ClearCookies | 保持しているCookieを削除します。 |
| 2 | Delete | DELETEメソッドを発行し結果を受け取ります。 |
| 3 | Get | GETメソッドを発行し結果を受け取ります。 |
| 4 | Patch | PATCHメソッドを発行し結果を受け取ります。 |
| 5 | Post | POSTメソッドを発行し結果を受け取ります。 |
| 6 | Put | PUTメソッドを発行し結果を受け取ります。 |
Cookieとリダイレクトの扱い¶
1.5.10.0
Cookieを保持する範囲¶
httpClientは、応答で受け取ったCookie(Set-Cookieヘッダ)を保持し、以降のリクエストで自動的に送信します。このため、Cookieでログインの状態を管理する外部サービスにも、ログインした後に続けてアクセスできます。Cookieが保持されるのは、1回の処理(リクエスト)の間のみです。Cookieを保存しておく機能はありません。
| 状況 | Cookieの引き継ぎ |
|---|---|
| 同じスクリプトの中で、httpClientを続けて使用する | 引き継がれます |
| 同じ処理の中の別の条件(「作成前」と「作成後」など) | 引き継がれます |
| 別の画面操作・API呼び出しなど、別のリクエスト | 引き継がれません |
| items.Update()などで別のテーブルのレコードを更新したときに、そのテーブルで実行されるサーバスクリプト | 引き継がれません |
| バックグラウンドサーバスクリプト | 同じ実行の中では引き継がれ、別の実行には引き継がれません |
別のテーブルのサーバスクリプトで同じ外部サービスにアクセスする場合は、そのスクリプトの中でログインしてください。同じホストに別のアカウントで接続し直す場合は、ClearCookiesでCookieを削除してください。
ドメインが一致しないなど、不正なSet-Cookieヘッダは無視されます。応答の本文は通常どおり取得できます。
リダイレクト¶
300(Locationヘッダがある場合)・301・302・303・307・308の応答を受け取ると、リダイレクト先へ自動的にリクエストが送信されます。途中の応答で受け取ったCookieも保持されます。
- リダイレクトをたどる回数の上限は、Script.jsonの「ServerScriptHttpClientMaxRedirectCount」で指定します(既定値は50)。「0」を指定すると、リダイレクトをたどりません。上限に達した場合は、最後に受け取った応答(3xx)の本文が返されます。StatusCodeには3xxのステータスコードが、IsSuccessにはFalseが入ります。
- HTTPSからHTTPへのリダイレクトはたどりません。受け取った応答(3xx)の本文が返されます。
- 300・301・302をPOSTで受け取った場合と、303をGET・HEAD以外で受け取った場合は、GETに切り替えて送信します。本文は送信されません。307・308では、メソッドと本文を変えずに送信します。
- RequestHeadersで指定したAuthorizationヘッダは、リダイレクト先には送信されません。リダイレクト先が同じホストでも送信されません。
- 最初に指定したURLとホスト名またはポート番号が異なるURLへリダイレクトされた場合は、RequestHeadersで指定したCookieヘッダは送信されません。保持しているCookieのうち、リダイレクト先のホストに送信できるものが送信されます。
対応バージョン¶
| 対応バージョン | 内容 |
|---|---|
| 1.2.16.0以降 | HttpClientを追加 |
| 1.3.9.0以降 | RequestHeadersを追加 |
| 1.3.50.0以降 | HttpClientのPatchメソッドを追加 |
| 1.4.8.0以降 | ResponseHeadersを追加 |
| 1.4.19.0以降 | TImeOutを追加 |
| 1.4.20.0以降 | IsTImeOutを追加 |
| 1.5.10.0以降 | ClearCookiesを追加 Cookieとリダイレクトの扱いを追加 |
