Vytváření požadavků HTTP

V Copilot Studio můžete rozšířit možnosti agenta voláním externích rozhraní REST API pomocí uzlu Požadavek HTTP. Toto volání může být užitečné, když potřebujete získat data z externího systému nebo manipulovat s daty v tomto systému.

Předpoklady

• Vytváření a úprava témat

Použijte uzel požadavku HTTP

1. Vyberte ikonu Přidat uzel pod uzlem, po kterém chcete volat externí rozhraní API, přejděte na Upřesnit a vyberte Odeslat požadavek HTTP.

2. V poli Adresa URL zadejte adresu URL koncového bodu rozhraní API, který chcete volat.

3. V rozevíracím seznamu vyberte příslušnou metodu požadavku. Podporovány jsou metody GET, POST, PATCH, PUT a DELETE.

   

4. V části Hlavičky a text na uzlu vyberte tlačítko Upravit, které otevře panel Vlastnosti požadavku HTTP.

5. K požadavku HTTP můžete volitelně přidat jedno nebo více záhlaví. Chcete-li přidat klíč a hodnotu každého záhlaví, vyberte tlačítko Přidat.

   

   Oddíl hlavičky můžete použít k předání ověřovacích tokenů, typu obsahu nebo jiných požadovaných hlaviček pro rozhraní API, které voláte. Například můžete přidat hlavičku, jako je Authorization: Bearer <your_token>, k ověření požadavku.

6. Ve výchozím nastavení se v těle požadavku HTTP neodesílá žádný obsah, ale můžete zadat obsah v těle.

7. V uzlu vyberte z dostupných možností Datový typ odpovědi.

   Můžete zadat ukázkovou odpověď JSON, kterou obvykle najdete v dokumentaci k rozhraní API, které voláte. Ta vygeneruje proměnnou Power Fx, kterou můžete použít jinde na vašem plátně pro vytváření obsahu s podporou intellisense v editoru Power Fx. Vyberte Z ukázkových dat a poté vyberte Získat schéma z ukázkového JSON. Vložte ukázku odpovědi do editoru a vyberte Potvrdit.

8. V části Uložit odpověď uživatele jako zvolte, kam chcete uložit odpověď požadavku HTTP, a to buď vytvořením nové proměnné, nebo výběrem existující.

Odešlete obsah v textu požadavku HTTP

1. V části Hlavičky a text na uzlu vyberte tlačítko Upravit, které otevře panel Vlastnosti požadavku HTTP.

2. V sekci Text požadavku vyberte příslušný typ obsahu. Ve výchozím nastavení je Text nastaven na Žádný obsah, kde by v textu požadavku neměl být žádný obsah, což se nejčastěji používá s požadavkem GET. Chcete-li do textu požadavku přidat obsah, vyberte jednu z dostupných možností.

   

   • Obsah JSON: Obsah JSON umožňuje zadat objekt JSON v textu požadavku. Tento objekt se často používá při vytváření požadavků POST nebo PUT. Když je vybrána tato možnost, editor vám umožní zadat obsah JSON.

     Obsah JSON můžete také zadat pomocí Power Fx, což vám umožní zahrnout dynamické hodnoty a referenční proměnné. Vyberte tlačítko Upravit JSON, zvolte Vzorec a poté zadejte objekt Power Fx ( jakýkoli existující JSON, který byl zadán, se za vás převede na objekt Power Fx), který se po provedení požadavku HTTP převede na JSON.

     

   • Nezpracovaný obsah: Nezpracovaný obsah umožňuje vložit řetězec dat do textu požadavku a tento řetězec může mít libovolný typ obsahu, který určíte. Nezpracovaný obsah se zadává pomocí vzorce Power Fx, například obsah řetězce zobrazený v následujícím příkladu.

     

Zpracování chyb a časový limit

Uzel Požadavek HTTP nabízí několik možností pro řešení situací, kdy může požadavek HTTP selhat nebo vrátit chybu.

Ve výchozím nastavení funkce vyvolá chybu. To znamená, že když požadavek HTTP vrátí chybu nebo se nepodaří provést, agent zastaví svou operaci, aktivuje systémové téma Při chybě a zobrazí chybovou zprávu.

Zpracování chyb však můžete nakonfigurovat tak, aby nespouštělo systémové téma Při chybě. Místo toho můžete nastavit, aby ukládal stavový kód HTTP a jakýkoli text chybové odpovědi do proměnných, které zadáte. Tyto proměnné můžete podle potřeby dotazovat a úloha může pokračovat v běhu. Tato konfigurace je užitečná ve scénářích, kdy chcete, aby agent pokračoval v provozu, a to i v případě, že konkrétní požadavek HTTP selže.

Pro konfiguraci chování zpracování chyb uzlu požadavku HTTP:

1. V části Záhlaví a text vyberte Upravit. Zobrazí se panel Vlastnosti požadavku HTTP.

2. V části Zpracování chyb vyberte požadované chování: Vyvolání chyby nebo Pokračovat při chybě.

3. Pokud vyberete Pokračovat při chybě, nakonfigurujte proměnné pro stavový kód a text chybové odpovědi.

   

Pokud se požadavek HTTP v tomto příkladu nezdaří, agent uloží stavový kód HTTP do proměnné Topic.StatusCode a text odpovědi do proměnné Topic.ErrorResponse. Agent pokračuje dalšími kroky v tématu.

Typ proměnné Chybová odpověď je Jakákoli. Můžete použít uzel Analyzovat hodnotu k převodu této proměnné na záznam Power Fx.

Na panelu Vlastnosti požadavku HTTP můžete také nastavit vlastnost Časový limit požadavku v milisekundách. Výchozí hodnota je 30 sekund.