Chuyển tới nội dung chính

Các công thức kịch bản kinh điển

Kết hợp concepts và scripting thành các quy trình thực tế. Mỗi kịch bản gồm: mục tiêu → quy trình → script dán thẳng vào UI → kết quả mong đợi. Toàn bộ logic script đã được xác minh đầu-cuối trong ứng dụng thật.

Các ví dụ dùng máy chủ kiểm thử cục bộ (/oauth2/token, /protected, /echo, /json, v.v.). Khi trỏ tới API của riêng bạn, hãy thay bằng đường dẫn và Pre-URL của bạn.


Kịch bản 1: Đăng nhập lấy token, tự gắn cho cả nhóm​

Mục tiêu: gọi API đăng nhập, lưu token và khiến mọi yêu cầu sau đó tự gắn nó — không cần sao chép thủ công.

Yêu cầu A — đăng nhập (script sau phản hồi lưu token)​

POST /oauth2/token, body dạng form: grant_type=password&username=qruser&password=qrpass&client_id=qr-client&client_secret=qr-secret

Thêm một bước script vào chuỗi sau phản hồi:

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;
}

Yêu cầu B — gắn token (cùng một script có thể sao chép vào mọi API có ủy quyền)​

GET /protected, thêm một bước script vào chuỗi trước khi gửi:

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;
}

Kết quả mong đợi​

Hành độngKết quả
Gửi A trước (đăng nhập)200, phản hồi chứa access_token, token đã lưu
Sau đó gửi B (gắn)200, phản hồi {authorized:true, ...}
Tắt script, gửi lại B401 (chuỗi trước khi gửi không chạy → không token được chèn — chứng minh chính script gắn nó)

Chìa khóa: A và B phải trong cùng nhóm gắn cùng môi trường (biến thời gian chạy có phạm vi theo môi trường), và đoạn đường dẫn được hoàn thiện bởi Pre-URL của môi trường.


Kịch bản 2: Mã hóa body yêu cầu bằng AES, giải mã phản hồi (chuỗi nhiều script)​

Mục tiêu: mã hóa body bằng AES trước khi gửi (trên dây chỉ có bản mã hóa), giải mã phản hồi khi nó đến; kịch bản cũng minh họa xích nhiều script và chia sẻ dữ liệu giữa chúng.

Tại sao có thể tách thành nhiều script? Script trong cùng chuỗi chia sẻ globalThis: script ① cất khóa/văn bản rõ, script ②③ nhặt chúng lên. Mỗi script giữ một mục đích duy nhất và có thể bật/tắt độc lập.

Chuỗi trước khi gửi​

Script ① (chuẩn bị ngữ cảnh và khóa):

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;
}

Script ② (mã hóa body):

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;
}

(Tùy chọn) script ③ thêm logic gắn token từ Kịch bản 1.

Chuỗi sau phản hồi (giải mã + viết lại phản hồi)​

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;
}

Body yêu cầu (trước khi mã hóa): {"order":123,"note":"secret-payload","amount":99.5}

Kết quả mong đợi​

Sau khi gửi bạn nhận được:

{"traceId":"...","decrypted":"{\"order\":123,\"note\":\"secret-payload\",\"amount\":99.5}","roundtripOk":true,"jsonValid":true}
  • roundtripOk:true: kết quả giải mã khớp văn bản rõ gốc từng byte một
  • Body phản hồi đã viết lại hiển thị trong kết quả (chứng minh việc viết lại sau phản hồi có hiệu lực)

⚠️ Tham số $crypto là chuỗi vị trí; khi thất bại nó chỉ trả về chuỗi bắt đầu bằng Error: — không ném ngoại lệ và không ngắt (đã xác minh: ciphertext xấu → Invalid ciphertext, key/iv sai → CryptoKit error). Văn bản rõ tiếng Trung và không ASCII mã hóa và giải mã đúng (tuyên bố cũ "không ASCII làm ngắt" đã bị bác bỏ). Nếu bạn cần ghi kết quả đã giải mã vào header HTTP, hãy đảm bảo giá trị là ASCII (giá trị header từ chối ký tự không ASCII, nếu không sẽ ném TypeError); đặt nội dung UTF-8 vào body hoặc tham số truy vấn.


