Udostępnij za pośrednictwem

Tworzenie żądań HTTP

  • Artykuł

W Copilot Studio można rozszerzyć możliwości agenta, wywołując zewnętrzne interfejsy API REST za pomocą 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

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

  1. Wybierz opcję Dodaj węzeł (+), otwórz podmenu Zaawansowane, a następnie wybierz polecenie Wyślij żądanie HTTP.

    Zrzut ekranu opcji wysyłania żądania HTTP w menu zaawansowanym.

  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.

    Zrzut ekranu: adres URL zakończonego interfejsu API i lista rozwijana sposobów

  4. W obszarze Nagłówki i treść na węźle wybierz przycisk Edytuj, który powoduje otwarcie okienka 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.

    Zrzut ekranu przedstawiający listę par kluczy nagłówków dla węzła HTTP.

  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ść na węźle wybierz przycisk Edytuj, który powoduje otwarcie okienka 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.

    Zrzut ekranu listy rozwijanej opcji zawartości treści

    • 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.

      Zrzut ekranu przedstawiający zawartość JSON wybraną dla typ zawartości.

    • 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.

      Zrzut ekranu przedstawiający zawartość RAW wybraną dla typ zawartości.

Obsługa błędów i limit 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 należy wypełnić kod stanu HTTP oraz wszystkie treści błędów odpowiedź na określone zmienne, co pozwala na zamianę tych zmiennych w razie potrzeby i temat na kontynuowanie działania. 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.

Umożliwia skonfigurowanie zachowania obsługi błędów.

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

  2. W liście rozwijanej Obsługi błędów wybierz żądane zachowanie.

  3. W przypadku wybrania opcji Kontynuuj z błędem skonfiguruj zmienne treści Kodu stanu i Treść odpowiedzi na błąd, tworząc nowe zmienne lub wybierając istniejące zmienne wyboru.

    Zrzut ekranu przedstawiający obsługę błędów skonfigurowanych w celu kontynuowania błędu w zmiennych określonych dla treści kodu stanu i 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. Do przekonwertowania tej zmiennej na rekord Power Fx możesz użyć węzła wartości analizy.

Okienko właściwości zawiera także właściwość Limitu czasu żądania, która akceptuje wartość w milisekundach. Domyślna wartość wynosi 30 sekund, ale w razie potrzeby można zmienić tę wartość.