UiPath Documentation
integration-service
latest
false
Guide de l'utilisateur d'Integration Service
Important :
Ce contenu a été traduit à l'aide d'une traduction automatique. Les packages de connecteurs disponibles dans Integration Service sont traduits à l'aide d'un moteur de traduction. La localisation du contenu nouvellement publié peut prendre 1 à 2 semaines avant d’être disponible.

Script

Configurez les scripts du générateur de connecteurs qui exécutent JavaScript avant ou après les requêtes d’API, pour chaque requête dans un connecteur ou pour une ressource unique, et l’ordre dans lequel ils s’exécutent.

Connector Builder lets you write JavaScript that runs before or after the API requests made by your connector. Use pre-request scripts to modify outgoing requests and post-request scripts to process incoming responses. Scripts on the Global Scripts tab run for every request the connector makes, and scripts on a resource's Scripts tab run only for that resource.

When to use scripts​

Les scripts sont utiles lorsque vous devez personnaliser la façon dont votre connecteur appelle le fournisseur, 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

Scripts pour une ressource unique​

Chaque ressource dispose également de son propre onglet Scripts , ainsi que de Paramètres, de Champs de requête, de Champs de réponse et du Concepteur d'activités. Il fournit les mêmes éditeurs de script Pré-requête et Post-requête , les mêmes extraits et les mêmes variables et le même contrat done() que l'onglet Scripts globaux au niveau du connecteur.

La différence est l'étendue:

  • Un script dans l'onglet Global Scripts (Scripts globaux) s'exécute pour chaque requête effectuée par le connecteur.
  • Un script de l'onglet Scripts d'une ressource s'exécute uniquement pour cette ressource.

Utilisez un script de ressource lorsque la logique s'applique à un point de terminaison et un script global lorsqu'elle s'applique à l'ensemble du connecteur.

É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 sandboxed, sans accès au réseau et sans moyen d'importer des packages.

Les éléments intégrés JavaScript standard sont disponibles: JSON, Date, Array, Object, URL, encodeURIComponent, URLSearchParams, TextEncoder, TextDecoder, btoa, atob, crypto, Blob, FormData, Headers, Intl et BigInt.

Important :

Buffer n'est pas disponible. Utilisez btoa et atob pour l'encodage base64 à la place.

Les éléments suivants ne sont pas disponibles dans la sandbox:

CatégorieNon disponible
Évaluation et importationseval, tout appel require(), une instruction import ou export de niveau supérieur, une expression dynamique import(...)
Réseaufetch, XMLHttpRequest, WebSocket
Minuteurs et travailleurssetTimeout, setInterval, setImmediate, Worker, importScripts, postMessage
Runtime et globalsDeno, process, globalThis, self, window, WebAssembly, Buffer

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

Le panneau Script de pré-requête propose les modèles suivants, regroupés sous Scripts de pré-requête:

  • Mettre à jour l’URL du fournisseur - Définit request_vendor_path sur une URL complète, remplaçant l’URL du fournisseur pour cette demande.
  • Utiliser une configuration — Lit une valeur à partir de configuration (l'URL de base du connecteur, dans l'exemple) et l'envoie au fournisseur comme en-tête de la demande.
  • Ignorer une demande de fournisseur - Définit continue sur false pour que la demande ne soit jamais envoyée au fournisseur.

Le panneau Script Post-requête propose les modèles suivants, regroupés sous Scripts Post-requête:

  • Mettre à jour le corps de la réponse - Copie response_body dans une variable locale, y ajoute un champ et renvoie le corps modifié.
  • Génération de métadonnées SR à partir des métadonnées du fournisseur - Crée des métadonnées de champ de ressource standard à partir d’une réponse de métadonnées de fournisseur, en colonnes le type, le format, le nom complet, la description, les méthodes prises en charge et les valeurs enum de chaque champ personnalisé.

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().

VariableAccèsDescription
request_methodLuMéthode HTTP de l'appel d'API (GET, POST, etc.).
request_vendor_methodLecture et écritureMéthode HTTP qui sera transmise au fournisseur.
request_headersLuLes en-têtes de requête sont transmis dans le cadre de l'appel d'API.
request_vendor_headersLecture et écritureEn-têtes qui seront envoyés au fournisseur.
request_pathLuChemin de la demande de l’appel d’API.
request_vendor_pathLecture et écritureChemin 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_variablesLuVariables de chemin d'accès extraites du modèle d'URL.
request_parametersLuParamètres de requête transmis dans le cadre de l'appel d'API.
request_vendor_parametersLecture et écritureParamètres de requête qui seront envoyés au fournisseur.
request_bodyLuLe corps de la requête est passé dans le cadre de l'appel d'API, sous forme de chaîne.
request_body_rawLuLe 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_bodyLecture et écritureCorps de la requête qui sera envoyé au fournisseur. Accepte une chaîne, une liste ou une carte en écriture.
request_body_mapLuCorps de la requête transmis dans le cadre de l'appel d'API, sous forme de carte.
request_vendor_body_mapLuCorps de la requête qui sera envoyé au fournisseur, sous forme de carte.
request_vendor_urlLuURL de point de terminaison complète qui sera utilisée pour l’appel du fournisseur.
request_expressionLuLe paramètre CEQL where a été converti en liste de {attribute, value, operator} cartes.
request_previous_responseLuResponse body from the previous chained resource. null if not part of a chain.
request_previous_response_headersLuResponse headers from the previous chained resource. null if not part of a chain.
request_previous_vendor_pathLuThe path of the previous request in the chain. null if not part of a chain.
request_root_keyLecture et écritureChemin de notation pointée pour créer un sous-objet dans la charge utile JSON de la requête (par exemple data.record).
object_nameLuNom de l'objet canonique pour la requête.
vendor_object_nameLuNom de l’objet fournisseur. Identique à object_name sauf en cas d'écrasement sur la ressource.
configurationLuPropriétés de configuration du connecteur.
response_status_codeÉcrireCode de statut HTTP à renvoyer lorsque continue est false.
response_error_messageÉcrireMessage d’erreur à renvoyer avant l’envoi de la demande au fournisseur.
response_bodyÉcrireCorps de la réponse à renvoyer lorsque continue est false.
response_body_rawÉcrireCorps de la réponse sous forme de chaîne à renvoyer lorsque continue est false
response_root_keyLecture et écritureChemin de notation pointée pour limiter la réponse à un sous-objet (par exemple data.records).
multipart_hook_context_itemsLecture et écritureÉléments de formulaire multipart pour les demandes de téléchargement de fichiers.
continueÉcrireRé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 });
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'
});
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)
});
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().