Kịch bản 3: trích xuất · assertion · biến động · ký số​

Một bộ tự động hóa nhẹ — hầu hết không cần JS nào, dùng các bước khai báo trích xuất / assertion.

3.1 Chuyển một trường phản hồi cho yêu cầu tiếp theo (trích xuất)​

  • Thêm bước trích xuất vào chuỗi sau phản hồi của yêu cầu A: biến author, nguồn response body JSON, biểu thức $.slideshow.author.
  • Thêm bước script vào chuỗi trước khi gửi của yêu cầu B: var v=sdk.env.get('author'); if(v){ request.headers.set('X-Extracted', v); } return request;

Đã xác minh: /echo của yêu cầu B phản hồi lại header X-Extracted khớp với tác giả trong phản hồi của yêu cầu A.

3.2 Assertion​

Thêm các bước assertion vào chuỗi sau phản hồi: mã trạng thái = 200, $.slideshow.title exists. Kết quả được liệt kê từng cái một (đạt/trượt, kỳ vọng vs thực tế).

3.3 Biến động​

Viết trực tiếp vào params / headers / URL:

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

Đã xác minh: mỗi lần gửi ts phản hồi lại dấu thời gian hiện tại, r một số nguyên ngẫu nhiên khác, và u một UUID hợp lệ. Danh sách đầy đủ: concepts, biến động.

3.4 Ký số (MD5, chuẩn và tương thích)​

Nhiều API mở ký bằng MD5(param concatenation + secret). Dùng $hash.md5 chuẩn đã xác minh:

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;
}

Đã xác minh: $hash.md5('abc') = 900150983cd24fb0d6963f7d28e17f72, khớp với backend.

✅ $hmac gốc ($hmac.sha256(message, key) v.v.) đã được xác minh vector-với-vector khớp HMAC RFC chuẩn (chú ý thứ tự tham số: dữ liệu trước, khóa sau) và dùng được để ký bên ngoài; họ $hash cũng chuẩn. Chỉ $jwt làm hỏng payload dạng đối tượng thành [object Object] (hãy serialize trước bằng JSON.stringify hoặc ký ở máy chủ).


Kịch bản 4: tái sử dụng logic chung với script thư viện và require()​

Mục tiêu: tách "chèn token", "ký thống nhất" và "logging" thành các đơn vị tái sử dụng — tham chiếu ở nhiều nơi, bảo trì ở một nơi.

Hai cách tái sử dụng:

  • Bước script thư viện: một script đầy đủ với onRequest/onResponse riêng — thêm nó như một bước, nó chạy đúng thứ tự và chia sẻ globalThis với các bước khác.
  • require(): lưu các hàm thuần vào thư viện script bằng module.exports, rồi tải từ bất kỳ script nào — tốt nhất cho hàm ký, bộ mã hóa và các tiện ích chia sẻ khác:
// 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;
}

Dùng Copy require statement trong trình quản lý thư viện để lấy dạng định danh ổn định. Các thư viện tích hợp (@libs/base64, @libs/hex) khả dụng ở mọi nơi không cần cấu hình. Cơ chế đầy đủ: scripting, Tải thư viện script bằng require().


Cẩm nang kịch bản​

Tôi muốn…Dùng bước nào
Tự gắn token cho mọi API sau đăng nhậpScript sau phản hồi lưu + script trước khi gửi đọc và chèn header
Mã hóa body yêu cầu / giải mã phản hồi$crypto.encryptAES trước khi gửi + decryptAES sau phản hồi
Chuyển một trường phản hồi cho yêu cầu tiếp theoBước trích xuất + script đọc biến
Kiểm tra mã trạng thái / trườngBước assertion
Sinh giá trị ngẫu nhiên / dấu thời gian mỗi lần gửiBiến động như {{$uuid}}
Ký một API mở$hash.md5(...) (chuẩn)
Dùng lại cùng logic ở nhiều nơiScript thư viện, hoặc require('@libs/<key>') một thư viện script