メインコンテンツまでスキップ

定番シナリオレシピ

concepts と スクリプト を組み合わせて実際のワークフローにします。各シナリオは ゴール → フロー → UIにそのまま貼り付けられるスクリプト → 期待される結果 の構成です。すべてのスクリプトロジックは実アプリでエンドツーエンド検証済みです。

例ではローカルテストサーバー(/oauth2/token、/protected、/echo、/json など)を使用します。自分のAPIに向ける場合は、パスとPre-URLを自分のものに置き換えてください。


シナリオ1:ログインでトークン取得、グループ全体への自動付与​

ゴール:ログインAPIを呼び、トークンを保存し、その後のすべてのリクエストに自動で付与させます — 手動コピーは不要です。

リクエストA — ログイン(レスポンス後スクリプトがトークンを保存)​

POST /oauth2/token、フォームボディ:grant_type=password&username=qruser&password=qrpass&client_id=qr-client&client_secret=qr-secret

レスポンス後チェーンにスクリプトステップを1つ追加します:

async function onResponse(context, url, response) {
var j = response.body.parseJSON();
if (j && j.access_token) {
sdk.env.set('authToken', j.access_token); // store on the runtime blackboard
sdk.env.set('tokenType', j.token_type || 'Bearer');
}
return response;
}

リクエストB — トークンの付与(同じスクリプトを認可が必要な全APIにコピー可能)​

GET /protected、送信前チェーンにスクリプトステップを1つ追加します:

async function onRequest(context, url, request) {
var tok = sdk.env.get('authToken'); // take from the blackboard
var ty = sdk.env.get('tokenType') || 'Bearer';
if (tok) { request.headers.set('Authorization', ty + ' ' + tok); }
return request;
}

期待される結果​

アクション結果
先にAを送信(ログイン)200、レスポンスに access_token が含まれ、トークン保存済み
続けてBを送信(付与)200、レスポンス {authorized:true, ...}
スクリプトを無効化してBを再送信401(送信前チェーンが動かない → トークン未注入 — スクリプトこそが付与している証拠)

鍵:AとBは同じ環境にバインドされた同じグループに置く必要があります(実行時変数は環境単位のスコープ)。パス断片は環境のPre-URLが補完します。


シナリオ2:リクエストボディのAES暗号化、レスポンスの復号(マルチスクリプトチェーン)​

ゴール:送信前にボディをAES暗号化し(ワイヤー上は暗号文のみ)、レスポンスの到着後に復号します。複数スクリプトのチェーン化とスクリプト間のデータ共有も示します。

なぜ複数スクリプトに分割できるのか? 同じチェーンのスクリプトは**globalThis を共有**します:スクリプト①が鍵/平文を退避し、スクリプト②③がそれを受け取ります。各スクリプトは単一目的を保ち、独立してON/OFFできます。

送信前チェーン​

スクリプト①(コンテキストと鍵の準備):

async function onRequest(context, url, request) {
globalThis.__traceId = $uuid.v4();
globalThis.__aesKey = '0123456789abcdef'; // 16 bytes → AES-128
globalThis.__aesIv = 'abcdef0123456789';
globalThis.__plain = request.body.parseText();
request.headers.set('X-Trace-Id', globalThis.__traceId);
return request;
}

スクリプト②(ボディの暗号化):

async function onRequest(context, url, request) {
var cipher = $crypto.encryptAES(globalThis.__plain, globalThis.__aesKey, globalThis.__aesIv);
request.body = cipher; // only ciphertext on the wire
request.headers.set('X-Encrypt', 'AES-128-CBC');
return request;
}

(任意)スクリプト③はシナリオ1のトークン付与ロジックを追加します。

レスポンス後チェーン(復号 + レスポンスの書き換え)​

async function onResponse(context, url, response) {
var j = response.body.parseJSON();
var cipher = j && j.body && j.body.utf8; // /echo echoes the request body in body.utf8
var recovered = cipher ? $crypto.decryptAES(cipher, globalThis.__aesKey, globalThis.__aesIv) : '';
var obj = null; try { obj = JSON.parse(recovered); } catch (e) {}
response.body = JSON.stringify({
traceId: globalThis.__traceId, decrypted: recovered,
roundtripOk: recovered === globalThis.__plain, jsonValid: !!obj,
});
return response;
}

リクエストボディ(暗号化前):{"order":123,"note":"secret-payload","amount":99.5}

期待される結果​

送信すると次を得ます:

{"traceId":"...","decrypted":"{\"order\":123,\"note\":\"secret-payload\",\"amount\":99.5}","roundtripOk":true,"jsonValid":true}
  • roundtripOk:true:復号結果が元の平文とバイト単位で一致
  • 書き換え後のレスポンスボディが結果に表示される(レスポンス後の書き換えが効いている証拠)

