Tworzenie żądań HTTP

Note

Funkcje opisane w tym artykule są obsługiwane przez standardowy mechanizm, który wykorzystuje opcje rozliczeniowe opisane w Licencjonowanie agentów obsługiwanych przez standardowy mechanizm. Dowiedz się, jak uzyskać dostęp do standardowych funkcji w Uzyskiwanie dostępu do standardowych agentów i przepływów agentów.

W programie Copilot Studio można rozszerzyć możliwości agenta, wywołując zewnętrzne interfejsy API REST przy użyciu węzła Żądania HTTP . To wywołanie może być przydatne, gdy trzeba pobrać dane z zewnętrznego systemu lub modyfikować dane w tym systemie.

Wymagania wstępne

• Tworzenie i edytowanie tematów

Używanie węzła żądania HTTP

1. Wybierz ikonę Dodaj węzeł pod węzłem, po którym chcesz wywołać zewnętrzny interfejs API, wskaż pozycję Zaawansowane, a następnie wybierz pozycję Wyślij żądanie HTTP.

2. W polu URL wprowadź adres URL punktu końcowego interfejsu API, który chcesz wywołać.

3. Wybierz odpowiednie żądanie Sposób z rozwijanego menu. Obsługiwane są metody GET, POST, PATCH, PUT i DELETE.

   

4. W obszarze Nagłówki i treść w węźle wybierz przycisk Edytuj , który otwiera panel właściwości żądania HTTP .

5. Można opcjonalnie dodać jeden lub więcej nagłówków do żądania HTTP. Wybierz przycisk Dodaj, aby dodać klucz i wartość każdego nagłówka.

   

   Sekcja nagłówków umożliwia przekazywanie tokenów uwierzytelniania, typu zawartości lub innych wymaganych nagłówków dla wywoływanego interfejsu API. Na przykład możesz dodać nagłówek podobny Authorization: Bearer <your_token> do uwierzytelnienia żądania.

6. Domyślnie w treści żądania HTTP nie jest wysyłana żadna zawartość, ale można określić zawartość w treści.

7. Na węźle wybierz z dostępnych opcji Typ danych odpowiedzi.

   Można podać przykładową odpowiedź JSON, którą zwykle można znaleźć w dokumentacji interfejsu API, który wywołujesz. Generuje zmienną Power Fx, co umożliwia użycie jej w innych miejscach na kanwie tworzenia aplikacji, z obsługą funkcji IntelliSense w edytorze Power Fx. Wybierz opcję Z przykładowych danych, a następnie wybierz Pobierz schemat z przykładowego kodu JSON. Wklej swoją przykładową odpowiedź do edytora i wybierz Potwierdź.

8. W sekcji Zapisz odpowiedź użytkownika jako wybierz miejsce przechowywania odpowiedzi na żądanie HTTP, tworząc nową zmienną lub wybierając istniejącą.

Wysyłanie zawartości w treści żądania HTTP

1. W obszarze Nagłówki i treść w węźle wybierz przycisk Edytuj , który otwiera panel właściwości żądania HTTP .

2. W obszarze Treść wybierz odpowiedni typ zawartości. Domyślnie opcja Treść ma ustawienie Brak zawartości, gdzie w treści żądania nie powinna być obecne żadne treści, co jest najczęściej stosowane w przypadku żądania GET. Aby dodać treść do obszaru treści, wybierz jedną z dostępnych opcji.

   

   • Zawartość obiektu JSON: zawartość JSON umożliwia dostarczenie obiektu JSON w treści żądania. Ten obiekt jest często używany podczas tworzenia żądań POST lub PUT. Po wybraniu tej opcji edytor umożliwia wprowadzenie zawartości w JSON.

     Można także określić zawartość JSON przy użyciu Power Fx, co pozwoli na dołączanie wartości dynamicznych i zmiennych odwołania. Wybierz przycisk Edytuj JSON, wybierz opcję Formuła, a następnie wprowadź obiekt Power Fx (wszelki istniejący kod JSON, który został wcześniej wprowadzony, zostanie za Ciebie przekonwertowany na obiekt Power Fx), który zostanie przekonwertowany na kod JSON w momencie wysłania żądania HTTP.

     

   • Surowa zawartość: Surowa zawartość umożliwia wstawienie ciągu danych do treści żądania, a ten ciąg może mieć dowolny określony przez Ciebie typ zawartości. Nieprzetworzoną zawartość wprowadza się za pomocą formuły Power Fx, takiej jak zawartość ciągu znaków pokazana w poniższym przykładzie.

     

Obsługa błędów i czasów oczekiwania

Węzeł Żądanie HTTP ma wiele opcji obsługi sytuacji, w których żądanie HTTP może zakończyć się niepowodzeniem lub zwrócić błąd.

Domyślnie ta funkcja zgłasza błąd. Oznacza to, że gdy żądanie HTTP zwróci błąd lub nie zostanie wykonane, agent zatrzyma swoje działanie i uruchomi temat systemowy W przypadku błędu, wyświetlając komunikat o błędzie.

Można jednak skonfigurować obsługę błędów w taki sposób, aby nie uruchamiała tematu systemowego On Error. Zamiast tego można przechowywać kod stanu HTTP i treść odpowiedzi o błędzie do zmiennych, które określisz. Możesz zbadać te zmienne w razie potrzeby, a wątek może nadal działać. Ta konfiguracja jest przydatna w scenariuszach, w których chcesz, aby agent kontynuował działanie, nawet jeśli określone żądanie HTTP zakończy się niepowodzeniem.

Aby skonfigurować zachowanie obsługi błędów węzła żądania HTTP:

1. W obszarze Nagłówki i treść wybierz pozycję Edytuj. Zostanie wyświetlony panel właściwości żądania HTTP .

2. W obszarze Obsługa błędów wybierz żądane zachowanie: Zgłoś błąd lub kontynuuj po błędzie.

3. Jeśli wybierzesz pozycję Kontynuuj po błędzie, skonfiguruj zmienne dla kodu stanu i treści odpowiedzi na błędy.

   

W tym przykładzie, jeśli żądanie HTTP zakończy się niepowodzeniem, agent przechowuje kod stanu HTTP w Topic.StatusCode zmiennej i treść odpowiedzi w zmiennej Topic.ErrorResponse . Agent przechodzi do kolejnych kroków opisanych w temacie.

Typ zmiennej Error response to Any. Możesz użyć węzła Analizowanie wartości, aby zamienić tę zmienną na rekord Power Fx.

W panelu właściwości żądania HTTP można również ustawić właściwość limitu czasu żądania w milisekundach. Wartość domyślna to 30 sekund.