Scripts globales

Configura Global Scripts en Connector Builder para ejecutar JavaScript antes o después de cada solicitud de API para un procesamiento coherente de solicitudes y respuestas.

La pestaña Scripts globales en el Creador de conectores te permite escribir JavaScript que se ejecuta antes o después de cada solicitud de API realizada por tu conector. Utiliza scripts previos a la solicitud para modificar las solicitudes salientes y scripts posteriores a la solicitud para procesar las respuestas entrantes.

Cuándo utilizar Global Scripts

Los scripts globales son útiles cuando necesitas aplicar una lógica coherente en todas las solicitudes de un conector, como por ejemplo:

• Inyectar o anular encabezados, parámetros o cuerpo de la solicitud antes de enviar
• Construir dinámicamente la URL del proveedor en función de los valores de configuración
• Transformar el cuerpo de una respuesta del proveedor antes de que se devuelva al flujo de trabajo
• Detener una solicitud basada en condiciones personalizadas sin llamar a la API del proveedor

Scripts para un solo recurso

Cada recurso también tiene su propia pestaña Scripts , junto con Parámetros, Campos de solicitud, Campos de respuesta y Diseñador de actividades. Proporciona los mismos editores de script previo a la solicitud y posterior a la solicitud , los mismos fragmentos y las done() variables y contrato que la pestaña Scripts globales en el nivel de conector.

La diferencia es el ámbito:

• Un script en la pestaña Scripts globales se ejecuta para cada solicitud que realiza el conector.
• Un script en la pestaña Scripts de un recurso se ejecuta solo para ese recurso.

Utiliza un script de recursos cuando la lógica se aplica a un punto final y un script global cuando se aplica a todo el conector.

Escribir scripts

Para abrir la pestaña Scripts globales:

1. En Integration Service, abre el Creador de conectores y selecciona tu conector personalizado.
2. Selecciona Scripts globales en la navegación superior.
3. Expande Script de solicitud previa o Script de solicitud posterior e introduce tu JavaScript.

Los scripts se ejecutan en un entorno JavaScript aislado, sin acceso a la red y sin forma de importar paquetes.

Los integrados de JavaScript estándar están disponibles: JSON, Date, Array, Object, URL, encodeURIComponent, URLSearchParams, TextEncoder, TextDecoder, btoa, atob, crypto, Blob, FormData, Headers, Intl y BigInt.

Importante:

Buffer no está disponible. Utiliza btoa y atob para la codificación base64 en su lugar.

Lo siguiente no está disponible en el sandbox:

Categoría	No disponible
Evaluación e importaciones	eval, cualquier llamada require(), una instrucción import o export de nivel superior, una expresión dinámica import(...)
Red	fetch, XMLHttpRequest, WebSocket
Temporizadores y trabajadores	setTimeout, setInterval, setImmediate, Worker, importScripts, postMessage
Runtime y globales	Deno, process, globalThis, self, window, WebAssembly, Buffer

La función done()

Cada script debe llamar a done() para indicar la finalización. done() finaliza la ejecución inmediatamente: cualquier código escrito después de done() es inalcanzable.

// 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"
});

Uso de fragmentos

Selecciona Fragmentos en el panel de script para insertar plantillas de código en el editor de script activo.

El panel Script de solicitud previa ofrece las siguientes plantillas, agrupadas en Scripts de solicitud previa:

• Actualizar URL del proveedor : establece request_vendor_path en una URL completa, reemplazando la URL del proveedor para esa solicitud.
• Usar una configuración : lee un valor de configuration (la URL base del conector, en la muestra) y lo envía al proveedor como encabezado de solicitud.
• Omitir una solicitud de proveedor : establece continue como false para que la solicitud nunca se envíe al proveedor.

El panel Script posterior a la solicitud ofrece las siguientes plantillas, agrupadas en Scripts posteriores a la solicitud:

• Actualizar el cuerpo de la respuesta : copia response_body en una variable local, le añade un campo y devuelve el cuerpo modificado.
• Generación de metadatos de SR a partir de los metadatos del proveedor : crea metadatos de campo de recursos estándar a partir de la respuesta de metadatos de un proveedor, derivando el tipo, el formato, el nombre para mostrar, la descripción, los métodos compatibles y los valores de enumeración de cada campo personalizado.

Scripts de solicitud previa

Se ejecuta un script de solicitud previa antes de enviar cada llamada a la API al proveedor. Las variables con acceso de escritura o lectura y escritura se pueden establecer a través de done().

