Einführung
Benutzerdefinierte Konnektoren von Microsoft Power Platform verwenden OpenAPI-Definitionen (auch als Swagger bezeichnet), um Authentifizierung, Aktionen, Trigger und deren Parameter zu beschreiben. Mit der OpenAPI-Spezifikation können Sie Erweiterungen definieren, die die Kerndefinition erweitern, um bestimmte Szenarien zu behandeln. Microsoft hat mehrere Erweiterungen der OpenAPI-Definition definiert, mit denen Sie bestimmte Funktionen konfigurieren können, die von benutzerdefinierten Konnektoren unterstützt werden.
Sie können jede Erweiterung identifizieren, indem Sie nach x-ms-<name> in den OpenAPI-Definitionen suchen. Einige dieser Definitionen haben Sie wahrscheinlich bereits verwendet, als Sie einen benutzerdefinierten Konnektor mit dem Designer konfiguriert haben, z. B. wenn Sie eine Zusammenfassung des Parameters einer Aktion eingeben, der die Erweiterung x-ms-Zusammenfassung zum Speichern des Werts in der Definition verwendet. Einige Erweiterungen können nur entweder direkt über den Swagger-Editor des Designers oder durch Exportieren der Konnektordefinitionen und anschließendes Bearbeiten und Zurückimportieren bearbeitet werden. Sie finden eine Vollständige Liste der vom benutzerdefinierten Konnektor unterstützten Erweiterungen.
In diesem Modul werden die folgenden Erweiterungen und ihre Verwendung erläutert:
x-ms-capabilities – Wird in der Definition des Anschlusses und der Betriebsebene verwendet, um die angebotenen Funktionen anzuzeigen.
x-ms-encoding – Gibt die Codierung für einen Pfadparameter an.
x-ms-dynamic-values und x-ms-dynamische-Liste – Stellen Sie dem Benutzer eine Liste mit Optionen zur Auswahl von Eingabeparametern für eine Operation zur Verfügung.
x-ms-dynamic-schema – Ermöglicht es Ihnen, Parameter und Antworten basierend auf den Ergebnissen des Schemas, das aus einer Operation in der API abgerufen wird, dynamisch zu gestalten.
Der Hauptanwendungsfall für die Konfiguration dieser Erweiterungen besteht darin, die Verwendung des Konnektors zu vereinfachen. Ohne dynamische Werte müssten Hersteller beispielsweise interne unfreundliche Schemawerte oder Zeichenfolgen für Typ-/Suchparameter kennen. Durch die Konfiguration dynamischer Werte können Sie eine benutzerfreundliche Dropdownliste bereitstellen, aus der die Hersteller auswählen können.
Beachten Sie, dass einige Erweiterungen auch Unterstützung von der API erfordern. Für ein dynamisches Schema muss die API beispielsweise eine Operation zum Abrufen des Schemas unterstützen. In Fällen, in denen Sie die API nicht steuern, können diese Erweiterungstypen möglicherweise nicht konfiguriert werden.
Erweiterungen konfigurieren
Während einige OpenAPI-Erweiterungen während der Arbeit mit Definitionen mithilfe des Designers konfiguriert werden, sind die in diesem Modul behandelten Erweiterungen nicht konfiguriert. Um diese Erweiterungen zu konfigurieren, müssen Sie einen der folgenden Ansätze verwenden:
OpenAPI importieren – Wenn Sie eine OpenAPI-Datei importieren, kann diese Microsoft OpenAPI-Erweiterungen enthalten.
Microsoft Power Platform-Konnektoren-CLI – Mit dem Befehlszeilentool paconn können Sie die API-Definitionsdatei herunterladen und mit Ihrem bevorzugten JSON-Editor bearbeiten. Wenn Sie mit der Bearbeitung fertig sind, können Sie mit paconn die geänderten Definitionen wieder in Ihre Umgebung hochladen. Dieser Ansatz ist am besten geeignet, wenn Sie andere Änderungen an der Datei API-Eigenschaften vornehmen müssen, für Verbindungsparameter zum Beispiel.
Microsoft Power Platform CLI – Mit dem Befehlszeilentool können Sie die API-Definitionsdatei für benutzerdefinierte Konnektoren mit Lösungen herunterladen und mit Ihrem bevorzugten JSON-Editor bearbeiten. Wenn Sie mit der Bearbeitung fertig sind, können Sie mit CLI die geänderten Definitionen wieder in Ihre Lösung hochladen. Dieser Ansatz ist am besten geeignet, wenn Sie andere Änderungen an der Datei API-Eigenschaften vornehmen müssen, und der benutzerdefinierte Konnektor befindet sich in einer Lösung.
Eingebauter Swagger-Editor – Der benutzerdefinierte Konnektor-Designer verfügt über einen integrierten OpenAPI-Editor, mit dem sich OpenAPI-Erweiterungen am schnellsten hinzufügen lassen.
Den Swagger-Editor verwenden
Sie können den Swagger-Editor sichtbar machen, indem Sie den Schalter Swagger Editor von einem der Schritte im benutzerdefinierten Designer aktivieren.
Wenn der Editor aktiviert ist, wird links die OpenAPI-Definition in YAML Ain't Markup Language (YAML) angezeigt, und rechts werden Validierungsmeldungen (falls vorhanden) und eine Operationsliste angezeigt.
Wenn Sie nicht mit YAML vertraut sind, handelt es sich um einen benutzerfreundlichen Standard für die Serialisierung von Daten, mit dem Sie Änderungen am YAML-Inhalt vornehmen, speichern und von der Konnektorlaufzeit verwenden können.
Die meisten Änderungen, die Sie vornehmen, haben ein Beispiel, mit dem Sie beginnen können. Ein guter Ort, um nach Änderungen in YAML zu suchen, sind andere Konnektoren, die sich im Microsoft Power Platform-Konnektor-GitHub-Repository befinden. Wenn Sie z. B. eine x-ms-capability-Erweiterung implementieren möchten, können Sie das Repository durchsuchen und sehen, wie es andere Konnektoren konfiguriert haben.
Wenn Sie den Editor verwenden, nehmen Sie am besten kleine, fokussierte Änderungen vor. Der Editor überprüft Ihre Syntax während der Eingabe und teilt Ihnen in Echtzeit mit, ob ein Fehler gemacht wurde und wo sich der Fehler befindet.
Tipps für die Arbeit mit YAML im Swagger-Editor:
Einrückung ist wichtig – Einrückung ist Teil der YAML-Spezifikationen. Beobachten Sie daher, wie Einrückungen verwendet werden, um weitere Konfigurationsspezifikationen bereitzustellen.
Offene und geschlossene Klammern {} – Wenn Sie eine offene Klammer haben {, müssen Sie auch eine geschlossene Klammer haben }.
Offene und geschlossene eckige Klammern [] – Wenn Sie eine offene eckige Klammer haben, müssen Sie auch eine geschlossene eckige Klammer haben.
STRG+F zum Suchen – Mit dieser Tastenkombination können Sie innerhalb der YAML suchen.
STRG+Z zum Rückgängig machen – Wenn Sie feststellen, dass Sie einen Fehler gemacht haben, verwenden Sie die Tastenkombination STRG+Z. Diese macht Ihre letzte Änderung rückgängig.
Im Rest dieses Moduls erfahren Sie, wie Sie einige der Microsoft OpenAPI-Erweiterungen verwenden, um die Verwendung Ihrer benutzerdefinierten Konnektoren zu vereinfachen.