グローバル スクリプト

コネクタ ビルダーでグローバル スクリプトを設定して、すべての API 要求の前または後に JavaScript を実行し、要求と応答の処理を一貫させます。

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

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

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

• 送信前に要求ヘッダー、パラメーター、または本文を挿入または上書きする
• 構成値に基づいてベンダー 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	読み取り	直前のチェーンされたリソースからの応答本文。チェーンの一部でない場合は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を使用して短絡 — ベンダーを呼び出さずに直接応答を返します。