> For the complete documentation index, see [llms.txt](https://documentation.efalia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.efalia.com/documentations/efalia-process/vue-ensemble-api/connecteur-api-rest.md). # Connecteur API REST Le **connecteur ApiRest** permet d'effectuer des requêtes HTTP vers des services web REST externes depuis une opération de workflow Efalia Process. Il couvre les cas d'usage les plus courants : récupération de données JSON, envoi de formulaires, transfert de fichiers, appels avec authentification. {% hint style="info" %} **Version requise** Le connecteur `ApiRestConnector` est disponible depuis **Efalia Process 6.36.0**. {% endhint %} **Classe Java :** `com.clog.workey.connectors.ApiRestConnector` *** ## Paramètres **Entrée :** Un champ texte contenant le JSON de configuration (obligatoire) **Sortie :** Un champ texte contenant la réponse textuelle du service (obligatoire) *** ## Méthodes HTTP Supportées | Méthode | Usage | | -------- | ----------------------------------------- | | `GET` | Récupérer une ressource | | `POST` | Créer une ressource / envoyer des données | | `PUT` | Modifier une ressource | | `DELETE` | Supprimer une ressource | *** ## Exemples par Cas d'Usage ### GET — Récupérer des données JSON ```json { "url": "http://api.example.com/api/person/12", "method": "GET", "expectedType": "JSON", "jsonMappings": { "Prenom": "$.firstname", "Nom": "$.lastname", "Age": "$.age", "Hobbies": "$.hobbies[*]", "Ville": "$.address.city" } } ``` La propriété `jsonMappings` définit la ventilation automatique des données JSON reçues vers les champs Process. La clé est le **nom interne du champ Process**, la valeur est l'**expression JSONPath** pointant vers la donnée dans la réponse. Les champs multivalués (comme `Hobbies`) reçoivent les valeurs d'un tableau JSON. *** ### GET — Récupérer un texte simple ```json { "url": "http://api.example.com/api/service/status", "method": "GET", "expectedType": "TEXT" } ``` La réponse est stockée telle quelle dans le champ de sortie. *** ### GET — Télécharger un fichier ```json { "url": "https://api.example.com/documents/uuid/binaire", "method": "GET", "expectedType": "BINARY", "retrievedBinary": { "designerName": "champPieceJointe", "filename": "document.pdf" } } ``` * `designerName` : nom interne du composant Pièce Jointe qui recevra le fichier * `filename` : nom de fichier à utiliser (optionnel si le serveur distant le fournit) *** ### GET — Récupérer plusieurs fichiers (multipart) ```json { "url": "http://api.example.com/multipart-response", "method": "GET", "expectedType": "MULTIPART_FORM_DATA", "retrievedMultipart": { "filePartNames": { "facture": { "designerName": "PJ_Facture", "filename": "facture.pdf" }, "annexe[]": { "designerName": "PJ_Annexes" } }, "fieldPartNames": { "lastname": "Nom", "firstname": "Prenom" } } } ``` *** ### POST — Envoyer un formulaire ```json { "url": "http://api.example.com/api/submit", "method": "POST", "contentType": "FORM_DATA", "formData": { "firstname": "champ_prenom", "lastname": "champ_nom", "status": "#Soumis" }, "expectedType": "JSON", "jsonMappings": { "Identifiant_retour": "$.id" } } ``` *** ### POST — Envoyer du JSON ```json { "url": "http://api.example.com/api/persons", "method": "POST", "contentType": "JSON", "jsonBody": "champJsonAEnvoyer", "expectedType": "JSON", "jsonMappings": { "Identifiant_cree": "$.id" } } ``` Le champ `champJsonAEnvoyer` contient le texte JSON à transmettre. Ce JSON peut contenir des **parties variables** substituées au moment de l'exécution : ```json { "id": "{champ_id_process}", "lastname": "{champ_nom}", "firstname": "{champ_prenom}", "city": "Paris" } ``` *** ### POST — Envoyer un fichier (binaire) ```json { "url": "http://api.example.com/upload", "method": "POST", "contentType": "BINARY", "sentBinary": "champ_pj_source", "expectedType": "JSON", "jsonMappings": { "Resultat": "$.message" } } ``` *** ### POST — Envoyer plusieurs fichiers (multipart) ```json { "url": "http://api.example.com/upload/", "method": "POST", "contentType": "MULTIPART_FORM_DATA", "sentMultipart": { "filePartNames": { "file": "PJ_Principal", "annexe[]": "PJ_Annexes" }, "fieldPartNames": { "firstname": "champ_prenom", "lastname": "champ_nom", "status": "#Soumis" } }, "expectedType": "JSON" } ``` Le suffixe `[]` sur un nom de champ fichier envoie **tous les fichiers** du composant Pièce Jointe. Sans `[]`, seul le premier est envoyé. *** ### DELETE — Supprimer une ressource ```json { "url": "https://api.example.com/api/person/{id_personne}", "method": "DELETE", "expectedType": "JSON", "jsonMappings": { "Resultat": "$.message" } } ``` *** ## Fonctionnalités Avancées ### Variables et Substitution Définissez des variables pour composer dynamiquement l'URL et les données envoyées : ```json { "variables": { "personId": "champ_uuid", "apiKey": "com.clog.workey.weather.api.key" }, "method": "GET", "url": "http://api.example.com/person/{personId}/details" } ``` **Règles de résolution :** **Politique n°1** (URL, JSON envoyé) — Pour `{partie_variable}` : 1. Cherche dans les variables définies 2. Cherche un champ Process de même nom 3. Sinon, utilise la valeur telle quelle **Politique n°2** (en-têtes, queryStrings, formData) — Pour une valeur : 1. Si commence par `#` → valeur littérale (sans le `#`) 2. Cherche dans les variables 3. Cherche un champ Process 4. Sinon, valeur telle quelle {% hint style="success" %} Pour les clés d'API et mots de passe, utilisez le système de variables pointant vers des propriétés `catalina.properties`. Ces valeurs ne sont jamais inscrites dans les journaux. {% endhint %} ### En-têtes HTTP ```json { "headers": { "x-api-key": "com.clog.workey.myapi.key", "Accept": "#application/json", "Authorization": "com.clog.workey.myapi.bearer" } } ``` ### QueryStrings ```json { "queryStrings": { "search": "champ_recherche", "maxItems": "#100" }, "url": "https://api.example.com/api/search" } ``` L'URL résultante sera : `https://api.example.com/api/search?search=&maxItems=100` ### Traitement Groovy de la réponse Pour les cas complexes non couverts par `jsonMappings`, utilisez un script Groovy : ```json { "url": "https://api.example.com/api/person/23", "method": "GET", "callbackScript": "monScript.groovy" } ``` Le fichier `monScript.groovy` doit être placé dans `$WORKEY_DATA/scripts/`. **Variables disponibles dans le script :** | Variable | Description | | ---------- | --------------------------------- | | `params` | Paramètres d'entrée du connecteur | | `document` | Document Process courant | | `response` | Corps de la réponse HTTP | | `result` | Tableau de sortie à renseigner | ```groovy import groovy.json.JsonSlurper JsonSlurper slurper = new JsonSlurper() def data = slurper.parse(response.toString().getBytes()) result = [data.lastname, data.firstname, data.city] ``` *** ## Débogage Pour activer les journaux détaillés de l'ApiRestConnector, ajoutez dans `catalina.properties` : ```properties com.clog.workey.connectors.ApiRestConnector.debug=true ``` Les échanges HTTP (requête + réponse) apparaîtront dans `catalina.out`. *** ## Types de Fichiers Autorisés Pour les requêtes récupérant des fichiers, le contrôle des **types de fichiers autorisés** configuré dans l'administration Process s'applique. Vérifiez que les extensions reçues sont autorisées dans **Administration > Paramètres > Types de fichiers autorisés**. *** ## Questions Fréquentes
Comment passer un token Bearer en en-tête ? ```json { "variables": { "token": "com.clog.workey.myapi.token" }, "headers": { "Authorization": "Bearer {token}" }, "url": "https://api.example.com/resource", "method": "GET" } ``` La variable `token` est résolue depuis `catalina.properties` pour éviter d'exposer le token dans la modélisation.
Comment gérer les erreurs HTTP (4xx, 5xx) ? En cas d'erreur HTTP, le connecteur lève une exception qui fait échouer l'opération. Pour un traitement conditionnel, utilisez le script Groovy de callback qui a accès au statut HTTP de la réponse.
L'URL peut-elle contenir des caractères spéciaux ? Les queryStrings sont encodées automatiquement. Pour les parties variables de l'URL, les caractères spéciaux sont également encodés lors de la substitution.
*** Pour aller plus loin : * [Syntaxes JSON/JSONPath](/documentations/efalia-process/vue-ensemble-api/syntaxes-json-jsonpath.md) * [Connecteurs Génériques](/documentations/efalia-process/vue-ensemble/connecteurs-generiques.md) * [Vue d'Ensemble API](/documentations/efalia-process/vue-ensemble-api.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.efalia.com/documentations/efalia-process/vue-ensemble-api/connecteur-api-rest.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.