Scripts globaux

L’onglet Scripts globaux du générateur de connecteurs vous permet d’écrire du JavaScript qui s’exécute avant ou après chaque requête d’API effectuée par votre connecteur. Utilisez des scripts de pré-demande pour modifier les demandes sortantes et des scripts de post-demande afin de traiter les réponses entrantes.

Quand utiliser les scripts globaux

Les scripts globaux sont utiles lorsque vous devez appliquer une logique cohérente à toutes les requêtes d'un connecteur, par exemple :

• Injecter ou remplacer les en-têtes, les paramètres ou le corps de la requête avant l'envoi
• Créer dynamiquement l'URL du fournisseur en fonction des valeurs de configuration
• Transformer le corps d’une réponse de fournisseur avant qu’il soit renvoyé au workflow
• Arrêter une requête en fonction de conditions personnalisées sans faire appel à l'API du fournisseur

Écriture de scripts

Pour ouvrir l'onglet Global Scripts :

1. Dans Integration Service, ouvrez le générateur de connecteurs et sélectionnez votre connecteur personnalisé.
2. Sélectionnez Scripts globaux dans la navigation supérieure.
3. Développez Script de pré-demande ou Script de post-demande et saisissez votre JavaScript.

Les scripts s'exécutent dans un environnement JavaScript en sandbox. Les contraintes suivantes s’appliquent :

