スクリプトタスクでは、httpClient オブジェクトを使って外部の Web API に HTTP リクエストを送ることができます。この記事では、GET リクエストと POST リクエストの基本的な書き方をサンプルコードとともに解説します。
GET リクエスト
httpClient.begin() でリクエストを組み立て、.get(url) で送信します。
const url = "https://api.example.com/items";
const response = httpClient.begin()
.get(url);
const statusCode = response.getStatusCode();
const body = response.getResponseAsString();
engine.log("ステータスコード: " + statusCode);
engine.log("レスポンス: " + body);クエリパラメータを付ける
クエリパラメータは URL 文字列に直接付加するか、.queryParam() で指定します。
// URL に直接付加する場合
const url = "https://api.example.com/items?category=book&limit=10";
// queryParam() で指定する場合
const response = httpClient.begin()
.queryParam("category", "book")
.queryParam("limit", "10")
.get("https://api.example.com/items");JSON レスポンスを解析する
レスポンスが JSON の場合、JSON.parse() でオブジェクトに変換できます。
const response = httpClient.begin()
.get("https://api.example.com/items");
const json = JSON.parse(response.getResponseAsString());
const items = json.items || [];
engine.log("件数: " + items.length);POST リクエスト
.body() でリクエストボディを指定し、.post(url) で送信します。
const payload = JSON.stringify({
name: "新しいアイテム",
value: 100
});
const response = httpClient.begin()
.body(payload, "application/json")
.post("https://api.example.com/items");
const statusCode = response.getStatusCode();
engine.log("ステータスコード: " + statusCode);フォーム形式で送る場合
application/x-www-form-urlencoded 形式で送る場合は、.formParam() を使います。
const response = httpClient.begin()
.formParam("name", "新しいアイテム")
.formParam("value", "100")
.post("https://api.example.com/items");認証が必要な場合
OAuth などの認証が必要な API を呼び出す場合は、まず httpClient.findAuthSetting() で HTTP 認証設定を取得し、それを .authSetting() に渡します。
// 第 2 引数は全アプリ共有設定の場合 true、アプリ個別設定の場合 false
const setting = httpClient.findAuthSetting("設定名", false);
const response = httpClient.begin()
.authSetting(setting)
.get("https://api.example.com/items");HTTP 認証設定の作成方法については「HTTP 認証設定について理解する」を参照してください。
レスポンスの確認とエラー処理
ステータスコードで成功・失敗を判定し、想定外の場合は例外をスローすることが推奨されます。200（OK）以外にも 201（Created）・204（No Content）などの成功レスポンスがあるため、200 番台かどうかで判定するのが汎用的です。
const response = httpClient.begin()
.get("https://api.example.com/items");
const statusCode = response.getStatusCode();
if (statusCode < 200 || statusCode >= 300) {
// 失敗時は本文もログに残しておくとデバッグしやすい
engine.log("エラーレスポンス: " + response.getResponseAsString());
throw new Error("API リクエストが失敗しました。ステータスコード: " + statusCode);
}
const body = response.getResponseAsString();成功時に許容するステータスコードは API の仕様に合わせて調整してください。冪等な GET なら 200 のみ、リソース作成系の POST なら 201 も含める、といった選び方をします。
engine.log() を活用してレスポンス内容をログに出力しておくと、デバッグ時に原因を特定しやすくなります。ログの使い方については「ログ出力を使用する」を参照してください。
実践例：外部 API からデータを取得してデータ項目に書き込む
商品 ID（文字型）を読み取り、外部 API から商品名と価格を取得して、それぞれのデータ項目に書き込む例です。
// 商品 ID を取得
const productId = engine.findDataByVarName("q_product_id");
if (productId === null) {
throw new Error("商品 ID が入力されていません");
}
// 外部 API を呼び出す
const url = "https://api.example.com/products/" + encodeURIComponent(productId);
const response = httpClient.begin()
.get(url);
const statusCode = response.getStatusCode();
if (statusCode < 200 || statusCode >= 300) {
engine.log("エラーレスポンス: " + response.getResponseAsString());
throw new Error("商品情報の取得に失敗しました。ステータスコード: " + statusCode);
}
// レスポンスを解析してデータ項目に書き込む
const product = JSON.parse(response.getResponseAsString());
engine.setDataByVarName("q_product_name", product.name);
engine.setDataByVarName("q_product_price", new java.math.BigDecimal(String(product.price)));設計上の注意
スクリプトタスクの実行時間は 最大 30 秒 です。外部 API のレスポンスが遅い場合や、ループ内で複数回リクエストを送る場合は、この制限に注意してください。
また、1 回の実行につき HTTP リクエストは 最大 10 回 までという制限もあります。
関連リファレンス
- HTTP 認証設定について理解する — OAuth などの認証設定の作成方法
- ログ出力を使用する — engine.log() を使ったデバッグ方法
- スクリプトタスクでデータ項目の値を参照・更新する — データ項目の読み書き方法
