Faire des requêtes HTTP

  • Article

Dans Copilot Studio, vous pouvez étendre les capacités d’un copilote 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.

Conditions préalables

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.

    Capture d’écran de l’option Envoyer une requête HTTP dans le menu avancé.

  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.

    Capture d’écran de l’URL de l’API complétée et de la liste déroulante des méthodes

  4. Sous En-têtes et corps sur le nœud, Sélectionner 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.

    Capture d’écran de la liste des paires clé-valeur d’en-tête pour le nœud HTTP.

  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.

    Capture d’écran du schéma Get à partir d’un exemple d’éditeur JSON.

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

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

  1. Sous En-têtes et corps sur le nœud, Sélectionner 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.

    Capture d’écran de la liste déroulante des options de contenu du corps

    • 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.

      Capture d’écran du contenu JSON sélectionné pour le type de contenu du corps.

    • 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.

      Capture d’écran du contenu RAW sélectionné pour le type de contenu du corps.

Gestion des erreurs et expiration

Le nœud de 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 caractéristique lève erreur. Cela signifie que lorsqu’une requête HTTP renvoie une erreur ou ne parvient pas à s’exécuter, le copilote cesse de fonctionner et déclenche la rubrique système Erreur, en affichant un message d’erreur.

Cependant, vous pouvez configurer la gestion des erreurs pour ne pas Gâchette l’ erreur transcription. Au lieu de cela, il remplit le code d’état HTTP et tout corps d’erreur réponse dans les variables que vous spécifiez, vous permettant d’interroger ces variables selon vos besoins et de permettre au rubrique de continuer à s’exécuter. Cette configuration est utile dans les scénarios où vous souhaitez que le copilote continue de fonctionner même si une requête HTTP particulière échoue.

Pour configurer le comportement de gestion des erreurs.

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

  2. Choisissez le comportement souhaité dans la liste déroulante Gestion des erreurs.

  3. Si vous choisissez Continuer en cas d’erreur, configurez les variables Code d’état et Corps de la réponse d’erreur, soit en créant de nouvelles variables, soit en sélectionnant des variables existantes dans le sélecteur.

    Capture d’écran de la gestion des erreurs configurée pour continuer en cas d’erreur avec des variables spécifiées pour le code d’état et le corps de la réponse d’erreur.

Dans cet exemple de code, si la requête HTTP échoue, le copilote stocke le code de statut HTTP dans la variable Topic.StatusCode et le corps de la réponse dans la variable Topic.ErrorResponse. Ensuite, le copilote continue avec ses étapes suivantes dans la rubrique.

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

Le volet des propriétés contient également une propriété Expiration de la requête, qui accepte une valeur en millisecondes. La valeur par défaut est de 30 secondes, mais vous pouvez modifier cette valeur si nécessaire.