Variable	Acceso	Descripción
request_method	Leer	Método HTTP de la llamada a la API (GET, POST, etc.).
request_vendor_method	Leer y escribir	Método HTTP que se pasará al proveedor.
request_headers	Leer	Solicitar encabezados pasados como parte de la llamada a la API.
request_vendor_headers	Leer y escribir	Encabezados que se enviarán al proveedor.
request_path	Leer	Solicitar la ruta de la llamada a la API.
request_vendor_path	Leer y escribir	Solicitar la ruta que se enviará al proveedor. Si la ruta comienza con http, se utiliza como la URL de solicitud completa.
request_path_variables	Leer	Variables de ruta extraídas de la plantilla de URL.
request_parameters	Leer	Parámetros de consulta pasados como parte de la llamada a la API.
request_vendor_parameters	Leer y escribir	Parámetros de consulta que se enviarán al proveedor.
request_body	Leer	Cuerpo de la solicitud pasado como parte de la llamada a la API, como una cadena.
request_body_raw	Leer	Cuerpo de la solicitud pasado como parte de la llamada a la API, como una cadena no procesada.
request_vendor_body	Leer y escribir	Cuerpo de la solicitud que se enviará al proveedor. Acepta cadena, lista o mapa al escribir.
request_body_map	Leer	Cuerpo de la solicitud pasado como parte de la llamada a la API, como un mapa.
request_vendor_body_map	Leer	Cuerpo de la solicitud que se enviará al proveedor, como un mapa.
request_vendor_url	Leer	URL del punto final completamente formada que se utilizará para la llamada del proveedor.
request_expression	Leer	El parámetro CEQL where se convirtió en una lista de mapas {attribute, value, operator} .
request_previous_response	Leer	Cuerpo de respuesta del recurso encadenado anterior. null si no forma parte de una cadena.
request_previous_response_headers	Leer	Encabezados de respuesta del recurso encadenado anterior. null si no forma parte de una cadena.
request_root_key	Leer y escribir	Ruta de notación de puntos para crear un subobjeto en la carga útil JSON de la solicitud (p. ej. data.record).
object_name	Leer	Nombre de objeto canónico para la solicitud.
vendor_object_name	Leer	Nombre del objeto del proveedor. Igual que object_name a menos que se anule en el recurso.
configuration	Leer	Propiedades de configuración del conector.
response_status_code	Escribir	Código de estado HTTP que se devolverá cuando continue sea false.
response_error_message	Escribir	Mensaje de error que se devolverá antes de enviar la solicitud al proveedor.
response_body	Escribir	Cuerpo de respuesta que se devolverá cuando continue sea false.
response_body_raw	Escribir	Cuerpo de la respuesta como una cadena que se devolverá cuando continue sea false.
response_root_key	Leer y escribir	Ruta de notación de puntos para limitar la respuesta a un subobjeto (p. ej. data.records).
multipart_hook_context_items	Leer y escribir	Elementos de formulario de varias partes para solicitudes de carga de archivos.
continue	Escribir	Establece en false para omitir la llamada del proveedor. El valor predeterminado es true.

Ejemplo: inyectar un encabezado dinámico desde la configuración

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

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

done({ request_vendor_headers: headers });

Ejemplo: anular la ruta de la URL del proveedor

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'
});

Ejemplo: modificar el cuerpo de la solicitud

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 posteriores a la solicitud

Un script posterior a la solicitud se ejecuta después de recibir una respuesta del proveedor. Todas las variables de solicitud previa permanecen disponibles como Lectura. Se añaden las siguientes variables específicas de respuesta, y configuration se convierte en Lectura y escritura. Las variables con acceso de escritura o lectura y escritura se pueden establecer a través de done().

Variable	Acceso	Descripción
response_iserror	Leer	true si la respuesta del proveedor indica un error (códigos de estado fuera de 200–207).
response_status_code	Leer y escribir	Código de estado HTTP del proveedor.
response_body	Leer y escribir	Cuerpo de respuesta del proveedor.
response_body_raw	Leer y escribir	Cuerpo de respuesta sin formato del proveedor, como una cadena.
response_body_raw_map	Leer	Cuerpo de respuesta sin procesar del proveedor, como un mapa.
response_body_map	Leer	Cuerpo de respuesta del proveedor, como un mapa.
response_headers	Leer y escribir	Encabezados de respuesta del proveedor.
response_error_message	Escribir	Mensaje de error a devolver. Convierte la respuesta en un error.
response_root_key	Leer y escribir	Ruta de notación de puntos para limitar la respuesta a un subobjeto (p. ej. data.records).
configuration	Leer y escribir	Propiedades de configuración del conector. Los cambios persisten en la instancia del conector.
multipart_hook_context_items	Leer y escribir	Elementos de formulario de varias partes para solicitudes de carga de archivos.
metadata_merge	Escribir	Establece en true para combinar los metadatos del proveedor con los metadatos del modelo.

Consejo:

Inicia cada script posterior a la solicitud con una protección contra errores. Si la respuesta es un error, llama a done() sin argumentos para pasarlo sin cambios.

Ejemplo: transformar el cuerpo de la respuesta

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 });

Funciones de utilidad

Las siguientes funciones de utilidad están disponibles en ambos tipos de script:

Función	Descripción
console.log()	Emite un mensaje de depuración.

Traiga su propio caso de uso del conector LLM

Si estás creando un conector para un proveedor de LLM, como un modelo autohospedado o un punto final de inferencia de terceros, los scripts globales te permiten adaptar las solicitudes y respuestas para que coincidan con el contrato esperado sin modificar cada recurso individualmente.

Consejo:

Para los proveedores de LLM comunes (AWS Bedrock, Azure OpenAI, Google Vertex AI, compatible con OpenAI V1), puedes comenzar desde una plantilla de conector que rellena previamente la configuración de autenticación y los scripts por ti. Para obtener más información, consulta Usar plantillas de conector.

Los siguientes scripts muestran una configuración completa previa y posterior a la solicitud para este escenario.

Solicitud previa: establecer encabezados de autenticación

Inserta la clave API del proveedor desde la configuración del conector y aplica el 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
});

Solicitud previa: insertar un mensaje del sistema

Establece los parámetros del modelo predeterminados y asegúrate de que haya un mensaje del sistema en cada conversación enviada al 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)
});

Posterior a la solicitud: procesar la matriz de opciones

Itera la matriz choices en la respuesta del proveedor y añade metadatos personalizados antes de volver al flujo de trabajo:

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 });

Mejores prácticas

• Llamar siempre done() : un script que no llama a done() bloquea la solicitud.
• Copiar variables antes de mutar : el tiempo de ejecución utiliza el modo estricto. Asignar primero a una variable local: var headers = request_vendor_headers; y luego modificar headers.
• No escriba código después de done() : es inaccesible.
• Comprueba null o undefined : request_body y request_vendor_body son undefined para solicitudes GET y DELETE.
• Usa continue: false para acortar : devolver una respuesta directamente sin llamar al proveedor.