Tworzenie żądań HTTP

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ć pomocne, gdy jest konieczne pobranie danych z systemu zewnętrznego lub pracy z danymi 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 adresu URL wprowadź punkt końcowy adresu URL 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ładowy kod JSON odpowiedź, który zwykle można znaleźć w dokumentacji wywoływanego interfejsu API. Tworzy zmienną Power Fx, co pozwala na użycie jej w innych miejscach na kanwie tworzenia, przy czym w edytorze można użyć pomocy technicznej Power Fx. Wybierz opcję Z przykładowych danych, a następnie z przykładowej opcji Pobierz schemat z próbki JSON. Wklej przykładowy adres odpowiedź do edytora i wybierz opcję 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ć zawartość do 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. Zaznacz przycisk Edytuj JSON, wybierz opcję Formuła, a następnie wprowadź obiekt Power Fx (wszystkie wprowadzone już obiekty JSON Power Fx są konwertowane na obiekt), który jest konwertowany na JSON po wprowadzeniu żądania HTTP.

     

   • Nieprzetworzona zawartość: nieprzetworzoną zawartość umożliwia wstawianie ciągu danych do treści żądania. Może to być dowolny typ zawartości określony przez użytkownika. Nieprzetworzonej zawartości wprowadza się przy użyciu formuły Power Fx, takiej jak zawartość ciągu pokazana w następującym przykładzie.

     

Obsługa błędów i limit czasu

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 wyzwalała tematu systemowego W przypadku błędu. 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.

Zmienna Błędu odpowiedzi jest Dowolne. 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.