⚠️ $crypto の引数は位置指定の文字列です。失敗時は Error: で始まる文字列を返すだけで、例外や中断はしません(検証済み:壊れた暗号文 → Invalid ciphertext、誤った鍵/iv → CryptoKit error)。中国語 / 非ASCIIの平文も正しく暗号化・復号できます(「非ASCIIは中断する」という古い記述は否定されました)。復号結果をHTTPヘッダーに書きたい場合は、値がASCIIであることを確認してください(ヘッダー値は非ASCIIを拒否し、そうでなければ TypeError が投げられます)。UTF-8の内容はボディかクエリパラメータに置いてください。


シナリオ3:抽出 · アサーション · 動的変数 · 署名​

軽量オートメーションの詰め合わせです。ほとんどはJS不要で、宣言的な抽出 / アサーションステップを使います。

3.1 レスポンスフィールドを次のリクエストへ渡す(抽出)​

  • リクエストAのレスポンス後チェーンに抽出ステップを追加:変数 author、ソース response body JSON、式 $.slideshow.author。
  • リクエストBの送信前チェーンにスクリプトステップを追加:var v=sdk.env.get('author'); if(v){ request.headers.set('X-Extracted', v); } return request;

検証済み:リクエストBの /echo が、リクエストAのレスポンス内のauthorと一致する X-Extracted ヘッダーを返します。

3.2 アサーション​

レスポンス後チェーンにアサーションステップを追加:ステータスコード = 200、$.slideshow.title exists。結果は1件ずつ一覧表示されます(合否、期待値 vs 実際値)。

3.3 動的変数​

params / headers / URL に直接書けます:

GET /echo?ts={{$timestamp}}&r={{$randomInt}}&u={{$uuid}}

検証済み:送信のたびに ts は現在のタイムスタンプ、r は別のランダム整数、u は有効なUUIDとして返ります。全リスト:concepts、動的変数。

3.4 署名(MD5、標準的で相互運用可能)​

多くの公開APIは MD5(param concatenation + secret) で署名します。標準検証済みの $hash.md5 を使います:

async function onRequest(context, url, request) {
var appId = sdk.env.get('appId');
var secret = sdk.env.get('appSecret'); // keep secrets in environment variables
var ts = String(Math.floor(Date.now() / 1000));
var sign = $hash.md5(appId + ts + secret); // concatenation order per your backend's convention
request.queries.set('appId', appId);
request.queries.set('ts', ts);
request.queries.set('sign', sign);
return request;
}

検証済み:$hash.md5('abc') = 900150983cd24fb0d6963f7d28e17f72、バックエンドと一致。

✅ ネイティブの $hmac($hmac.sha256(message, key) など)はベクトル単位で検証済みで、標準RFC HMAC と一致します(引数の順序に注意:データが先、鍵が後)。外部署名に使えます。$hash 系も標準的です。$jwt だけはオブジェクトペイロードを [object Object] に劣化させます(先に JSON.stringify するか、サーバー側で署名してください)。


シナリオ4:ライブラリスクリプトと require() で共通ロジックを再利用​

ゴール:「トークン注入」「統一署名」「ロギング」を再利用可能な単位に切り出します — 多くの場所から参照し、1か所で保守します。

再利用の方法は2つ:

  • ライブラリスクリプトステップ:独自の onRequest/onResponse を持つ完全なスクリプトです — ステップとして追加すると順序どおりに実行され、他のステップと globalThis を共有します。
  • require():純粋関数を module.exports でスクリプトライブラリに保存し、任意のスクリプトから読み込みます — 署名ヘルパー、コーデックなどの共通ユーティリティに最適:
// script library "sign-lib" (no entry function needed)
function sign(method, path, body, secret) {
return $hmac.sha256(method + path + body, secret);
}
module.exports = { sign };
// any request script
async function onRequest(context, url, request) {
const { sign } = require('@libs/sign-lib');
request.headers.set('X-Sign', sign('POST', request.path, request.body.parseText(), sdk.env.get('appSecret')));
return request;
}

安定したidentifier形はライブラリマネージャーのrequire文をコピーで取得します。組み込みライブラリ(@libs/base64、@libs/hex)は設定なしでどこでも使えます。詳細な仕組み:スクリプト、スクリプトライブラリのrequire。


シナリオ早見表​

やりたいこと使うステップ
ログイン後に全APIへトークンを自動付与レスポンス後スクリプトで保存 + 送信前スクリプトで読んでヘッダー注入
リクエストボディの暗号化 / レスポンスの復号送信前 $crypto.encryptAES + レスポンス後 decryptAES
レスポンスフィールドを次のリクエストへ渡す抽出ステップ + 変数を読むスクリプト
ステータスコード / フィールドの検証アサーションステップ
送信ごとにランダム値 / タイムスタンプを生成{{$uuid}} などの動的変数
公開APIに署名$hash.md5(...)(標準)
同じロジックを多くの場所で再利用ライブラリスクリプト、またはスクリプトライブラリを require('@libs/<key>')