Scripts globais

A guia Scripts Globais no Construtor de Conector permite que você escreva JavaScript que é executado antes ou após cada solicitação de API feita por seu conector. Use scripts pré-solicitação para modificar solicitações de saída e scripts pós-solicitação para processar respostas de entrada.

Quando usar scripts globais

Os scripts globais são úteis quando você precisa aplicar uma lógica consistente em todas as solicitações em um conector, como:

• Injetar ou substituir cabeçalhos, parâmetros ou corpo da solicitação antes de enviar
• Construindo dinamicamente o URL do fornecedor com base em valores de configuração
• Transformação do corpo da resposta de um fornecedor antes de ser retornado ao fluxo de trabalho
• Interrompendo uma solicitação com base em condições personalizadas sem chamar a API do fornecedor

Escrever scripts

Para abrir a guia Scripts globais:

1. No Integration Service, abra o Connector Builder e selecione seu conector personalizado.
2. Selecione Scripts globais na navegação superior.
3. Expanda Script pré-solicitação ou Script pós-solicitação e insira seu JavaScript.

Os scripts são executados em um ambiente JavaScript de sandbox. As seguintes restrições se aplicam:

• require() está disponível apenas para um conjunto de bibliotecas pré-aprovado (consulte Usando fragmentos). Pacotes arbitrários não podem ser importados.
• APIs de rede (fetch, XMLHttpRequest, WebSocket) não estão disponíveis.
• eval não está disponível.
• Integrações JavaScript padrão (JSON, Date, Array, Object, URL, Buffer, encodeURIComponent) estão disponíveis.

A função done()

Todo script deve chamar done() para sinalizar a conclusão. done() encerra a execução imediatamente — qualquer código escrito após done() é inacessível.

// Pass through unchanged
done();

// Override one or more output values
done({
  request_vendor_headers: updatedHeaders
});

// Return multiple overrides
done({
  request_vendor_body: newBody,
  request_vendor_headers: newHeaders
});

// Stop the request — do not call the vendor API
done({ continue: false });

// Stop the request and return an error
done({
  continue: false,
  response_status_code: 400,
  response_error_message: "Invalid action"
});

Usando fragmentos

Selecione Fragmentos no painel do script para inserir modelos de código no editor de script ativo. Os seguintes modelos estão disponíveis:

• Importar uma biblioteca — insere uma chamada require() para uma das bibliotecas pré-aprovadas disponíveis no sandbox do script: buffer, crypto, http, https, querystring, url, util, zlib, axios, lodash, jmespath, moment, request, request-promise.
• Scripts de pré-requisitos:
  • Atualizar um provedor — insere um modelo para modificar as propriedades de solicitação de saída do fornecedor.
  • Usar um objeto de configuração — insere um modelo para os valores de configuração do conector de leitura.
  • Interromper uma solicitação do provedor — insere um padrão done({ continue: false }) para interromper a solicitação sem chamar a API do fornecedor.

Scripts pré-solicitação

Um script de pré-solicitação é executado antes de cada chamada de API ser enviada ao provedor. Variáveis com acesso de Gravação ou Leitura e Gravação podem ser definidas por meio de done().

