Foretag HTTP-forespørgsler

  • Artikel

Vigtigt!

Power Virtual Agents-funktioner og -egenskaber er nu en del af Microsoft Copilot Studio, der følger vigtige investeringer i generativ AI og forbedrede integrationer på tværs af Microsoft Copilot.

Der refereres muligvis til nogle artikler og skærmbilleder i Power Virtual Agents, mens vi opdaterer dokumentation og undervisningsindhold.

I Copilot Studio kan du udvide en copilots muligheder ved at kalde eksterne REST-API'er ved hjælp af HTTP-anmodningsnoden. Dette kan være nyttigt, når du skal hente data fra et eksternt system eller manipulere data på det pågældende system.

Forudsætninger

Brug af HTTP-anmodningsnoden

  1. Vælg Tilføj node (+), åbn undermenuen Avanceret , og vælg derefter Send HTTP-anmodning.

    Skærmbillede af indstillingen med send HTTP-anmodning i den avancerede menu.

  2. I feltet URL-adresse skal du angive webadressen til den API slutpunkt du vil ringe til.

  3. Vælg den rette anmodning Metode på rullelisten. Metoderne HENT, POST, PATCH, PUT og SLET understøttes.

    Skærmbillede af fuldført URL-adresse til API og metode dropdown

  4. Klik på knappen Rediger under Overskrifter og brødtekst på noden. Derved åbnes ruden med egenskaber for HTTP-anmodninger.

  5. Du kan også føje en eller flere overskrifter til HTTP-anmodningen. Klik på knappen Tilføj for at tilføje nøglen og værdien i de enkelte overskrifter.

    Skærmbillede af listen over header-nøgleværdipar for HTTP-node.

  6. Der sendes som standard ikke indhold i brødteksten i HTTP-anmodningen, men du angiver, at indholdet skal sendes på brødteksten.

  7. Vælg datatypen Respons blandt de tilgængelige indstillinger i noden.

    Du kan komme med et eksempel på et JSON-svar (som du som regel kan finde i dokumentationen til den API, du kalder), som opretter en stærkt indtastet Power FX-variabel, så du kan bruge den andre steder i dit forfatterlærred med intellisense-understøttelse i Power FX-editoren. Det kan du gøre ved at vælge Fra eksempeldata og derefter klikke på Hent skema fra eksempel-JSON, indsætte eksempelresponsen i den viste editor og vælge Bekræft.

    Skærmbillede af hent skemaet fra JSON-eksempeleditoren.

  8. Under Gem svar som kan du vælge, hvor HTTP-anmodningsresponset skal gemmes, ved enten at oprette en ny variabel eller vælge en eksisterende variabel.

Sende indhold i brødteksten til HTTP-anmodningen

  1. Klik på knappen Rediger under Overskrifter og brødtekst på noden. Derved åbnes ruden med egenskaber for HTTP-anmodninger.

  2. Vælg den rette indholdstype under Brødtekst. Som standard angives dette til Intet indhold, hvor der ikke skal være indhold i brødteksten i anmodningen, som normalt bruges sammen med GET-anmodningen. Hvis du vil føje indhold til brødteksten, skal du vælge en af de tilgængelige indstillinger.

    Rulleliste med indstillinger for brødtekstindhold

    • JSON-indhold: JSON-indhold giver dig mulighed for at levere et JSON-objekt i brødteksten til anmodningen. Dette bruges ofte, når du foretager POST- eller PUT-forespørgsler. Når denne indstilling er valgt, får du vist en editor, hvor du kan angive dit JSON-indhold.

      Du kan også angive JSON-indholdet ved hjælp af Power FX, så du kan inkludere dynamiske værdier og referencevariabler. Det kan du gøre ved at markere knappen Rediger JSON, vælge Formular og derefter angive et Power FX-objekt (alle eksisterende JSON-objekter, der allerede er angivet, konverteres til et Power FX-objekt for dig), der konverteres til JSON, når HTTP-anmodningen foretages.

      Skærmbillede af JSON-indhold, der er valgt til indholdstype.

    • Råt indhold: Råt indhold giver dig mulighed for at indsætte en streng med data i brødteksten i anmodningen, og denne streng kan være af enhver indholdstype du angiver. Råt indhold angives ved hjælp af en Power FX-formular, f.eks. det strengindhold, der er vist i eksemplet nedenfor.

      Skærmbillede af RAW-indhold, der er valgt til indholdstype.

Håndtering af fejl og timeput

HTTP-anmodningsnoden har flere indstillinger til håndtering af de situationer, hvor HTTP-anmodningen kan mislykkes eller returnere en fejl.

Funktionen "Opret en fejl" vises som standard. Det betyder, at når en HTTP-anmodning returnerer en fejl eller ikke udføres, standser copiloten driften og udløser systememnet Fejl og viser en fejlmeddelelse.

Du kan dog konfigurere fejlhåndteringen til ikke at udløse Fejl-systememnet og i stedet udfylde HTTP-statuskoden og eventuelle brødtekster med fejlsvar i variabler, du angiver, så du kan afhøre variablerne efter behov og for at fortsætte med at køre emnet. Dette er nyttigt i scenarier, hvor copiloten skal fortsætte driften, også selvom en bestemt HTTP-anmodning ikke kan udføres.

Sådan konfigureres funktionsmåden for fejlhåndtering.

  1. Klik på knappen Rediger under Overskrifter og brødtekst på noden. Derved åbnes ruden med egenskaber for HTTP-anmodninger.

  2. Vælg den ønskede funktionsmåde på rullelisten Fejlhåndtering.

  3. Hvis du vælger Fortsæt ved-fejl, skal du konfigurere brødtekstvariablerne Statuskode og Fejlsvar enten ved at oprette nye variabler eller vælge eksisterende variabler fra vælgeren.

    Skærmbillede af fejlhåndtering konfigureret til at fortsætte ved fejl med variabler angivet for statuskode og brødtekst for fejlrespons.

Hvis HTTP-anmodningen mislykkes i dette kodeeksempel, gemmer copilot HTTP-statuskoden i variablen Topic.StatusCode og svarteksten i variablen Topic.ErrorResponse. Copiloten fortsætter derefter til næste trin i emnet.

Variabeltypen Fejlrespons vil være Alle. Du kan bruge noden Fortolkningsværdi til at konvertere den til en Power Fx-post.

Egenskabsruden indeholder også egenskaben Anmod om timeput, der accepterer en værdi i millisekunder. Standardværdien er 30 sekunder, men du kan ændre denne værdi efter behov.