スクリプト

Configure Connector Builder scripts that run JavaScript before or after API requests, for every request in a connector or for a single resource, and the order in which they run.

Connector Builder lets you write JavaScript that runs before or after the API requests made by your connector. Use pre-request scripts to modify outgoing requests and post-request scripts to process incoming responses. Scripts on the Global Scripts tab run for every request the connector makes, and scripts on a resource's Scripts tab run only for that resource.

When to use scripts

Scripts are useful when you need to customize how your connector calls the provider, such as:

• 送信前に要求ヘッダー、パラメーター、または本文を挿入または上書きする
• 構成値に基づいてベンダー URL を動的に構築する
• ベンダーの応答本文をワークフローに返す前の変換
• ベンダーの API を呼び出さずにカスタム条件に基づいて要求を停止する

単一リソースのスクリプト

また、各リソースには専用の [ スクリプト ] タブがあり、[ パラメーター]、[ 要求] フィールド、[ 応答] フィールド、 アクティビティ デザイナーのほかにあります。コネクタ レベルの [グローバル スクリプト] タブと同じ [要求前スクリプト] エディターと [要求後] スクリプト エディター、同じスニペット、同じ変数done()コントラクトを提供します。

違いはスコープです。

• [ グローバル スクリプト ] タブのスクリプトは、コネクタが行うすべての要求に対して実行されます。
• リソースの [ スクリプト ] タブのスクリプトは、そのリソースに対してのみ実行されます。

ロジックが 1 つのエンドポイントに適用される場合はリソース スクリプトを使用し、コネクタ全体に適用される場合はグローバル スクリプトを使用します。

スクリプトの記述

[グローバル スクリプト] タブを開くには:

1. Integration Service でコネクタ ビルダーを開き、カスタム コネクタを選択します。
2. 上部のナビゲーションから [ グローバル スクリプト ] を選択します。
3. [ Pre-request script] または [ Post-request script] を展開し、JavaScript を入力します。

スクリプトはサンドボックス化された JavaScript 環境で実行されます。ネットワークにアクセスできず、パッケージをインポートする方法もありません。

標準の JavaScript 組み込みとして、 JSON、 Date、 Array、 Object、 URL、 encodeURIComponent、 URLSearchParams、 TextEncoder、 TextDecoder、 btoa、 atob、 crypto、 Blob、 FormData、 Headers、 Intl、 BigIntがあります。

重要:

Buffer は利用 できません 。代わりに、Base64 エンコードには btoa と atob を使用します。

以下はサンドボックスでは利用できません。

カテゴリ (Category)	利用できません。
評価とインポート	eval、任意の require() 呼び出し、最上位の import または export ステートメント、動的な import(...) 式
ネットワーク	fetchXMLHttpRequest、WebSocket
タイマーとワーカー	setTimeout、setInterval、setImmediate、Worker、importScripts、postMessage
ランタイムとグローバル	Deno、process、globalThis、self、window、WebAssembly、Buffer

done() 関数

すべてのスクリプト は 、完了を通知するために done() を呼び出す必要があります。done() は直ちに実行を終了し、 done() 後に記述されたコードにはアクセスできません。

// Pass through unchanged
done();

// Override one or more output values
done({
  request_vendor_headers: updatedHeaders
});

// Return multiple overrides
done({
  request_vendor_body: newBody,
  request_vendor_headers: newHeaders
});

// Stop the request — do not call the vendor API
done({ continue: false });

// Stop the request and return an error
done({
  continue: false,
  response_status_code: 400,
  response_error_message: "Invalid action"
});

スニペットを使用する

スクリプト パネルで [ スニペット ] を選択して、アクティブなスクリプト エディターにコード テンプレートを挿入します。

[ 事前要求スクリプト ] パネルには、次のテンプレートが [事前要求スクリプト] の下にグループ化されています。

• プロバイダーの URL を更新 — request_vendor_path を完全な URL に設定し、その要求のプロバイダーの URL を置き換えます。
• 構成を使用 — configuration (このサンプルではコネクタのベース URL) から値を読み取り、要求ヘッダーとしてプロバイダーに送信します。
• プロバイダーの要求をスキップ — continue を に設定し false 要求がプロバイダーに送信されないようにします。

[ 要求後スクリプト ] パネルには、次のテンプレートが [要求後スクリプト] の下にグループ化されています。

• 応答本文を更新する — response_body ローカル変数にコピーし、そこにフィールドを追加して、変更された本文を返します。
• ベンダーのメタデータからの SR メタデータの生成 — ベンダーのメタデータの応答から標準リソース フィールドのメタデータを構築し、各カスタム フィールドの種類、形式、表示名、説明、サポートされているメソッド、列挙値を導き出します。

要求前のスクリプト

各 API 呼び出しがプロバイダーに送信される前に、要求前スクリプトが実行されます。書き込みアクセス権または読み取り/書き込みアクセス権を持つ変数は、done()で設定できます。

