Перейти к основному содержимому

Классические рецепты сценариев

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

Примеры используют локальный тестовый сервер (/oauth2/token, /protected, /echo, /json и т.д.). При работе со своими API подставьте свои пути и Pre-URL.


Сценарий 1: вход для получения токена, автоподстановка для всей группы​

Цель: вызвать API входа, сохранить токен и сделать так, чтобы все последующие запросы прикрепляли его автоматически — без ручного копирования.

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

POST /oauth2/token, form-тело: 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, ...}
Отключить скрипты и снова отправить B401 (цепочка перед отправкой не выполняется → токен не внедрен — доказательство, что именно скрипт прикрепляет его)

Ключевое: A и B должны находиться в одной группе, привязанной к одному окружению (переменные runtime действуют в рамках окружения), а фрагменты пути достраиваются Pre-URL окружения.


Сценарий 2: шифрование тела запроса AES, расшифровка ответа (цепочка из нескольких скриптов)​

Цель: шифровать тело AES перед отправкой (в сети только шифротекст), расшифровывать ответ после получения; также демонстрирует цепочку из нескольких скриптов и обмен данными между ними.

Почему можно разделить на несколько скриптов? Скрипты одной цепочки разделяют globalThis: скрипт ① прячет ключи/plaintext, скрипты ②③ их подхватывают. Каждый скрипт остается однозадачным и может включаться/выключаться независимо.

Цепочка перед отправкой​

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

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: расшифрованный результат побайтово совпадает с исходным plaintext
  • Переписанное тело ответа видно в результате (доказательство, что переписывание после ответа сработало)

⚠️ Аргументы $crypto — позиционные строки; при сбое он только возвращает строку, начинающуюся с Error: — не бросает исключение и не прерывает (проверено: неверный шифротекст → Invalid ciphertext, неверные key/iv → CryptoKit error). Китайский / не-ASCII plaintext шифруется и расшифровывается корректно (старое утверждение «не-ASCII прерывает» опровергнуто). Если нужно записать расшифрованный результат в HTTP-заголовок, убедитесь, что значение ASCII (значения заголовков отвергают не-ASCII, иначе бросается TypeError); UTF-8-контент кладите в тело или query-параметры.


Сценарий 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;

Проверено: /echo запроса B возвращает заголовок X-Extracted, совпадающий с author из ответа запроса A.

3.2 Проверки​

Добавьте шаги проверка в цепочку после ответа: код состояния = 200, $.slideshow.title exists. Результаты перечисляются по одному (успех/провал, ожидаемое vs фактическое).

3.3 Динамические переменные​

Пишите их прямо в params / headers / URL:

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

Проверено: каждая отправка возвращает ts как текущий timestamp, 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, совпадает с backend.

✅ Нативный $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 после ответа
Передать поле ответа следующему запросуШаг извлечения + скрипт, читающий переменную
Проверять коды состояния / поляШаг проверки
Генерировать случайные значения / timestamps при каждой отправкеДинамические переменные вроде {{$uuid}}
Подписать открытый API$hash.md5(...) (стандарт)
Переиспользовать одну логику во многих местахБиблиотечный скрипт, или require('@libs/<key>') библиотеки скриптов