OpenAPI-Erweiterungen verwenden
In Dieser Lerneinheit wird die Verwendung der Microsoft OpenAPI-Erweiterungen x-ms-capabilities und x-ms-url-encoding in Ihren benutzerdefinierten Konnektoren erläutert.
Mit der Erweiterung x-ms-capabilities können Sie konfigurieren, welche Funktionen der Konnektor auf Konnektor‑ und Betriebsebene bietet. Zurzeit können benutzerdefinierte Microsoft Power Platform-Konnektoren für die folgenden Optionen konfiguriert werden:
Segmentübertragung – Vorgangsebene
Testverbindung – Konnektorebene
Aktivieren Sie die Segmentübertragung
Bei der Verarbeitung von Nachrichten begrenzt die Konnektorlaufzeit den Nachrichteninhalt auf eine maximale Größe. Diese Begrenzung trägt zur Reduzierung des Aufwands bei, der durch das Speichern und Verarbeiten großer Nachrichten entsteht. Um Nachrichten zu verarbeiten, die größer als diese Grenze sind, können Konnektoren eine große Nachricht in kleinere Nachrichtenblöcke aufteilen. Auf diese Weise können Sie immer noch große Inhalte übertragen. Bei der Kommunikation mit anderen Diensten über Konnektoren kann die Laufzeit große Nachrichten verbrauchen, jedoch nur in Segmenten. Diese Bedingung bedeutet, dass Konnektoren auch Chunking unterstützen müssen und der zugrunde liegende HTTP-Nachrichtenaustausch zwischen dem Konnektor und diesen Diensten Segmentierung verwenden muss.
Damit ein benutzerdefinierter Konnektor die Segmentübertragung verwenden kann, sind die folgenden Parameter erforderlich:
Die API muss Segmentierung unterstützen. Weitere Informationen finden Sie unter Connector-Verarbeitung von Nachrichten, die in Blöcke aufgeteilt sind.
Ihr benutzerdefinierter Konnektor muss die Erweiterung der Segmentierungsübertragungsfunktion für die Aktion aktivieren.
Der Hersteller, der Ihre Konnektoraktion verwendet, muss die Segmentübertragung für den Flowschritt aktivieren.
In Ihrer benutzerdefinierten Konnektordefinition würden Sie der Operationsdefinition, für die Sie die Segmentübertragung aktivieren möchten, die folgende Logik hinzufügen.
{chunkTransfer: true}
Wenn Sie mit der heruntergeladenen Datei „apiDefinition.swagger.json“ anstelle des YAML-Editors arbeiten, würden Sie die im folgenden Screenshot gezeigte Änderung vornehmen.
Nachdem diese Änderung vorgenommen wurde, wird die Anzeige der Änderung im benutzerdefinierten Konnektordesigner nicht mehr angezeigt. Wenn die Aktion jedoch in einem Flow verwendet wird, wird die folgende Option Segmentierung zulassen in den Einstellungen des Schritts angezeigt.
Wenn die API dies unterstützt, nachdem die Segmentierung aktiviert wurde, funktionieren große Nachrichten jetzt und werden mithilfe der Segmentierung übertragen.
Testverbindung konfigurieren
Wenn Sie eine Verbindung mithilfe eines benutzerdefinierten Konnektors erstellen, wird die Verbindung standardmäßig nicht als gültig oder nicht gültig überprüft. Wenn Sie beispielsweise eine ungültige Host-URL oder einen ungültigen API-Schlüssel angegeben haben, können Sie eine Verbindung erstellen, die jedoch bei Verwendung der Verbindung möglicherweise fehlschlägt. Mit der testConnection-OpenAPI-Erweiterung können Sie einen Vorgang auf Ihrem benutzerdefinierten Konnektor angeben, der während der Verbindungserstellung ausgeführt wird, um die bereitgestellte Konfiguration zu überprüfen.
Um Verbindungstests zu implementieren, muss auf Ihrem benutzerdefinierten Konnektor eine einfache Operation definiert sein, die HTTP 200 zurückgibt (Erfolg). Dieser Vorgang kann ein bereits vorhandener Vorgang sein, den Sie bereits konfiguriert haben, oder Sie können einen speziell zum Testen der Verbindung erstellten Vorgang erstellen. Wenn Sie einen bestimmten Testvorgang konfigurieren, empfehlen wir, ihn als intern zu markieren, damit Benutzer nicht versuchen, ihn zu verwenden. Sie können auch statische Parameter an den Vorgang übergeben. Zum Beispiel, wenn Ihre Aktion ein $top-Parameter nimmt, um die Anzahl der zurückgegebenen Datensätze zu begrenzen, können Sie Parameter verwenden, um die Ergebnisse auf einen Datensatz zu beschränken.
Das folgende Beispiel zeigt die definierte ListInvoices-Operation und wie sie zum Testen der Verbindung verwendet wird, und zeigt die Konfiguration der Erweiterung Testverbindung.
Das Bearbeiten von „apiDefinition.swagger.json“ würde dem folgenden Bild ähneln.
Die Pfadcodierung konfigurieren
Die Erweiterung x-ms-url-encoding gilt für Parameter, die im Anforderungs-URL-Pfad enthalten sind.
Beispielsweise können Sie eine Aktion zum Zurückgeben von Kunden nach Land/Region mit der folgenden Anforderung definieren:
https://myapi.myservice.com/customers/{country}
In dieser Aktion wird Land zu einem Parameter, das vom Benutzer des Konnektors angegeben wird. Da diese Parameter Teil des Pfads sind, müssen sie URL-codiert sein. Standardmäßig sind Pfadparameter einzeln URL-codiert. In bestimmten Szenarien kann die zugrunde liegende API jedoch erwarten, dass die Parameter doppelt URL-codiert sind, um potenzielle Mehrdeutigkeiten aufzulösen, die durch bestimmte Zeichen wie at-Zeichen (@), Schrägstrich (/) und umgekehrten Schrägstrich (\) usw. entstehen.
Um die Doppelcodierung für einen Pfadparameter zu konfigurieren, fügen Sie dem Parameter die folgende Option hinzu:
x-ms-url-encoding: doppelt
Stellen Sie sich die API vor, die über zwei Methoden verfügt, die den Eingabepfadparameter zurückgeben, mit der Ausnahme, dass eine davon die doppelte Codierung verwendet, wie in der folgenden Abbildung dargestellt.
Wenn Sie einen Microsoft Power Automate-Flow ausführen, der beide Aktionen mit einer komplexen Eingabe aufruft, übergibt die doppelte Codierung denselben Textwert an die API, außer dass sie jetzt doppelt codiert ist.
Diese Erweiterung vereinfacht die Behandlung der Parameter, bei denen die API eine doppelte URL-Codierung erwartet, da ein Konnektorbenutzer die Pfadparameter beim Aufrufen der Aktionen nicht codieren muss.