変数	アクセス	説明
request_method	読み取り	API 呼び出しの HTTP メソッド (GET、 POSTなど) です。
request_vendor_method	読み取り/書き込み	プロバイダーに渡される HTTP メソッドです。
request_headers	読み取り	API 呼び出しの一部として渡される要求ヘッダー。
request_vendor_headers	読み取り/書き込み	プロバイダーに送信されるヘッダー。
request_path	読み取り	API 呼び出しの要求パスです。
request_vendor_path	読み取り/書き込み	プロバイダーに送信される要求パス。パスが で httpで始まる場合、完全な要求 URL として使用されます。
request_path_variables	読み取り	URL テンプレートから抽出されたパス変数。
request_parameters	読み取り	API 呼び出しの一部として渡されるクエリ パラメーター。
request_vendor_parameters	読み取り/書き込み	プロバイダーに送信されるクエリ パラメーター。
request_body	読み取り	API 呼び出しの一部として文字列として渡される要求本文です。
request_body_raw	読み取り	API 呼び出しの一部として、未処理の文字列として渡される要求本文です。
request_vendor_body	読み取り/書き込み	プロバイダーに送信される要求本文。書き込み時に文字列、リスト、またはマップを受け入れます。
request_body_map	読み取り	要求本文は、API 呼び出しの一部としてマップとして渡されます。
request_vendor_body_map	読み取り	プロバイダーにマップとして送信される要求本文です。
request_vendor_url	読み取り	ベンダー呼び出しに使用される完全形式のエンドポイント URL です。
request_expression	読み取り	CEQL where パラメーターを {attribute, value, operator} マップのリストに変換します。
request_previous_response	読み取り	Response body from the previous chained resource. null if not part of a chain.
request_previous_response_headers	読み取り	Response headers from the previous chained resource. null if not part of a chain.
request_previous_vendor_path	読み取り	The path of the previous request in the chain. null if not part of a chain.
request_root_key	読み取り/書き込み	要求 JSON ペイロードでサブオブジェクトを構築するためのドット表記のパス (例:data.record)。
object_name	読み取り	要求の正規オブジェクト名です。
vendor_object_name	読み取り	ベンダー オブジェクト名。リソースでオーバーライドされない限り、 object_name と同じです。
configuration	読み取り	コネクタの構成プロパティ
response_status_code	書き込み	continue がfalseされた場合に返される HTTP ステータス コードです。
response_error_message	書き込み	要求がベンダーに送信される前に返されるエラー メッセージ。
response_body	書き込み	continue がfalseときに返される応答本文。
response_body_raw	書き込み	continue がfalse場合に返される文字列としての応答本文です。
response_root_key	読み取り/書き込み	サブオブジェクトへの応答を制限するドット表記のパス (例:data.records)。
multipart_hook_context_items	読み取り/書き込み	ファイルのアップロード要求用のマルチパート フォーム項目。
continue	書き込み	ベンダーからの問い合わせをスキップするには、[ false ] に設定します。既定値は [ trueです。

例: 構成から動的ヘッダーを挿入する

var headers = request_vendor_headers || {};
var config = configuration || {};

headers['Authorization'] = 'Bearer ' + config['oauth_token'];

done({ request_vendor_headers: headers });

例: ベンダーの URL パスを上書きする

var baseUrl = configuration['base_url'];
if (!baseUrl) {
  done({ continue: false, response_error_message: "Missing configuration: 'base_url'" });
  return;
}

var apiVersion = configuration['api_version'] || 'v1';
var modelId = request_path_variables.modelId;
var vendorUrl = baseUrl.startsWith('http') ? baseUrl : 'https://' + baseUrl;

done({
  request_vendor_path: vendorUrl + '/' + apiVersion + '/models/' + modelId + '/completions'
});

例: 要求本文を変更する

var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});

要求後のスクリプト

ベンダーから応答を受け取った後、要求後スクリプトが実行されます。要求前のすべての変数は、引き続き読み取りとして使用できます。以下の応答固有の変数が追加され、 configuration が [Read & Write] になります。書き込みアクセス権または読み取り/書き込みアクセス権を持つ変数は、done()で設定できます。

変数	アクセス	説明
response_iserror	読み取り	true ベンダーの応答がエラーを示している場合 (ステータス コード 200 から 207 以外)。
response_status_code	読み取り/書き込み	ベンダーからの HTTP ステータス コード。
response_body	読み取り/書き込み	ベンダーからの応答本文。
response_body_raw	読み取り/書き込み	ベンダーからの生の応答本文 (文字列) です。
response_body_raw_map	読み取り	ベンダーからの生の応答本文 (マップとして)。
response_body_map	読み取り	ベンダーからの応答本文をマップとして。
response_headers	読み取り/書き込み	ベンダーからの応答ヘッダー。
response_error_message	書き込み	返すエラー メッセージ。応答をエラーに変換します。
response_root_key	読み取り/書き込み	サブオブジェクトへの応答を制限するドット表記のパス (例:data.records)。
configuration	読み取り/書き込み	コネクタの構成プロパティコネクタ インスタンスへの変更が保持されます。
multipart_hook_context_items	読み取り/書き込み	ファイルのアップロード要求用のマルチパート フォーム項目。
metadata_merge	書き込み	ベンダーのメタデータとモデルのメタデータを組み合わせるには、[ true ] に設定します。

