Sdílet prostřednictvím

Vytváření požadavků HTTP

  • Článek

Důležité

Schopnosti a funkce Power Virtual Agents jsou nyní součástí Microsoft Copilot Studio po významných investicích do generativní umělé inteligence a vylepšených integracích napříč Microsoft Copilot.

Některé články a snímky obrazovky mohou odkazovat na Power Virtual Agents, zatímco aktualizujeme dokumentaci a obsah školení.

V Copilot Studio můžete rozšířit schopnosti kopilota voláním externích REST API pomocí uzlu HTTP požadavek. To může být užitečné, když potřebujete získat data z externího systému nebo pracovat s daty v tomto systému.

Předpoklady

Použijte uzel požadavku HTTP

  1. Vyberte Přidat uzel (+), otevřete podnabídku Rozšířené a poté vyberte Odeslat požadavek HTTP.

    Screenshot možnosti Odeslat požadavek HTTP v nabídce Rozšířené.

  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.

    Screenshot s dokončenou adresou URL rozhraní API a rozevíracím seznamem metod

  4. V sekci Záhlaví a text požadavku v uzlu klikněte na tlačítko Upravit. Otevře se podokno Vlastnosti požadavku HTTP.

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

    Screenshot se seznamem párů klíčů hodnot záhlaví pro uzel HTTP.

  6. Ve výchozím nastavení se v textu požadavku HTTP neodesílá žádný obsah, ale vy zadáte obsah, který se má odeslat v textu požadavku.

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

    Můžete zadat příklad odpovědi JSON (kterou obvykle najdete v dokumentaci k rozhraní API, které voláte), která vygeneruje proměnnou Power FX se silným typem, což vám umožní použít ji jinde ve vašem plátně pro vytváření obsahu s podporou IntelliSense v editoru Power FX. Chcete-li to provést, vyberte Z ukázkových dat a poté klikněte na možnost Získat schéma z ukázkového JSON a vložte ukázkovou odpověď do editoru, který se zobrazí, a vyberte možnost Potvrdit.

    Screenshot načtení schématu z ukázkového editoru JSON.

  8. V sekci Uložit odpověď jako vyberte, kam chcete uložit odpověď na požadavek HTTP, buď vytvořte novou proměnnou, nebo vyberte existující.

Odešlete obsah v textu požadavku HTTP

  1. V sekci Záhlaví a text požadavku v uzlu klikněte na tlačítko Upravit. Otevře se podokno Vlastnosti požadavku HTTP.

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

    Screenshot s rozevíracím seznamem možností obsahu pro text požadavku

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

      Můžete také zadat svůj obsah JSON pomocí Power FX, což vám umožní zahrnout dynamické hodnoty a referenční proměnné. Chcete-li to provést, vyberte tlačítko Upravit JSON, vyberte možnost Vzorec a poté zadejte objekt Power FX (všechny existující kódy JSON, které již byly zadány, budou převedeny na objekt Power FX), který bude převeden na kód JSON, když bude proveden požadavek HTTP.

      Screenshot obsahu JSON vybraného pro typ obsahu textu požadavku.

    • 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, jako je obsah řetězce uvedený v příkladu níže.

      Screenshot nezpracovaného obsahu vybraného pro typ obsahu textu požadavku.

Zpracování a časový limit chyb

Uzel Požadavek HTTP má několik možností pro zpracování 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, kopilot zastaví svou činnost a spustí systémové téma Chyba a zobrazí chybovou zprávu.

Můžete však nakonfigurovat zpracování chyb tak, aby se neaktivovalo systémové téma Chyba a místo toho naplníte stavový kód HTTP a libovolný text chybové zprávy do vámi zadaných proměnných, což vám umožní dotazovat se na tyto proměnné podle potřeby a téma může dále běžet. To je užitečné ve scénářích, kdy chcete, aby kopilot pokračoval v provozu, i když konkrétní požadavek HTTP selže.

Chcete-li nakonfigurovat chování zpracování chyb.

  1. V sekci Záhlaví a text požadavku v uzlu klikněte na tlačítko Upravit. Otevře se podokno Vlastnosti požadavku HTTP.

  2. Vyberte požadované chování z rozevíracího seznamu Zpracování chyb.

  3. Pokud zvolíte Při chybě pokračovat, nakonfigurujte proměnné Stavový kód a Text chybové odpovědi, a to buď vytvořením nových proměnných, nebo výběrem existujících proměnných z nástroje pro výběr.

    Screenshot zpracování chyb nakonfigurovaného tak, aby se pokračovalo při chybě, s proměnnými zadanými pro stavový kód a text chybové odpovědi.

Pokud v této ukázce kódu selže požadavek HTTP, kopilot uloží stavový kód HTTP do proměnné Topic.StatusCode a text odpovědi do proměnné Topic.ErrorResponse. Kopilot pak bude pokračovat dalšími kroky v tématu.

Typ proměnné Chybová odpověď bude Žádná. K převodu tohoto na záznam Power Fx můžete použít možnost Analyzovat uzel hodnoty.

Panel vlastností také obsahuje vlastnost Časový limit požadavku, která přijímá hodnotu v milisekundách. Výchozí hodnota je 30 sekund, ale v případě potřeby můžete tuto hodnotu změnit.