Variável	Acesso	Description
request_method	Ler	Método HTTP da chamada de API (GET, POST, etc.).
request_vendor_method	Ler e Gravar	Método HTTP que será transmitido ao provedor.
request_headers	Ler	Cabeçalhos de solicitação transmitidos como parte da chamada de API.
request_vendor_headers	Ler e Gravar	Cabeçalhos que serão enviados ao provedor.
request_path	Ler	Caminho de solicitação da chamada de API.
request_vendor_path	Ler e Gravar	O caminho da solicitação que será enviado ao provedor. Se o caminho começar com http, ele será usado como a URL completa da solicitação.
request_path_variables	Ler	Variáveis de caminho extraídas do modelo de URL.
request_parameters	Ler	Parâmetros de consulta passados como parte da chamada de API.
request_vendor_parameters	Ler e Gravar	Parâmetros de consulta que serão enviados ao provedor.
request_body	Ler	Corpo da solicitação transmitido como parte da chamada de API, como uma string.
request_body_raw	Ler	Corpo da solicitação transmitido como parte da chamada de API, como uma string não processada.
request_vendor_body	Ler e Gravar	Corpo da solicitação que será enviado ao provedor. Aceita string, lista ou mapa na gravação.
request_body_map	Ler	Corpo da solicitação passado como parte da chamada de API, como um mapa.
request_vendor_body_map	Ler	Corpo da solicitação que será enviado ao provedor, como um mapa.
request_vendor_url	Ler	URL do ponto de extremidade totalmente formado que será usada para a chamada do fornecedor.
request_expression	Ler	O parâmetro where do CEQL foi convertido em uma lista de mapas {attribute, value, operator} .
request_previous_response	Ler	Corpo de resposta do recurso encadeado anterior. null se não for parte de uma cadeia.
request_previous_response_headers	Ler	Cabeçalhos de resposta do recurso encadeado anterior. null se não for parte de uma cadeia.
request_root_key	Ler e Gravar	Caminho de notação de ponto para criar um subobjeto na carga JSON solicitada (por exemplo data.record).
object_name	Ler	Nome de objeto canônico para a solicitação.
vendor_object_name	Ler	Nome do objeto do fornecedor. Igual a object_name a não ser que seja substituído no recurso.
configuration	Ler	Propriedades de configuração do conector.
response_status_code	Gravar	Código de status HTTP a ser retornado quando continue for false.
response_error_message	Gravar	Mensagem de erro a ser retornada antes que a solicitação seja enviada ao fornecedor.
response_body	Gravar	Corpo da resposta a ser retornado quando continue for false.
response_body_raw	Gravar	Corpo da resposta como uma string a ser retornada quando continue for false.
response_root_key	Ler e Gravar	Caminho com notação de ponto para limitar a resposta a um subobjeto (por exemplo data.records).
multipart_hook_context_items	Ler e Gravar	Itens de formulário multipart para solicitações de upload de arquivos.
continue	Gravar	Defina como false para ignorar a chamada do fornecedor. O padrão é true.

Exemplo: injetar um cabeçalho dinâmico da configuração

var headers = request_vendor_headers || {};
var config = configuration || {};

headers['Authorization'] = 'Bearer ' + config['oauth_token'];

done({ request_vendor_headers: headers });

Exemplo: substituir o caminho da URL do fornecedor

var baseUrl = configuration['base_url'];
if (!baseUrl) {
  done({ continue: false, response_error_message: "Missing configuration: 'base_url'" });
  return;
}

var apiVersion = configuration['api_version'] || 'v1';
var modelId = request_path_variables.modelId;
var vendorUrl = baseUrl.startsWith('http') ? baseUrl : 'https://' + baseUrl;

done({
  request_vendor_path: vendorUrl + '/' + apiVersion + '/models/' + modelId + '/completions'
});

Exemplo: modificar o corpo da solicitação

var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});

Scripts pós-solicitação

Um script pós-solicitação é executado após uma resposta ser recebida do fornecedor. Todas as variáveis de pré-solicitação permanecem disponíveis como Leitura. As variáveis específicas de resposta abaixo são adicionadas, e configuration se torna Leitura e Gravação. Variáveis com acesso de Gravação ou Leitura e Gravação podem ser definidas por meio de done().