ヒント:

すべての要求後スクリプトをエラー ガードで開始します。応答がエラーの場合は、引数を指定せずに done() を呼び出して、変更せずに渡します。

例: 応答の本文を変換する

if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

body.processed = true;
body.timestamp = new Date().toISOString();

done({ response_body: body });

ユーティリティ関数

以下のユーティリティ関数は、両方のスクリプトタイプで使用できます。

機能	説明
console.log()	デバッグ メッセージを出力します。

独自の LLM コネクタを使用する - ユース ケース

セルフホスト モデルやサードパーティの推論エンドポイントなど、LLM プロバイダーのコネクタを構築する場合、グローバル スクリプトを使用すると、各リソースを個別に変更することなく、要求と応答を予想されるコントラクトに合わせて調整できます。

ヒント:

一般的な LLM プロバイダー (AWS Bedrock、Azure OpenAI、Google Vertex AI、OpenAI V1 互換) の場合、認証設定とスクリプトが事前に入力されたコネクタ テンプレートから始めることができます。詳しくは、「 コネクタ テンプレートを使用する」をご覧ください。

次のスクリプトは、このシナリオの完全な事前要求と事後要求の設定を示しています。

事前要求: 認証ヘッダーを設定する

コネクタ構成からプロバイダーの API キーを挿入し、期待される Content-Typeを適用します。

var headers = {
  'Content-Type': 'application/json',
  'x-api-key': configuration['api_key']
};

done({
  request_vendor_headers: headers,
  request_vendor_body: request_body_map
});

事前要求: システム メッセージを挿入する

既定のモデル パラメーターを設定し、モデルに送信されるすべての会話にシステム メッセージが存在することを確認します。

var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

var hasSystemMessage = body.messages.some(function(msg) {
  return msg.role === 'system';
});

if (!hasSystemMessage) {
  body.messages.unshift({
    role: 'system',
    content: 'You are a helpful assistant.'
  });
}

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});

事後要求: choices 配列を処理します

ワークフローに戻る前に、ベンダーの応答で choices 配列を反復処理し、カスタム メタデータを追加します。

if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

if (body.choices && body.choices.length > 0) {
  body.choices.forEach(function(choice) {
    choice.processed_by = 'connector-post-script';
  });
}

body.custom_metadata = {
  processed: true,
  timestamp: new Date().toISOString()
};

done({ response_body: body });

ベスト プラクティス

• 常に done()を呼び出す — 要求を呼び出しdone()ハングさせないスクリプト。
• 変更前に変数をコピーする — ランタイムは厳密モードを使用します。最初にローカル変数に代入してから var headers = request_vendor_headers;に代入してから、 headersを変更します。
• done()後にコードを記述しないでください - 到達できません。
• nullまたはundefinedを確認する — GET 要求と DELETE 要求に対してrequest_bodyとrequest_vendor_bodyがundefinedされます。
• Use continue: false to short-circuit — skip the vendor call and return your own response. Post-request scripts still run on that response.

Execution order

When a connector has both a global script and a resource script for the same phase, both scripts run, in this order:

1. Global pre-request script
2. Resource pre-request script
3. The request is sent to the provider
4. Global post-request script
5. Resource post-request script

重要:

The post-request chain does not run in reverse. The global post-request script receives the raw provider response first, and can change or reject it before the resource post-request script runs.

Example: a global script and a resource script on one activity

Consider a connector with the following scripts:

• Global pre-request: adds an X-Acme-Tenant header from configuration.
• Global post-request: maps the provider's error envelope onto the matching HTTP status code.
• GET /contacts resource: a pre-request script that maps paging parameters, and a post-request script that reshapes the payload.

順序	スクリプト	表示される内容
1	Global pre-request	The request as built from the activity input.
2	Resource pre-request	The request, including the tenant header added in step 1.
—	Provider call	—
3	Global post-request	The raw provider response.
4	Resource post-request	The response as left by step 3.

If both pre-request scripts set Authorization, the provider receives the value from the resource script, because it runs last. If the global post-request script sets response_error_message, the request ends with that error and step 4 does not run. Setting only an error response_status_code does not stop the chain.

When a pre-request script stops the request

If a global or resource pre-request script calls done() with continue: false, the request is not sent to the provider:

• Pre-request scripts that haven't run yet are skipped. For example, if the global pre-request script stops the request, the resource pre-request script does not run.
• Both post-request scripts still run, in the usual order, on the response returned by the script that stopped the request.
• If that script returned no response body, the post-request scripts receive an empty body: an empty array for a paginated resource, and an empty response otherwise.

To end the request with an error instead, set response_error_message. In a pre-request or post-request script, it ends the request immediately with that error, and no later script runs, including post-request scripts. The status code is the value of response_status_code, or 400 if it isn't set.