• require() est disponible uniquement pour un ensemble de bibliothèques pré-approuvées (voir Utilisation d'extraits). Les paquets arbitraires ne peuvent pas être importés.
• Les API réseau (fetch, XMLHttpRequest, WebSocket) ne sont pas disponibles.
• eval n’est pas disponible.
• Les éléments intégrés JavaScript standard (JSON, Date, Array, Object, URL, Buffer, encodeURIComponent) sont disponibles.

La fonction done()

Chaque script doit appeler done() pour signaler l'achèvement. done() arrête immédiatement l'exécution - tout code écrit après done() est inaccessible.

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

Utilisation des extraits

Sélectionnez Extraits de code dans le panneau de script pour insérer des modèles de code dans l'éditeur de script actif. Les modèles suivants sont disponibles :

• Importer une bibliothèque — Insère un appel require() pour l'une des bibliothèques pré- approuvées disponibles dans la sandbox du script : buffer, crypto, http, https, querystring, url, util, zlib, axios, lodash, jmespath, moment, request, request-promise.
• Scripts prérequis:
  • Mettre à jour un fournisseur — Insère un modèle pour modifier les propriétés de la demande du fournisseur sortant.
  • Use a config object — Insère un modèle pour lire les valeurs de configuration du connecteur.
  • Arrêter une demande de fournisseur — Insère un modèle done({ continue: false }) pour raccourcir la requête sans appeler l'API de fournisseur.

Scripts de pré-demande

Un script de pré-demande s'exécute avant l'envoi de chaque appel d'API au fournisseur. Les variables avec accès à l'écriture ou à la lecture et à l'écriture peuvent être définies via done().

Variable	Accès	Description
request_method	Lu	Méthode HTTP de l'appel d'API (GET, POST, etc.).
request_vendor_method	Lecture et écriture	Méthode HTTP qui sera transmise au fournisseur.
request_headers	Lu	Les en-têtes de requête sont transmis dans le cadre de l'appel d'API.
request_vendor_headers	Lecture et écriture	En-têtes qui seront envoyés au fournisseur.
request_path	Lu	Chemin de la demande de l’appel d’API.
request_vendor_path	Lecture et écriture	Chemin de la demande qui sera envoyé au fournisseur. Si le chemin commence par http, il est utilisé comme URL complète de la requête.
request_path_variables	Lu	Variables de chemin d'accès extraites du modèle d'URL.
request_parameters	Lu	Paramètres de requête transmis dans le cadre de l'appel d'API.
request_vendor_parameters	Lecture et écriture	Paramètres de requête qui seront envoyés au fournisseur.
request_body	Lu	Le corps de la requête est passé dans le cadre de l'appel d'API, sous forme de chaîne.
request_body_raw	Lu	Le corps de la requête est transmis dans le cadre de l'appel d'API sous la forme d'une chaîne non traitée.
request_vendor_body	Lecture et écriture	Corps de la requête qui sera envoyé au fournisseur. Accepte une chaîne, une liste ou une carte en écriture.
request_body_map	Lu	Corps de la requête transmis dans le cadre de l'appel d'API, sous forme de carte.
request_vendor_body_map	Lu	Corps de la requête qui sera envoyé au fournisseur, sous forme de carte.
request_vendor_url	Lu	URL de point de terminaison complète qui sera utilisée pour l’appel du fournisseur.
request_expression	Lu	Le paramètre CEQL where a été converti en liste de {attribute, value, operator} cartes.
request_previous_response	Lu	Corps de la réponse de la précédente ressource enchaînée. null si ne fait pas partie d’une chaîne.
request_previous_response_headers	Lu	En-têtes de réponse de la précédente ressource enchaînée. null si ne fait pas partie d’une chaîne.
request_root_key	Lecture et écriture	Chemin de notation pointée pour créer un sous-objet dans la charge utile JSON de la requête (par exemple data.record).
object_name	Lu	Nom de l'objet canonique pour la requête.
vendor_object_name	Lu	Nom de l’objet fournisseur. Identique à object_name sauf en cas d'écrasement sur la ressource.
configuration	Lu	Propriétés de configuration du connecteur.
response_status_code	Écrire	Code de statut HTTP à renvoyer lorsque continue est false.
response_error_message	Écrire	Message d’erreur à renvoyer avant l’envoi de la demande au fournisseur.
response_body	Écrire	Corps de la réponse à renvoyer lorsque continue est false.
response_body_raw	Écrire	Corps de la réponse sous forme de chaîne à renvoyer lorsque continue est false
response_root_key	Lecture et écriture	Chemin de notation pointée pour limiter la réponse à un sous-objet (par exemple data.records).
multipart_hook_context_items	Lecture et écriture	Éléments de formulaire multipart pour les demandes de téléchargement de fichiers.
continue	Écrire	Régler sur false pour ignorer l’appel du fournisseur. La valeur par défaut est true.

Exemple : injecter un en-tête dynamique à partir de la configuration

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

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

done({ request_vendor_headers: headers });

Exemple : Remplacer le chemin d'accès à l'URL du fournisseur

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

Exemple : Modifier le corps de la requête

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 de post-demande

Un script de post-demande s'exécute après la réception d'une réponse du fournisseur. Toutes les variables de pré-demande restent disponibles en tant que lecture. Les variables spécifiques aux réponses ci-dessous sont ajoutées et configuration devient une activité de type Lecture et Écriture. Les variables avec un accès Écriture ou Lecture et Écriture peuvent être définies via done().

Variable	Accès	Description
response_iserror	Lu	true si la réponse du fournisseur indique une erreur.
response_status_code	Lecture et écriture	Code de statut HTTP du fournisseur.
response_body	Lecture et écriture	Corps de la réponse du fournisseur.
response_body_raw	Lecture et écriture	Corps de la réponse brute du fournisseur, sous forme de chaîne.
response_body_raw_map	Lu	Corps de la réponse brute du fournisseur, sous forme de carte.
response_body_map	Lu	Corps de la réponse du fournisseur, sous forme de carte.
response_headers	Lecture et écriture	En-têtes de réponse du fournisseur.
response_error_message	Écrire	Message d'erreur à renvoyer. Convertit la réponse en une erreur.
response_root_key	Lecture et écriture	Chemin de notation pointée pour limiter la réponse à un sous-objet (par exemple data.records).
configuration	Lecture et écriture	Propriétés de configuration du connecteur. Les modifications seront conservées pour l’instance du connecteur.
multipart_hook_context_items	Lecture et écriture	Éléments de formulaire multipart pour les demandes de téléchargement de fichiers.
metadata_merge	Écrire	Régler sur true pour combiner les métadonnées du fournisseur avec les métadonnées du modèle.

Astuce :

Démarrez chaque script de post-demande avec un garde d'erreurs. Si la réponse est une erreur, appelez done() sans argument pour la transmettre.

Exemple : transformer le corps de la réponse

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

Fonctions utilitaires

Les fonctions utilitaires suivantes sont disponibles dans les deux types de scripts :

Function	Description
console.log()	Émet un message de débogage.

Apportez votre propre cas d'utilisation du connecteur LLM

Si vous créez un connecteur pour un fournisseur LLM, tel qu'un modèle auto-hébergé ou un point de terminaison d'inférence tiers, les scripts globaux vous permettent d'adapter les requêtes et les réponses afin qu'elles correspondent au contrat attendu sans modifier chaque ressource individuellement.

Astuce :

Pour les fournisseurs LLM courants (AWS Bedrock, Azure OpenAI, Google Vertex AI, OpenAI V1 Compatible), vous pouvez commencer par un modèle de connecteur qui pré-remplit la configuration d'authentification et les scripts pour vous. Pour plus de détails, consultez la section Utilisation de modèles de connecteur.

Les scripts suivants affichent une configuration complète de pré-demande et de post-demande pour ce scénario.

Pré-requête : définir les en-têtes d’authentification

Injectez la clé API du fournisseur à partir de la configuration du connecteur et appliquez la Content-Type attendue :

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

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

Pré-requête : injecter un message système

Définissez les paramètres du modèle par défaut et assurez-vous qu’un message système est présent dans chaque conversation envoyée au modèle :

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

Post-requête : traiter le tableau de choix

Itérez le tableau choices dans la réponse du fournisseur et ajoutez des métadonnées personnalisées avant de revenir au workflow :

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

Meilleures pratiques

• Appelez toujours done() — un script qui n’appelle pas done() bloque la requête.
• Copier les variables avant la mutation — le runtime utilise un mode strict. Affectez d'abord à une variable locale : var headers = request_vendor_headers;, puis modifiez headers.
• N'écrivez pas de code après done() , car celui-ci est inaccessible.
• Vérifiez null ou undefined — request_body et request_vendor_body sont undefined pour les requêtes GET et DELETE.
• Utilisez continue: false pour raccourcir – renvoyez une réponse directement sans appeler le fournisseur.