Créer le workflow d’API

Créez un workflow d'API Test Manager qui appelle le 5e SDR et renvoie des données Robot structurées.

Étape 1 - Créer le workflow de l'API Test Manager

Un workflow d’API est un workflow léger publié en tant que point de terminaison de l’API. Vous en créez un qui encapsule la recherche de Recherche de Extrait Open5e 5e: une entrée, une requête HTTP, une sortie. Une fois publié, il apparaît dans l'Agent Builder comme un outil que votre agent peut appeler.

Cette étape comporte six sous-étapes; Prévoyez 10 à 15 minutes pour la réaliser.

Créer un nouveau projet de workflow d’API

Sélectionnez Créer nouveau dans votre espace de travail Cloud. Dans la boîte de dialogue Démarrer la création , choisissez Workflow d'API sous Automatisation des tâches.

La sélection du type crée le projet immédiatement, sans invite de nom, de sorte que vous le renommez à l’étape suivante.

Renommez la solution et le workflow par défaut. Ouvrez le menu contextuel de chaque nom dans l'explorateur de projet et sélectionnez Renommer:

• Nom de la solution: Monster Query - 5e SRD
• Nom du workflow: API Query - 5e Monsters

Configurer les entrées et les sorties

Sélectionnez le gestionnaire de données (icône dans le presse-papiers le long de la barre de gauche) pour accéder aux variables de données du workflow.

Ajoutez un argument d'entrée au workflow:

Nom	Saisie de texte	Requis	Description
searchName	Chaîne de caractères (string)	Oui (Yes)	Le nom du moniteur ou le nom partiel à rechercher

Ajoutez un argument de sortie:

Nom	Saisie de texte	Requis	Description
monsterResults	Tableau	Oui (Yes)	Liste des résultats Extras

Ajouter la requête HTTP

1. Dans le canevas du workflow, sélectionnez + entre les activités pour ouvrir le menu des activités. Sélectionnez HTTP. L’activité s’affiche sur le canevas sous le nom de Requête HTTP.
2. Ouvrez le menu contextuel de l'activité et sélectionnez Rename (Renommer). Nommez-le HTTP Request - Open5e Monster Query.
3. Dans le panneau Propriétés , confirmez l'Authentification est l'authentification manuelle et la méthode est GET. Toutes deux sont les valeurs par défaut d'une nouvelle activité, il n'y a donc normalement rien à modifier.
4. Définissez l'URL sur https://api.open5e.com/v2/creatures/.
5. Renommez la sortie de l'activité searchResults.

Définissez la propriété Paramètres de requête:

Ouvrez la propriété Paramètres de requête qui ouvre un éditeur de dictionnaire avec les colonnes Clé et Valeur, et ajoutez les champs suivants:

Clé (Key)	Valeur (Value)
name__icontains	l'argument d'entrée searchName - voir l'avertissement ci-dessous
document__key	srd-2014
limit	10
fields	key,name,type,size,challenge_rating,alignment

Avertissement :

name__icontains prend la variable searchName , et vous devez la choisir dans le sélecteur de variables plutôt que de la saisir. Dans le champ de valeur, commencez par saisir @ pour ouvrir le sélecteur et sélectionnez SearchName ; ne pas utiliser le sélecteur enverra l'entrée sous forme de chaîne littérale, et l'API renverra HTTP 200 sans résultat. Le champ restitue alors la valeur sous forme de puce, et la valeur stockée est $input.searchName.

Ce que chaque paramètre fait:

• name__icontains: correspondance partielle insensible à la casse; dragon renvoie « Attribuer un mot de passe rouge», « Forcer le bleu», et d'autres
• document__key: srd-2014: filtres sur le SRS 5e officiel; en l'absence, les résultats incluent chaque éditeur de la base de données, contenu tiers inclus
• limit: 10: limite les candidats à 10; suffisamment pour que l'agent raisonne sans inonder son contexte
• fields: limite la réponse aux seuls champs dont l’agent a besoin; l'objet de création v2 complet est beaucoup plus volumineux et consommerait le budget de jetons

Avertissement :

Open5e ignore les paramètres de requête qu'elle ne reconnaît pas et renvoie HTTP 200 quand même. Sortez document__key ou utilisez l’orthographe v1 document__slug et le filtre est supprimé silencieusement: l’appel réussit, l’exécution est verte et l’agent reçoit des créations de chaque éditeur au lieu du SRS. Une recherche goblin renvoie 2 résultats avec le filtre appliqué et 29 sans celui-ci, alors vérifiez que le nombre de résultats ressemble à une main plutôt qu’à un catalogue.

