Pular para o conteúdo principal

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.

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çãoResultado
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 novo401 (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 $crypto são strings posicionais; em caso de falha ele apenas retorna uma string começando com Error: — 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 um TypeError é 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, origem response 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 $hmac nativo ($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 $hash também é padrão. Apenas o $jwt degrada payloads de objeto para [object Object] (faça stringify primeiro com JSON.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, compartilhando globalThis com as outras etapas.
  • require(): salve funções puras em uma biblioteca de scripts com module.exports e 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 loginScript 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çãoEtapa de extração + script que lê a variável
Validar códigos de status / camposEtapa de asserção
Gerar valores aleatórios / timestamps a cada envioVariáveis dinâmicas como {{$uuid}}
Assinar uma API aberta$hash.md5(...) (padrão)
Reutilizar a mesma lógica em muitos lugaresScript de biblioteca, ou require('@libs/<key>') de uma biblioteca de scripts