コンテンツにスキップ

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 メソッドを使用することで、任意のリクエストヘッダを追加できます。

httpClient.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 メソッドを使用することで、任意のレスポンスヘッダのプロパティ値を取得することができます。

httpClient.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メソッドを発行し結果を受け取ります。

1.5.10.0

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とリダイレクトの扱いを追加

関連情報