Référence de la propriété de la requête HTTP

L'activité expose les blocs de construction HTTP standard. La plupart des éléments que vous configurerez pour chaque API que vous appellerez; certaines que vous ignorerez pour les API publiques comme celle-ci:

• Authentification: options prédéfinies pour OAuth 2.0, Clé API et Authentification de base. Définissez sur « Authentification manuelle » ici, car Open5e n’en nécessite aucune. Pour les API authentifiées, choisissez l'option appropriée et fournissez les informations d'identification.
• En-têtes: paires clé/valeur envoyées avec chaque requête. Utilisations courantes: Authorization: Bearer <token> pour les API basées sur des jetons, Accept: application/json pour contrôler le format de la réponse et les en-têtes de contrôle de version des API.
• Corps: utilisé avec les requêtes POST, PUT et PATCH pour envoyer du JSON, des données de formulaire ou du contenu brut. Non applicable pour les requêtes GET, qui comportent des paramètres dans l'URL via des paramètres de requête.
• Paramètres de requête: paires clé/valeur ajoutées à l'URL. Pour référencer un argument de workflow, saisissez @ pour ouvrir le sélecteur de variables et sélectionnez l'argument - le champ stocke $input.<name> et l'affiche sous forme de puce. @ est le caractère de déclencheur du sélecteur, et non une syntaxe de référence que vous pouvez saisir. Voir configuration des activités pour plus d'informations sur les variables et les expressions dans Studio Web.
• Sortie (renommée en searchResults): reçoit la réponse HTTP complète y compris le code de statut, les en-têtes et le corps. Le changement de nom par défaut permet de rendre l’expression de réponse lisible.

Ajouter la réponse

1. Dans le canevas du workflow, sélectionnez + après la requête HTTP et sélectionnez Réponse.

   L'activité Response définit ce que le workflow d'API renvoie à son appelant (dans ce cas, ce que l'outil de l'agent reçoit lorsqu'il invoque le workflow). Tout ce que vous avez mis dans le corps de la réponse devient la sortie de l’outil sur laquelle l’agent raisonne.

2. Définissez le corps de la réponse sur:

   {
     "monsterResults": $context.outputs.searchResults.content.results
   }
   

$context.outputs contient chaque sortie nommée des activités de ce workflow. searchResults est la variable de sortie que vous avez renommée sur l’activité Requête HTTP; .content.results navigue dans l'enveloppe de réponse dans laquelle Open5e encapsule ses données, jusqu'au tableau réel des entrées Extras. Pour plus d'informations, consultez la documentation UiPath sur l'utilisation de JavaScript pour accéder aux données de workflow.

Tester le workflow

1. Sélectionnez Debug dans la barre d'outils.
2. Dans le panneau de saisie, définissez searchName sur dragon ou goblin et exécutez le workflow.
3. Vérifiez que la réponse inclut un tableau monsterResults avec des entrées Extra avant de continuer.

Une réponse de réussite contient jusqu'à 10 entrées, chacune avec key, name, alignment et challenge_rating, plus les objets type et size imbriqués. La recherche dans goblin renvoie Go modifications et Hub précision. Si un tableau est vide, essayez d’autres termes de recherche; chaque nom de création n’a pas une correspondance exacte dans le SRS.

Publier dans votre flux

La publication enregistre le workflow en tant que processus déployable dans Orchestrator. C’est ce qui le rend détectable dans la liste des ressources disponibles de l'Agent Builder: le générateur fait apparaître les workflows publiés de votre espace de travail, et non les brouillons enregistrés localement dans Studio Web.

1. Sélectionnez Publier dans la barre d'outils.
2. Dans la boîte de dialogue de publication, sélectionnez Pour moi afin de publier sur votre flux d'espace de travail personnel. Un flux d'espace de travail personnel est un référentiel de package privé lié à votre espace de travail Orchestrator; la publication de « Pour moi » rend ce workflow visible uniquement par vous, ce qui constitue l’étendue appropriée pour le développement et les tests. Pour de plus amples informations, consultez la section Espaces de travail personnels dans la documentation UiPath.
3. Sélectionnez Publier pour confirmer.

Remarque :

Workflow n’apparaissant pas dans Ressources disponibles à l’étape 3? Le workflow doit être publié (pas seulement enregistré) avant d'être visible en tant qu'outil. S’il ne s’affiche pas, revenez ici et confirmez que la publication est terminée, puis actualisez Agent Builder.

---

Une fois le workflow publié, il est disponible dans l'Agent Builder en tant qu'outil connectable dans la section suivante.