Перейти до основного вмісту

Класичні рецепти сценаріїв

Поєднуйте concepts та scripting у реальні робочі процеси. Кожен сценарій дає: мета → потік → скрипти, які можна вставити прямо в UI → очікуваний результат. Уся логіка скриптів перевірена наскрізно в реальному застосунку.

Приклади використовують локальний тестовий сервер (/oauth2/token, /protected, /echo, /json тощо). Підставте власні шляхи та Pre-URL, коли цілиитеся у власні API.


Сценарій 1: Вхід за токеном, автоприкріплення для всієї групи​

Мета: викликати API входу, зберегти токен і мати кожен наступний запит, який автоматично його прикріплює — без ручного копіювання.

Запит A — вхід (скрипт після відповіді зберігає токен)​

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

Додайте один крок скрипт до ланцюжка після відповіді:

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, додайте один крок скрипт до ланцюжка перед відправленням:

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: скрипт ① ховає ключі/відкритий текст, скрипти ②③ їх підбирають. Кожен скрипт лишається однозадачним і може вмикатися незалежно.

Ланцюжок перед відправленням​

Скрипт ① (готує контекст і ключі):

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, неправильний key/iv → CryptoKit error). Відкритий текст не-ASCII шифрується та розшифровується правильно (старе твердження, що «не-ASCII перериває», спростовано). Якщо потрібно записати розшифрований результат у HTTP-заголовок, переконайтеся, що значення ASCII (значення заголовків відкидають не-ASCII, інакше кидається TypeError); вміст UTF-8 кладіть у body або query params.


Сценарій 3: Витягування · assertion · динамічні змінні · підпис​

Набір легких автоматизацій — більшість не потребує жодного JS, використовують декларативні кроки витягування / assertion.

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;

Перевірено: /echo запиту B відлунює заголовок X-Extracted, що збігається з автором у відповіді запиту A.

3.2 Assertions​

Додайте кроки assert до ланцюжка після відповіді: код статусу = 200, $.slideshow.title exists. Результати перелічені один за одним (pass/fail, очікуване 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 деградує об'єктні payload у [object Object] (спершу stringify через JSON.stringify або підписуйте на сервері).


Сценарій 4: Повторне використання спільної логіки з бібліотечними скриптами та require()​

Мета: винести «ін'єкцію токена», «уніфіковане підписування» та «логування» у перевикористовувані одиниці — посилайтеся на них у багатьох місцях, підтримуйте в одному.

Два способи повторного використання:

  • Крок бібліотечного скрипта: повний скрипт з власним 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;
}

Використовуйте Copy require statement у менеджері бібліотек для стабільної форми з ідентифікатором. Вбудовані бібліотеки (@libs/base64, @libs/hex) доступні всюди без налаштування. Повна механіка: scripting, Завантаження бібліотек скриптів.


Шпаргалка сценаріїв​

Я хочу…Які кроки
Автоматично прикріплювати токен до кожного API після входуСкрипт після відповіді зберігає + скрипт перед відправленням читає та ін'єктує заголовок
Шифрувати тіло запиту / розшифровувати відповідьПеред відправленням $crypto.encryptAES + після відповіді decryptAES
Передати поле відповіді наступному запитуКрок витягування + скрипт, що читає змінну
Перевіряти коди статусу / поляКрок assert
Генерувати випадкові значення / мітки часу щовідправкиДинамічні змінні на кшталт {{$uuid}}
Підписувати відкритий API$hash.md5(...) (стандартний)
Використовувати ту саму логіку в багатьох місцяхБібліотечний скрипт, або require('@libs/<key>') бібліотеки скриптів