Receitas de cenários clássicos
Combine conceitos e scripts em fluxos de trabalho do mundo real. Cada cenário apresenta: objetivo → fluxo → scripts que você cola direto na UI → resultado esperado. Toda a lógica de script foi verificada de ponta a ponta no app real.
- Cenário 1: login para obter o token, anexação automática para todo o grupo
- Cenário 2: criptografar o corpo da requisi ção com AES, descriptografar a resposta (cadeia multi-scripts)
- Cenário 3: extração · asserções · variáveis dinâmicas · assinatura
- Cenário 4: reutilizar lógica compartilhada com scripts de biblioteca e
require()
Os exemplos usam o servidor de teste local (
/oauth2/token,/protected,/echo,/json, etc.). Ao apontar para as suas próprias APIs, troque pelos seus caminhos e Pre-URLs.
Cenário 1: login para obter o token, anexação automática para todo o grupo
Objetivo: chamar a API de login, armazenar o token e fazer todas as requisições seguintes anexá-lo automaticamente — sem cópia manual.
Requisição A — login (script pós-resposta armazena o token)
POST /oauth2/token, corpo form: grant_type=password&username=qruser&password=qrpass&client_id=qr-client&client_secret=qr-secret
Adicione uma etapa script à cadeia pós-resposta:
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;
}
Requisição B — anexar o token (o mesmo script pode ser copiado para toda API autorizada)
GET /protected, adicione uma etapa script à cadeia de pré-envio:
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;
}
Resultado esperado
| Ação | Resultado |
|---|---|
| Enviar A primeiro (login) | 200, a resposta contém access_token, token armazenado |
| Depois enviar B (anexar) | 200, resposta {authorized:true, ...} |
| Desativar scripts e enviar B de novo | 401 (a cadeia de pré-envio não roda → nenhum token injetado — prova de que é o script que anexa o token) |
Chave: A e B devem estar no mesmo grupo vinculado ao mesmo ambiente (variáveis de runtime têm escopo por ambiente), e os fragmentos de caminho são completados pelo Pre-URL do ambiente.
Cenário 2: criptografar o corpo da requisição com AES, descriptografar a resposta (cadeia multi-scripts)
Objetivo: criptografar o corpo com AES antes de enviar (apenas ciphertext na rede), descriptografar a resposta depois que ela chegar; também demonstra encadear múltiplos scripts e compartilhar dados entre eles.
Por que dá para dividir em vários scripts? Scripts da mesma cadeia compartilham
globalThis: o script ① guarda as chaves/plaintext, os scripts ②③ as recolhem. Cada script fica com um único propósito e pode ser ativado/desativado independentemente.
Cadeia de pré-envio
Script ① (prepara o contexto e as chaves):
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 ② (criptografa o corpo):
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;
}
(Opcional) o script ③ adiciona a lógica de anexação de token do Cenário 1.
Cadeia pós-resposta (descriptografar + reescrever a resposta)
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;
}
Corpo da requisição (antes da criptografia): {"order":123,"note":"secret-payload","amount":99.5}
Resultado esperado
Depois de enviar, você obtém:
{"traceId":"...","decrypted":"{\"order\":123,\"note\":\"secret-payload\",\"amount\":99.5}","roundtripOk":true,"jsonValid":true}
roundtripOk:true: o resultado descriptografado corresponde ao plaintext original byte a byte- O corpo reescrito da resposta aparece no resultado (prova de que a reescrita pós-resposta teve efeito)
⚠️ Os argumentos de
$cryptosão strings posicionais; em caso de falha ele apenas retorna uma string começando comError:— não lança exceção nem aborta (verificado: ciphertext inválido →Invalid ciphertext, key/iv errados →CryptoKit error). Plaintext em chinês / não-ASCII criptografa e descriptografa corretamente (a alegação antiga de que 'não-ASCII aborta' foi desmentida). Se precisar escrever um resultado descriptografado em um cabeçalho HTTP, garanta que o valor seja ASCII (valores de cabeçalho rejeitam não-ASCII, senão umTypeErroré lançado); coloque o conteúdo UTF-8 no corpo ou nos query params.
Cenário 3: extração · asserções · variáveis dinâmicas · assinatura
Um conjunto de automações leves — a maioria não precisa de JS algum, usando etapas declarativas de extração / asserção.
3.1 Passar um campo da resposta para a próxima requisição (extração)
- Adicione uma etapa extração à cadeia pós-resposta da requisição A: variável
author, origemresponse body JSON, expressão$.slideshow.author. - Adicione uma etapa script à cadeia de pré-envio da requisição B:
var v=sdk.env.get('author'); if(v){ request.headers.set('X-Extracted', v); } return request;
Verificado: o /echo da requisição B ecoa um cabeçalho X-Extracted que corresponde ao author da resposta da requisição A.
3.2 Asserções
Adicione etapas asserção à cadeia pós-resposta: código de status = 200, $.slideshow.title exists. Os resultados são listados um a um (pass/fail, esperado vs. real).
3.3 Variáveis dinâmicas
Escreva-as diretamente em params / headers / URL:
GET /echo?ts={{$timestamp}}&r={{$randomInt}}&u={{$uuid}}
Verificado: cada envio ecoa ts como o timestamp atual, r como um inteiro aleatório diferente e u como um UUID válido. Lista completa: concepts, variáveis dinâmicas.
3.4 Assinatura (MD5, padrão e interoperável)
Muitas APIs abertas assinam com MD5(param concatenation + secret). Use o $hash.md5, que segue o padrão verificado:
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;
}
Verificado: $hash.md5('abc') = 900150983cd24fb0d6963f7d28e17f72, correspondendo ao backend.
✅ O
$hmacnativo ($hmac.sha256(message, key)etc.) foi verificado vetor a vetor e corresponde ao HMAC RFC padrão (note a ordem dos argumentos: dados primeiro, chave depois) e pode ser usado para assinatura externa; a família$hashtambém é padrão. Apenas o$jwtdegrada payloads de objeto para[object Object](faça stringify primeiro comJSON.stringify, ou assine no servidor).
Cenário 4: reutilizar lógica compartilhada com scripts de biblioteca e require()
Objetivo: extrair 'injetar token', 'assinatura unificada' e 'logging' em unidades reutilizáveis — referencie em muitos lugares, mantenha em um só.
Duas formas de reutilizar:
- Etapa de script de biblioteca: um script completo com seu próprio
onRequest/onResponse— adicione-o como etapa e ele roda em ordem, compartilhandoglobalThiscom as outras etapas. require(): salve funções puras em uma biblioteca de scripts commodule.exportse carregue-as de qualquer script — ideal para helpers de assinatura, codecs e outros utilitários compartilhados:
// 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;
}
Use Copy require statement no gerenciador de bibliotecas para obter a forma estável de identificador. As bibliotecas integradas (@libs/base64, @libs/hex) estão disponíveis em qualquer lugar sem configuração. Mecânica completa: scripting, Require de bibliotecas de scripts.
Guia rápido de cenários
| Quero… | Quais etapas |
|---|---|
| Anexar o token automaticamente em toda API após o login | Script pós-resposta armazena + script de pré-envio lê e injeta o cabeçalho |
| Criptografar o corpo da requisição / descriptografar a resposta | $crypto.encryptAES no pré-envio + decryptAES no pós-resposta |
| Passar um campo da resposta para a próxima requisição | Etapa de extração + script que lê a variável |
| Validar códigos de status / campos | Etapa de asserção |
| Gerar valores aleatórios / timestamps a cada envio | Variáveis dinâmicas como {{$uuid}} |
| Assinar uma API aberta | $hash.md5(...) (padrão) |
| Reutilizar a mesma lógica em muitos lugares | Script de biblioteca, ou require('@libs/<key>') de uma biblioteca de scripts |