HTTP-Anforderungen stellen

Wichtig

Power Virtual Agents-Fähigkeiten und -Funktionen sind jetzt Teil von Microsoft Copilot Studio nach erheblichen Investitionen in generative KI und verbesserte Integrationen in Microsoft Copilot.

Einige Artikel und Screenshots beziehen sich möglicherweise auf Power Virtual Agents während wir Dokumentation und Schulungsinhalte aktualisieren.

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

Anforderungen

• Themen erstellen und bearbeiten

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.

   

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. Klicken Sie unter Kopfzeilen und Text im Knoten auf die Schaltfläche Bearbeiten. Dadurch wird der Bereich HTTP-Anforderungseigenschaften geöffnet.

5. Sie können der HTTP-Anforderung optional einen oder mehrere Header hinzufügen. Klicken Sie auf die Schaltfläche Hinzufügen, um den Schlüssel und Wert jedes Headers hinzuzufügen.

   

6. Standardmäßig wird im Hauptteil der HTTP-Anforderung kein Text gesendet, aber Sie geben den Inhalt an, der im Text gesendet werden soll.

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 von Ihnen aufgerufenen API finden), die eine stark typisierte Power FX-Variable generiert, die es Ihnen ermöglicht, sie an anderer Stelle in Ihrem Authoring-Canvas mit Intellisense-Unterstützung im Power FX-Editor zu verwenden. Wählen Sie dazu Aus Beispieldaten aus und klicken Sie dann auf Schema aus Beispiel-JSON abrufen und fügen Sie Ihre Beispielantwort in den angezeigten Editor ein und wählen Sie Bestätigen aus.

   

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 Kopfzeilen und Text im Knoten auf die Schaltfläche Bearbeiten. Dadurch wird der Bereich HTTP-Anforderungseigenschaften geöffnet.

2. Wählen Sie unter Text den entsprechenden Inhaltstyp aus. Standardmäßig ist dies auf Kein Inhalt eingestellt, wobei im Anforderungstext kein Inhalt vorhanden sein sollte, was am häufigsten bei der GET-Anforderung verwendet wird. 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. Dies wird häufig bei POST- oder PUT-Anforderungen verwendet. Wenn diese Option ausgewählt ist, wird Ihnen ein Editor angezeigt, in den Sie Ihren JSON-Inhalt eingeben können.

     Sie können Ihren JSON-Inhalt auch mit Power FX angeben und so dynamische Werte und Referenzvariablen einbeziehen. Wählen Sie dazu die Schaltfläche JSON bearbeiten und dann Formel aus, und geben Sie dann ein Power FX-Objekt ein (ein bereits eingegebenes JSON wird 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. Der Rohinhalt wird mithilfe einer Power FX-Formel eingegeben, z. B. der im folgenden Beispiel gezeigte Zeichenfolgeninhalt.

     

Fehlerbehandlung und Timeout

Der Knoten HTTP-Anforderung verfügt über mehrere Optionen zur Behandlung von Situationen, in denen die HTTP-Anforderung möglicherweise fehlschlägt oder einen Fehler zurückgibt.

Standardmäßig löst das Feature einen Fehler aus. Das bedeutet, dass der Copilot, wenn eine HTTP-Anforderung einen Fehler zurückgibt oder nicht ausgeführt werden kann, seinen Vorgang stoppt, das Systemthema Fehler auslöst und eine Fehlermeldung anzeigt.

Sie können die Fehlerbehandlung jedoch so konfigurieren, dass das Systemthema Fehler nicht ausgelöst wird, und stattdessen den HTTP-Statuscode und alle Fehlerantworttexte in von Ihnen angegebene Variablen ausfüllen. So können Sie diese Variablen nach Bedarf abfragen und das Thema weiter ausführen. Dies ist in Szenarien nützlich, in denen der Copilot den Vorgang fortsetzen soll, auch wenn eine bestimmte HTTP-Anforderung fehlschlägt.

Zum Konfigurieren des Fehlerbehandlungsverhaltens.

1. Klicken Sie unter Kopfzeilen und Text im Knoten auf die Schaltfläche Bearbeiten. Dadurch wird der Bereich HTTP-Anforderungseigenschaften geöffnet.

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.

   

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

Der Variablentyp Fehlerantwort ist Beliebig. Sie können den Knoten „Wert parsen“ verwenden, um diesen in einen Power Fx-Datensatz umzuwandeln.

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.