Freigeben über

HTTP-Anforderungen stellen

  • Artikel

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

Anforderungen

HTTP-Anforderungsknoten verwenden

  1. Wählen Sie Knoten hinzufügen (+) aus, öffnen Sie das Untermenü Erweitert und wählen Sie dann HTTP-Anforderung senden aus.

    Screenshot der Option zum Senden der HTTP-Anforderung im Menü „Erweitert“

  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.

    Screenshot der fertigen API-URL und des Methoden-Dropdowns

  4. Klicken Sie unter Header und Text auf dem Knoten auf die Schaltfläche Bearbeiten, um den Bereich Eigenschaften der HTTP-Anforderung zu öffnen.

  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.

    Screenshot der Liste der Header-Schlüssel-Wert-Paare für den HTTP-Knoten.

  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.

    Screenshot des Beispiel-JSON-Editors „Schema vom JSON-Beispiel abrufen“.

  8. Wählen Sie unter Antwort speichern unter aus, wo die HTTP-Anfrageantwort gespeichert werden soll, indem Sie entweder eine neue Variable erstellen oder eine vorhandene auswählen.

Inhalt des HTTP-Anforderungstextes senden

  1. Klicken Sie unter Header und Text auf dem Knoten auf die Schaltfläche Bearbeiten, um den Bereich Eigenschaften der HTTP-Anforderung zu öffnen.

  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.

    Screenshot des Dropdown-Menüs mit Textinhaltsoptionen

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

      Screenshot des für den Textinhaltstyp ausgewählten JSON-Inhalts.

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

      Screenshot des für den Textinhaltstyp ausgewählten RAW-Inhalts.

Fehlerbehandlung und Timeout

Der Knoten HTTP-Anforderung verfügt über mehrere Optionen zum Umgang mit Situationen, in denen die HTTP-Anforderung fehlschlagen oder einen Fehler zurückgeben könnte.

Standardmäßig löst die Funktion „einen Fehler aus“. Das bedeutet, dass Agent den Vorgang stoppt und den Fehler Systemthema auslöst, wenn eine HTTP-Anforderung einen Fehler zurückgibt oder nicht ausgeführt werden kann. Dadurch wird eine Fehlermeldung angezeigt.

Sie können die Fehlerbehandlung jedoch so konfigurieren, dass das Systemthema Fehler nicht ausgelöst wird. Stattdessen füllt es den HTTP-Statuscode und alle Antwort-Fehlertexte in die von Ihnen angegebenen Variablen ein. So können Sie diese Variablen nach Bedarf hinterfragen und Thema weiter ausführen. Diese Konfiguration ist in Szenarien nützlich, in denen Agent den Betrieb fortsetzen soll, auch wenn eine bestimmte HTTP-Anforderung fehlschlägt.

Zum Konfigurieren des Fehlerbehandlungsverhaltens.

  1. Klicken Sie unter Header und Text auf dem Knoten auf die Schaltfläche Bearbeiten, um den Bereich Eigenschaften der HTTP-Anforderung zu öffnen.

  2. Wählen Sie Ihr gewünschtes Verhalten aus der Dropdown-Liste Fehlerbehandlung aus.

  3. Wenn Sie Bei Fehler fortfahren auswählen, konfigurieren Sie den Statuscode und die Variablen Fehlerantworttext, indem Sie entweder neue Variablen erstellen oder vorhandene Variablen aus der Auswahl auswählen.

    Screenshot der Fehlerbehandlung, die so konfiguriert ist, dass sie bei einem Fehler mit Variablen fortfährt, die für den Statuscode und den Fehlerantworttext angegeben sind.

Wenn in diesem Codebeispiel die HTTP-Anforderung fehlschlägt, speichert Agent den HTTP-Statuscode in der Topic.StatusCode Variable und den Antwort-Text in der Topic.ErrorResponse Variable. Das Agent setzt seine nächsten Schritte im Thema fort.

Der Variablentyp Fehlerantwort lautet Beliebig. Sie können den Knoten „Wert parsen“ verwenden, um diese Variable in einen Power Fx-Datensatz zu konvertieren.

Der Eigenschaftsbereich enthält außerdem eine Eigenschaft Anforderungs-Timeout, die einen Wert in Millisekunden akzeptiert. Der Standardwert beträgt 30 Sekunden, Sie können diesen Wert jedoch bei Bedarf ändern.