Tworzenie żądań HTTP

W Copilot Studio można rozszerzyć możliwości agenta, wywołując zewnętrzne interfejsy API REST przy użyciu węzła Żądanie 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życie węzła żądania HTTP

1. Wybierz Dodaj węzeł poniżej węzła, po którym chcesz wywołać zewnętrzne API, wskaż Zaawansowane i wybierz 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ęzła 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.

   

   W sekcji nagłówków możesz przekazać tokeny uwierzytelniania, typ treści lub inne wymagane nagłówki dla wywoływanego API. Na przykład możesz dodać nagłówek taki jak Authorization: Bearer <your_token>, aby uwierzytelnić żądanie.

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ęzła 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.

     

Naprawianie błędów i przekroczenie limitu czasu

Węzeł żądania HTTP zawiera wiele opcji obsługi w sytuacjach, gdy żądanie HTTP może się nie powieść 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 ustawić, aby przechowywała kod stanu HTTP i dowolną treść odpowiedzi na błąd w określonych zmiennych. W razie potrzeby można zbadać te zmienne, a wątek może być kontynuowany. 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 w przypadku błędu.

3. Jeśli wybierzesz opcję Kontynuuj w przypadku błędu, skonfiguruj zmienne dla kodu stanu i treści odpowiedzi na błąd.

   

W tym przykładzie kodu, jeśli żądanie HTTP nie powiedzie się, agent przechowuje kod statusu HTTP w zmiennej Topic.StatusCode, a 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 Parse value, aby przekonwertować tę zmienną na rekord Power Fx.

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