Udostępnij za pośrednictwem

Tworzenie żądań HTTP

  • Artykuł

W Copilot Studio programie można rozszerzyć możliwości agent, 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

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

    Zrzut ekranu przedstawiający schemat Pobierz z przykładowego edytora JSON.

  8. W obszarze Zapisz odpowiedź 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.

Naprawianie błędów i upłynięcie 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 funkcja "zgłasza błąd". Oznacza to, że gdy żądanie HTTP zwraca błąd lub nie można go wykonać, agent zatrzymuje swoją operację i wyzwala komunikat Error temat systemowy, wyświetlając komunikat o błędzie.

Można jednak skonfigurować, aby obsługa błędów nie wyzwoliła temat systemowy Błąd. 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ładowym kodzie, jeśli żądanie HTTP zakończy się niepowodzeniem, agent zapisuje kod stanu HTTP w Topic.StatusCode zmiennej, a treść odpowiedź w zmiennej Topic.ErrorResponse . Agent kontynuuje swoje kolejne kroki w temat.

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ść.