VariableAccèsDescription
response_iserrorLutrue si la réponse du fournisseur indique une erreur.
response_status_codeLecture et écritureCode de statut HTTP du fournisseur.
response_bodyLecture et écritureCorps de la réponse du fournisseur.
response_body_rawLecture et écritureCorps de la réponse brute du fournisseur, sous forme de chaîne.
response_body_raw_mapLuCorps de la réponse brute du fournisseur, sous forme de carte.
response_body_mapLuCorps de la réponse du fournisseur, sous forme de carte.
response_headersLecture et écritureEn-têtes de réponse du fournisseur.
response_error_messageÉcrireMessage d'erreur à renvoyer. Convertit la réponse en une erreur.
response_root_keyLecture et écritureChemin de notation pointée pour limiter la réponse à un sous-objet (par exemple data.records).
configurationLecture et écriturePropriétés de configuration du connecteur. Les modifications seront conservées pour l’instance du connecteur.
multipart_hook_context_itemsLecture et écritureÉléments de formulaire multipart pour les demandes de téléchargement de fichiers.
metadata_mergeÉcrireRé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 });
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 :

FunctionDescription
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
});
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)
});
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 });
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 les déclencheurs : ignorez l’appel du fournisseur et renvoyez votre propre réponse. Les scripts post-requête s'exécuteront toujours sur cette réponse.

Ordre d’exécution​

Lorsqu'un connecteur a à la fois un script global et un script de ressource pour la même phase, les deux scripts s'exécutent, dans cet ordre:

  1. Global pre-request script
  2. Script de pré-requête de ressource
  3. The request is sent to the provider
  4. Global post-request script
  5. Script post-requête de ressource
Important :

La chaîne post-requête ne s'exécute pas en sens inverse. Le script de post-requête global reçoit d'abord la réponse brute du fournisseur et peut la modifier ou la rejeter avant l'exécution du script de post-requête de ressources.

Exemple: un script global et un script de ressource sur une même activité​

Imaginez un connecteur avec les scripts suivants:

  • Global pre-request: adds an X-Acme-Tenant header from configuration.
  • Global post-request: maps the provider's error envelope onto the matching HTTP status code.
  • GET /contacts resource: a pre-request script that maps paging parameters, and a post-request script that reshapes the payload.
OrdreScriptCe qu'il voit
1Global pre-requestLa requête telle qu'elle est générée à partir de l'entrée de l'activité.
2Resource pre-requestLa requête, y compris l'en-tête du locataire ajouté à l'étape 1.
—Provider call—
3Post-requête globaleLa réponse brute du fournisseur.
4Resource post-requestLa réponse telle qu'elle est laissée par l'étape 3.

If both pre-request scripts set Authorization, the provider receives the value from the resource script, because it runs last. If the global post-request script sets response_error_message, the request ends with that error and step 4 does not run. Setting only an error response_status_code does not stop the chain.

Lorsqu’un script de pré-requête arrête la requête​

Si un script de pré-requête globale ou de ressources appelle done() avec continue: false, la requête n'est pas envoyée au fournisseur:

  • Les scripts de pré-requête qui n’ont pas encore été exécutés sont ignorés. Par exemple, si le script de pré-requête global arrête la requête, le script de pré-demande de ressources ne s'exécute pas.
  • Both post-request scripts still run, in the usual order, on the response returned by the script that stopped the request.
  • If that script returned no response body, the post-request scripts receive an empty body: an empty array for a paginated resource, and an empty response otherwise.

Pour mettre fin à la requête avec une erreur à la place, définissez response_error_message Dans un script pré-requête ou post-requête, il termine immédiatement la requête avec cette erreur, et aucun script ne s'exécute ultérieurement, y compris les scripts post-requête. Le code de statut est la valeur de response_status_code, ou 400 s’il n’est pas défini.

Cette page vous a-t-elle été utile ?

Connecter

Besoin d'aide ? Assistance(opens in new window)

Vous souhaitez apprendre ? UiPath Academy(opens in new window)

Vous avez des questions ? UiPath Forum(opens in new window)

Rester à jour