Faire des requêtes HTTP

Dans Copilot Studio, vous pouvez étendre les capacités d’un agent en appelant des API REST externes à l’aide du nœud Requête HTTP. Cet appel peut être utile lorsque vous devez récupérer les données d’un système externe ou manipuler des données dessus.

Prérequis

• Créer et modifier des sujets

Utiliser le nœud Requête HTTP

1. Sélectionnez Ajouter un nœud (+), ouvrez le sous-menu Avancé, puis sélectionnez Envoyer une requête HTTP.

   

2. Dans la zone URL, entrez l’URL pour le point de terminaison d’API que vous souhaitez appeler.

3. Sélectionnez le mode de requête approprié dans le menu déroulant. Les modes GET, POST, PATCH, PUT et DELETE sont pris en charge.

   

4. Sous En-têtes et corps dans le nœud, sélectionnez le bouton Modifier, qui ouvre le volet Propriétés de la requête HTTP.

5. Vous pouvez éventuellement ajouter un ou plusieurs en-têtes à la requête HTTP. Sélectionner le bouton Ajouter pour ajouter la clé et la valeur de chaque en-tête.

   

   Vous pouvez utiliser la section en-têtes pour passer des jetons d’authentification, un type de contenu ou tout autre en-tête requis pour l’API que vous appelez. Par exemple, vous pouvez ajouter un en-tête comme Authorization: Bearer <your_token> pour authentifier la demande.

6. Par défaut, aucun contenu n’est envoyé dans le corps de la requête HTTP, mais vous pouvez spécifier le contenu dans le corps.

7. Sur le nœud, choisissez le Type de données de réponse parmi les options disponibles.

   Vous pouvez fournir un exemple JSON réponse, que vous pouvez généralement trouver dans la documentation de l’API que vous appelez. Il génère une Power Fx variable, vous permettant de l’utiliser ailleurs dans votre canevas de création, avec prise en charge d’IntelliSense dans l’ Power Fx éditeur. Sélectionner À partir de données d’exemple puis Sélectionner Obtenir le schéma à partir d’un exemple JSON. Collez votre échantillon réponse dans l’éditeur et Sélectionner Confirmez.

8. Sous Enregistrer la réponse de l’utilisateur sous, choisissez l’emplacement où vous souhaitez stocker la réponse à la requête HTTP, soit en créant une nouvelle variable, soit en sélectionnant une variable existante.

Envoyer du contenu dans le corps de la requête HTTP

1. Sous En-têtes et corps dans le nœud, sélectionnez le bouton Modifier, qui ouvre le volet Propriétés de la requête HTTP.

2. Sous Corps, sélectionnez le type de contenu approprié. Par défaut, Corps est défini sur Aucun contenu, où aucun contenu ne doit être présent dans le corps de la requête, ce qui est le plus souvent utilisé avec la requête GET. Pour ajouter du contenu au corps, sélectionnez l’une des options disponibles.

   

   • Contenu JSON : le contenu JSON vous permet de fournir un objet JSON dans le corps de la requête. Cet objet est souvent utilisé lors de requêtes POST ou PUT. Lorsque cette option est sélectionnée, un éditeur vous permet de saisir votre contenu JSON.

     Vous pouvez également spécifier votre contenu JSON à l’aide de Power Fx, ce qui vous permet d’inclure des valeurs dynamiques et des variables de référence. Sélectionner cliquez sur le bouton Modifier JSON , choisissez Formule, puis entrez un Power Fx objet (tout JSON existant qui a été saisi est converti en un Power Fx objet pour vous), qui est converti en JSON lorsque la requête HTTP est effectuée.

     

   • Contenu brut : le contenu brut vous permet d’insérer une chaîne de données dans le corps de la requête, et cette chaîne peut être de n’importe quel type de contenu que vous spécifiez. Le contenu brut est saisi à l’aide d’une formule Power Fx, telle que la chaîne content illustrée dans l’exemple suivant.

     

Gestion des erreurs et expiration du délai

Le nœud Requête HTTP dispose de plusieurs options pour gérer les situations dans lesquelles la requête HTTP peut échouer ou renvoyer une erreur.

Par défaut, la fonctionnalité génère une erreur. Cela signifie que lorsqu’une requête HTTP renvoie une erreur ou ne parvient pas à s’exécuter, l’agent arrête son opération et déclenche la rubrique système En cas d’erreur, qui affiche un message d’erreur.

Toutefois, vous pouvez configurer la gestion des erreurs pour ne pas déclencher la rubrique système En cas d’erreur. Au lieu de cela, vous pouvez faire en sorte qu’il stocke le code d’état HTTP et tout corps de réponse d’erreur dans les variables que vous spécifiez. Vous pouvez interroger ces variables si nécessaire et la rubrique peut continuer à s’exécuter. Cette configuration est utile dans les cas où vous souhaitez que l’agent continue à fonctionner, même si une requête HTTP particulière échoue.

Pour configurer le comportement de gestion des erreurs d’un nœud Requête HTTP :

1. Sous En-têtes et corps, sélectionnez Modifier. Le volet Propriétés de la requête HTTP s’affiche.

2. Sous Gestion des erreurs, sélectionnez le comportement souhaité : Déclencher une erreur ou Continuer en cas d’erreur.

3. Si vous sélectionnez Continuer en cas d’erreur, configurez des variables pour le code de statut et le corps de la réponse à l’erreur.

   

Dans cet exemple, si la requête HTTP échoue, l’agent stocke le code de statut HTTP dans la variable Topic.StatusCode et le corps de la réponse dans la variable Topic.ErrorResponse. L’agent passe aux étapes suivantes de la rubrique.

Le type de variable Erreur réponse est Tout. Vous pouvez utiliser un nœud Analyser la valeur pour convertir cette variable en enregistrement Power Fx.

Dans le volet Propriétés de la requête HTTP, vous pouvez également définir une propriété Délai d’expiration de la requête en millisecondes. La valeur par défaut est 30 secondes.