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

スクリプト(開発者ビュー)

送信前 / レスポンス後スクリプトはQuick Requestの万能ナイフです:動的署名、暗号化・復号、条件付きアサーション、リクエスト間の値の受け渡しは、すべてここにあります。スクリプトはJavaScriptで書き、内蔵のQuickJSエンジンで実行されます。

このページはUIで追加できるものとスクリプトでできることだけを扱います。JavaScript APIの完全なシグネチャはスクリプトAPIリファレンスを参照。


1つのリクエストに2つの「アクションチェーン」​

リクエスト編集ページでは、送信前とレスポンス後のチェーンに複数のステップを追加でき、順序どおりに実行されます。各ステップは次のいずれかです:

ステップタイプUIでやること典型的な用途
スクリプトJavaScriptを1つ書くヘッダー/ボディの変更、署名、復号、条件ロジック
ライブラリスクリプト保存済みの共有スクリプトを参照「トークン注入」「統一ロギング」を多くの場所で再利用
抽出レスポンスから値を取り変数に保存ログイントークンを次のリクエストへ渡す
アサーションレスポンスへの検証を1つ追加ステータスコード = 200、フィールドの存在確認
待機数ミリ秒一時停止レート制限、ポーリング間隔

スクリプトの書き方:2つのエントリーポイント​

スクリプトエンジンは、スクリプト内の既知のエントリ関数を探します:

// Pre-send: can change "the request that is about to go out"
async function onRequest(context, url, request) {
// e.g. inject a header
request.headers.set('X-Trace-Id', $uuid.v4());
return request; // you must return the request
}

// Post-response: can read and change "the response you received"
async function onResponse(context, url, response) {
// e.g. rewrite an encrypted response back to plaintext for humans
return response;
}
  • 送信前チェーンには onRequest、レスポンス後チェーンには onResponse を書きます。
  • 関数名は正確にこの名前である必要があります。そうでないと「エントリーポイントなし」と扱われスキップされます。
  • await に対応しています。

スクリプトが変更できるもの​

リクエストの変更(onRequest の request オブジェクト)​

やりたいこと方法
ヘッダーの設定 / 上書きrequest.headers.set('Authorization', 'Bearer ' + tok)
クエリパラメータの追加 / 変更request.queries.set('ts', String(Date.now()))
生ボディの読み取りvar text = request.body.parseText() または request.body.parseJSON()
ボディ全体の書き換えrequest.body = the new string(そのまま代入)

レスポンスの読み取り / 変更(onResponse の response オブジェクト)​

やりたいこと方法
ステータスコードの読み取りresponse.statusCode
レスポンスヘッダーの読み取りresponse.headers.get('Set-Cookie')
ボディの読み取りresponse.body.parseJSON() / .parseText()
レスポンスボディ全体の書き換えresponse.body = the new string — UI/結果ビューには書き換え後の内容が表示されます(検証済み)

組み込み機能 — 車輪の再発明は不要​

スクリプトには内蔵ツール群(sdk.*)と $ 接頭辞のネイティブ機能が最初から用意されています:暗号化、ダイジェスト、エンコーディング、ランダム、JSONPathをすべてカバー:

機能使うもの
変数の読み書き(リクエスト間受け渡し)sdk.env.get(name) / sdk.env.set(name, value)
宣言的テストsdk.test('status should be 200', function(){ sdk.expect(response.statusCode).toBe(200) })
JSONPathクエリsdk.jsonPath('$.data.id')
AES暗号化 / 復号$crypto.encryptAES(plaintext, key[, iv]) / $crypto.decryptAES(ciphertext, key[, iv])
MD5 / SHAダイジェスト(署名)$hash.md5(...) / $hash.sha256(...)(hexを返す、標準的で相互運用可能)
UUID$uuid.v4()
文字列base64sdk.utils.base64Encode(str) / base64Decode(str)

⚠️ エンジンはQuickJSです:ブラウザの crypto.subtle は存在せず、crypto.getRandomValues もこのエンジンでは動きません(渡された配列を埋めません)— AESには $crypto を、ランダムには crypto.randomUUID / $uuid を使ってください。WebCryptoには手を伸ばさないでください。完全なシグネチャと注意点:スクリプトAPIリファレンス。


スクリプトライブラリのrequire​

共有ロジックは、ステップとして追加する代わりにCommonJSスタイルの require() で読み込むこともできます。キーは常に @libs/<key> で、次の順序で解決されます:

  1. スクリプトライブラリのidentifier — 完全一致。リネームしても安定(推奨)
  2. スクリプトライブラリの名前 — 読みやすいが、ライブラリのリネームで参照が壊れる(曖昧な重複名はスキップ)
  3. 組み込みライブラリ — アプリに同梱

組み込みライブラリ​

キーエクスポート備考
@libs/base64encode(str) / decode(text)UTF-8対応Base64(中国語・絵文字も安全);decode は空白を無視、不正シーケンスはLatin-1のまま保持
@libs/hexencode(str) / decode(text)UTF-8対応の小文字hex;decode は非hex文字を無視、奇数長は例外を投げる

両方ともグローバルエイリアス(base64.encode(...) / hex.encode(...))としても公開されています — require は明示的なインポートスタイルを提供するだけです。

const { encode } = require('@libs/base64');
encode('hello 中文'); // 'aGVsbG8g5Lit5aSp'

自分のスクリプトライブラリ​

再利用する関数をスクリプトライブラリとして保存し(module.exports でエクスポート、エントリ関数は不要)、任意の送信前/後スクリプトからrequireします:

// script library "sign-lib"
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('secret')));
return request;
}
  • 安定したidentifier形を得るには、ライブラリマネージャーのrequire文をコピーを使います。
  • ライブラリは他のライブラリを require できます — 依存関係の閉包全体が自動でバンドルされます(循環はNode風に解決され、無限ループしません)。
  • モジュールキャッシュは実行のたびに再構築されます:ライブラリがリクエスト間で状態を持つことはありません。
  • npmパッケージを再利用するには、まず1ファイルにバンドルし(例:esbuild --format=iife、Browserify/Webpack)、そのファイルをスクリプトライブラリとしてインポートしてから require('@libs/<name>') します。Node(Buffer/fs/crypto/process)やDOM依存のない純粋JSビルドを選んでください。
  • 存在しないキーは Error: require: 未找到库 [...] を投げます — 送信前の失敗はリクエストを中断し、レスポンス後の失敗は元のレスポンスを保持します。コメント内の require 呼び出しは無視されます。

require の完全なセマンティクス:スクリプトAPIリファレンス。


複数スクリプトの連携​

1つのリクエストに複数のスクリプトがあるとき、それらは同じ globalThis を共有します(検証済み)。なので:

利点:各スクリプトは単一責任を持ち、独立してON/OFFできます。「ライブラリスクリプト」も完全なスクリプトです(独自の onRequest/onResponse を持ちます)— ステップとして追加すればチェーン全体を実行し、module.exports で純粋関数を保持して require('@libs/<key>') で読み込むこともできます(スクリプトライブラリのrequire 参照)。

具体的なチェーン例(トークンのためのログイン、AES往復)は recipes を参照。