グローバル スクリプト

Configure Global Scripts in Connector Builder to run JavaScript before or after every API request for consistent request and response processing.

コネクタ ビルダーのグローバル スクリプト タブでは、コネクタが行うすべての API 要求の前後に実行される JavaScript を記述できます。送信要求を変更するには要求前スクリプトを使用し、受信応答を処理するには要求後スクリプトを使用します。

グローバルスクリプトを使用する状況

グローバル スクリプトは、以下のような、コネクタ内のすべての要求に一貫したロジックを適用する必要がある場合に便利です。

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

Scripts for a single resource

Each resource also has its own Scripts tab, alongside Parameters, Request fields, Response fields, and Activity designer. It provides the same Pre-request script and Post-request script editors, the same snippets, and the same variables and done() contract as the connector-level Global Scripts tab.

The difference is scope:

• A script on the Global Scripts tab runs for every request the connector makes.
• A script on a resource's Scripts tab runs only for that resource.

Use a resource script when the logic applies to one endpoint, and a global script when it applies to the whole connector.

スクリプトの記述

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

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

Scripts run in a sandboxed JavaScript environment, with no network access and no way to import packages.

Standard JavaScript built-ins are available: JSON, Date, Array, Object, URL, encodeURIComponent, URLSearchParams, TextEncoder, TextDecoder, btoa, atob, crypto, Blob, FormData, Headers, Intl, and BigInt.

重要:

Buffer is not available. Use btoa and atob for base64 encoding instead.

The following are not available in the sandbox:

カテゴリ (Category)	利用できません。
Evaluation and imports	eval, any require() call, a top-level import or export statement, a dynamic import(...) expression
ネットワーク	fetchXMLHttpRequest、WebSocket
Timers and workers	setTimeout、setInterval、setImmediate、Worker、importScripts、postMessage
Runtime and globals	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"
});

スニペットを使用する

Select Snippets in the script panel to insert code templates into the active script editor.

The Pre-request script panel offers the following templates, grouped under Prerequest scripts:

• Update provider URL — Sets request_vendor_path to a full URL, replacing the provider URL for that request.
• Use a configuration — Reads a value from configuration (the connector's base URL, in the sample) and sends it to the provider as a request header.
• Skip a provider request — Sets continue to false so the request is never sent to the provider.

The Post-request script panel offers the following templates, grouped under Postrequest scripts:

• Update the response body — Copies response_body into a local variable, adds a field to it, and returns the modified body.
• SR metadata generation from vendor metadata — Builds standard resource field metadata from a vendor metadata response, deriving each custom field's type, format, display name, description, supported methods, and enum values.

要求前のスクリプト

各 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	読み取り	直前のチェーンされたリソースからの応答本文。チェーンの一部でない場合はnull。
request_previous_response_headers	読み取り	直前のチェーンされたリソースからの応答ヘッダー。チェーンの一部でない場合はnull。
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されます。
• continue: falseを使用して短絡 — ベンダーを呼び出さずに直接応答を返します。