Variável	Acesso	Description
response_iserror	Ler	true se a resposta do fornecedor indicar um erro (códigos de status fora de 200-207).
response_status_code	Ler e Gravar	Código de status HTTP do fornecedor.
response_body	Ler e Gravar	Corpo da resposta do fornecedor.
response_body_raw	Ler e Gravar	Corpo de resposta bruta do fornecedor, como uma string.
response_body_raw_map	Ler	Corpo de resposta bruta do fornecedor, como um mapa.
response_body_map	Ler	Corpo de resposta do fornecedor, como um mapa.
response_headers	Ler e Gravar	Cabeçalhos de resposta do fornecedor.
response_error_message	Gravar	Mensagem de erro a ser retornada. Converte a resposta em um erro.
response_root_key	Ler e Gravar	Caminho com notação de ponto para limitar a resposta a um subobjeto (por exemplo data.records).
configuration	Ler e Gravar	Propriedades de configuração do conector. As alterações persistem na instância do conector.
multipart_hook_context_items	Ler e Gravar	Itens de formulário multipart para solicitações de upload de arquivos.
metadata_merge	Gravar	Defina como true para combinar metadados de fornecedor com metadados de modelo.

Dica:

Inicie cada script pós-solicitação com uma proteção de erro. Se a resposta for um erro, chame done() sem argumentos para passá-la inalterada.

Exemplo: transformar o corpo da resposta

if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

body.processed = true;
body.timestamp = new Date().toISOString();

done({ response_body: body });

Funções de utilitário

As seguintes funções de utilitário estão disponíveis em ambos os tipos de script:

Função	Description
console.log()	Gera uma mensagem de depuração.

Traga seu próprio caso de uso de conector de LLM

Se você estiver criando um conector para um provedor de LLM — como um modelo auto-hospedado ou um endpoint de inferência de terceiros — os Scripts globais permitem adaptar solicitações e respostas para corresponder ao contrato esperado sem modificar cada recurso individualmente.

Dica:

Para provedores de LLM comuns (AWS Bedrock, Azure OpenAI, Google Vertex AI, OpenAI V1 compatível), você pode começar a partir de um modelo de conector que preenche previamente a configuração de autenticação e os scripts para você. Para obter detalhes, consulte Usando modelos de conector.

Os scripts a seguir mostram uma configuração completa de pré-solicitação e pós-solicitação para esse cenário.

Pré-solicitação: definir cabeçalhos de autenticação

Injetar a chave de API do provedor da configuração do conector e impor o Content-Type esperado :

var headers = {
  'Content-Type': 'application/json',
  'x-api-key': configuration['api_key']
};

done({
  request_vendor_headers: headers,
  request_vendor_body: request_body_map
});

Pré-solicitação: injetar uma mensagem do sistema

Defina parâmetros do modelo padrão e certifique-se de que uma mensagem do sistema esteja presente em todas as conversas enviadas ao modelo:

var body = typeof request_body_map === 'string'
  ? JSON.parse(request_body_map)
  : request_body_map;

body.max_tokens = body.max_tokens || 1024;
body.temperature = 0.7;

var hasSystemMessage = body.messages.some(function(msg) {
  return msg.role === 'system';
});

if (!hasSystemMessage) {
  body.messages.unshift({
    role: 'system',
    content: 'You are a helpful assistant.'
  });
}

done({
  request_vendor_headers: { 'Content-Type': 'application/json' },
  request_vendor_body: JSON.stringify(body)
});

Pós-solicitação: processar a matriz de opções

Itere a matriz choices na resposta do fornecedor e adicione metadados personalizados antes de retornar ao fluxo de trabalho:

if (response_iserror) {
  done();
  return;
}

var body = typeof response_body === 'string'
  ? JSON.parse(response_body)
  : response_body;

if (body.choices && body.choices.length > 0) {
  body.choices.forEach(function(choice) {
    choice.processed_by = 'connector-post-script';
  });
}

body.custom_metadata = {
  processed: true,
  timestamp: new Date().toISOString()
};

done({ response_body: body });

Melhores práticas

• Sempre chamar done() — um script que não chama done() trava a solicitação.
• Copie variáveis antes de uma mutação — o runtime usa o modo restrito. Atribua primeiro a uma variável local: var headers = request_vendor_headers; e depois modifique headers.
• Não escreva código depois de done() — é inacessível.
• Verifique se há null ou undefined — request_body e request_vendor_body são undefined para solicitações GET e DELETE.
• Use continue: false para atalho — retorne uma resposta diretamente sem chamar o fornecedor.