HTTP-Anforderungen stellen

In Copilot Studio können Sie die Funktionen eines Agents erweitern, indem Sie externe REST-APIs mithilfe des HTTP-Anforderungsknotens aufrufen. Dieser Aufruf kann hilfreich sein, wenn Sie Daten von einem externen System abrufen oder Daten auf diesem System bearbeiten müssen.

Anforderungen

• Themen erstellen und bearbeiten

Verwenden des HTTP-Anforderungsknotens

1. Wählen Sie das Symbol "Knoten hinzufügen" unter dem Knoten aus, nach dem Sie eine externe API aufrufen möchten, zeigen Sie auf "Erweitert", und wählen Sie "HTTP-Anforderung senden" aus.

2. Geben Sie im Feld URL die URL für den API-Endpunkt ein, den Sie aufrufen möchten.

3. Wählen Sie die entsprechende Anforderungsmethode aus dem Dropdown-Menü aus. Unterstützt werden die Methoden GET, POST, PATCH, PUT und DELETE.

   

4. Wählen Sie unter "Kopfzeilen" und "Textkörper " auf dem Knoten die Schaltfläche "Bearbeiten " aus, die den Bereich "HTTP-Anforderungseigenschaften " öffnet.

5. Sie können der HTTP-Anforderung optional einen oder mehrere Header hinzufügen. Wählen Sie die Schaltfläche Hinzufügen aus, um den Schlüssel und den Wert der einzelnen Header hinzuzufügen.

   

   Sie können den Abschnitt "Header" verwenden, um Authentifizierungstoken, Inhaltstyp oder andere erforderliche Header für die api zu übergeben, die Sie aufrufen. Sie können z. B. einen Header hinzufügen, Authorization: Bearer <your_token> der die Anforderung authentifiziert.

6. Standardmäßig wird im Text der HTTP-Anforderung kein Inhalt gesendet, Sie können jedoch Inhalt im Text angeben.

7. Wählen Sie im Knoten den Antwortdatentyp aus den verfügbaren Optionen aus.

   Sie können eine Beispiel-JSON-Antwort bereitstellen, die Sie normalerweise in der Dokumentation der aufgerufenen API finden. Dies generiert eine Power Fx-Variable, die Sie an anderer Stelle in Ihrem Erstellungsbereich verwenden können, mit IntelliSense-Unterstützung im Power Fx-Editor. Wählen Sie Aus Beispieldaten und dann Schema aus Beispiel-JSON abrufen. Fügen Sie Ihre Beispielantwort in den Editor ein und wählen Sie Bestätigen.

8. Wählen Sie unter Benutzerantwort speichern unter aus, wo die HTTP-Anforderungsantwort gespeichert werden soll, und erstellen Sie entweder eine neue Variable oder wählen Sie eine vorhandene aus.

Inhalt des HTTP-Anforderungstextes senden

1. Wählen Sie unter "Kopfzeilen" und "Textkörper " auf dem Knoten die Schaltfläche "Bearbeiten " aus, die den Bereich "HTTP-Anforderungseigenschaften " öffnet.

2. Wählen Sie unter Text den entsprechenden Inhaltstyp aus. Standardmäßig ist Text auf Kein Inhalt eingestellt, wobei im Anforderungstext kein Inhalt vorhanden sein sollte. Dies wird am häufigsten bei der GET-Anforderung verwendet. Um dem Text Inhalt hinzuzufügen, wählen Sie eine der verfügbaren Optionen aus.

   

   • JSON-Inhalt: Mit JSON-Inhalt können Sie ein JSON-Objekt im Anforderungstext bereitstellen. Dieses Objekt wird häufig bei POST- oder PUT-Anforderungen verwendet. Wenn diese Option ausgewählt ist, können Sie Ihren JSON-Inhalt in einem Editor eingeben.

     Sie können Ihren JSON-Inhalt auch mit Power Fx angeben und so dynamische Werte und Referenzvariablen einschließen. Wählen Sie die Schaltfläche JSON bearbeiten, wählen Sie die Formel aus und geben Sie dann ein Power Fx-Objekt ein (alle vorhandenen eingegebenen JSON-Daten werden für Sie in ein Power Fx-Objekt umgewandelt), das bei der HTTP-Anforderung in JSON umgewandelt wird.

     

   • Rohinhalt: Mit Rohinhalt können Sie eine Datenzeichenfolge in den Anforderungstext einfügen. Diese Zeichenfolge kann ein beliebiger Inhaltstyp sein, den Sie angeben. Unformatierte Inhalte werden mithilfe einer Power Fx-Formel eingegeben, wie beispielsweise der im folgenden Beispiel gezeigte Zeichenfolgeninhalt.

     

Fehlerbehandlung und Timeout

Der KNOTEN "HTTP-Anforderung " verfügt über mehrere Optionen für die Behandlung von Situationen, in denen die HTTP-Anforderung fehlschlägt oder einen Fehler zurückgibt.

Standardmäßig löst die Funktion einen Fehler aus. Dies bedeutet, dass der Agent seinen Vorgang stoppt, wenn eine HTTP-Anforderung einen Fehler zurückgibt oder nicht ausgeführt werden kann, und das Systemthema bei Fehler auslöst, wo eine Fehlermeldung angezeigt wird.

Sie können die Fehlerbehandlung jedoch so konfigurieren, dass das Systemthema Bei Fehler nicht ausgelöst wird. Stattdessen können Sie festlegen, dass der HTTP-Statuscode und ein beliebiger Fehlerantworttext in Variablen gespeichert werden, die Sie angeben. Sie können diese Variablen nach Bedarf abfragen, und das Thema kann weiterhin ausgeführt werden. Diese Konfiguration ist in Szenarien nützlich, in denen der Agent den Betrieb fortsetzen soll, auch wenn eine bestimmte HTTP-Anforderung fehlschlägt.

So konfigurieren Sie das Verhalten der Fehlerbehandlung eines HTTP-Anforderungsknotens :

1. Wählen Sie unter "Kopfzeilen" und " Textkörper" die Option "Bearbeiten" aus. Der Bereich "HTTP-Anforderungseigenschaften " wird angezeigt.

2. Wählen Sie unter "Fehlerbehandlung" das gewünschte Verhalten aus: "Fehler auslösen" oder "Fehler fortsetzen".

3. Wenn Sie "Weiter beim Fehler" auswählen, konfigurieren Sie Variablen für den Statuscode und den Fehlerantworttext.

   

Wenn die HTTP-Anforderung in diesem Beispiel fehlschlägt, speichert der Agent den HTTP-Statuscode in der Topic.StatusCode Variablen und den Antworttext in der Topic.ErrorResponse Variablen. Der Agent fährt mit den nächsten Schritten im Thema fort.

Der Variablentyp Fehlerantwort lautet Beliebig. Sie können einen Parse-Wertknoten verwenden, um diese Variable in einen Power Fx-Eintrag zu konvertieren.

Im Eigenschaftenbereich "HTTP-Anforderung" können Sie auch eine Anforderungstimeouteigenschaft in Millisekunden festlegen. Der Standardwert beträgt 30 Sekunden.