Dynamisches Schema verwenden
Wenn Sie eine Aktion auf einem benutzerdefinierten Konnektor konfigurieren, können Sie auch Parameter konfigurieren. Diese Parameter werden durch Importieren einer OpenAPI-Definition oder einer Beispielanforderung konfiguriert. Unabhängig vom verwendeten Ansatz ist die Liste der Parameter festgelegt. Dem Entwickler wird die statische Liste der vom Konnektor definierten Parameter angezeigt, wenn diese Aktion verwendet wird. Für viele Szenarien ist dieser Ansatz geeignet, da die Listenparameter fest sind und nicht variieren. In einigen Fällen sind die Parameter, die für die Eingabe angezeigt werden sollen, variabel.
Die häufigsten Anwendungsfälle für Richtlinien sind:
Die Liste der Parameter hängt von einem Typ ab, z. B. einer Kategorie oder einem Rechnungstyp.
Der Status des Datensatzes kann bestimmen, welche Parameter geändert werden können. Beispielsweise kann eine Versandbestellung andere verfügbare Parameter haben als eine nicht versendete Bestellung.
Die Parameterliste kann aus Sicherheitsgründen gekürzt werden.
Eine gemeinsame Aktionsimplementierung für einige verschiedene Datentypen. Beispielsweise könnte die API eine Aktion Erstellen implementieren, die für Konten, Kontakte, Bestellungen oder Rechnungen gilt. Eingabeparameter werden durch den vom Entwickler ausgewählten Objekttyp definiert.
Benutzerdefinierte Konnektoren unterstützen diese Szenarien, indem Sie OpenAPI-Erweiterungen für dynamische Schemata konfigurieren können. Wenn die OpenAPI-Erweiterungen für das dynamische Schema konfiguriert sind, ruft die Laufzeit des benutzerdefinierten Konnektors eine Operation auf, um das Schema abzurufen, das definiert, welche Parameter für diese bestimmte Aktion sichtbar sein sollen. Die Schemadaten können andere Optionen enthalten, z. B. den Anzeigenamen und die Beschreibung des Parameters.
Im Beispiel der Contoso Invoicing-API für eine Fakturierungs-API, nachdem die OpenAPI-Definition importiert wurde, ähnelte die Aktion dem folgenden Bild, als sie in einem Power Automate-Flow verwendet wurden.
Das vorstehende Bild zeigt Parameter, die für das Hinzufügen einer Einkaufsrechnung im Vergleich zu einer Nicht-Einkaufsrechnung nicht relevant sind. Außerdem sind nicht alle Rechnungsfelder gültige Eingaben für die Rechnungserstellung. Zum Beispiel ist Erstellungsdatum ein Feld, das von der API festgelegt wird und nicht Teil der Benutzereingabe sein sollte. Nachdem Sie dynamische Werte für die Rechnungsart-ID und das dynamische Schema für die anderen Parameter implementiert haben, sieht die Aktion wie im folgenden Bild aus.
Wenn der Entwickler die Rechnungsart von Bestellung zu Nichtbestellung ändert, wird der Parameter Einkaufsbestellung ausgeblendet oder entsprechend angezeigt.
Die benutzerdefinierte Konnektorlaufzeit unterstützt zwei verschiedene Erweiterungen, mit denen das dynamische Schema konfiguriert werden kann. Beide erreichen das gleiche Ziel, wo die Erweiterung x-ms-dynamic-schema Version 1 und x-ms-dynamic-properties die Version 2 sind. Wenn Sie ältere Flows mithilfe Ihrer Aktion unterstützen müssen, können Sie beide Versionen auf Ihrem benutzerdefinierten Konnektor konfigurieren. Wenn Sie nur neue Flows unterstützen, können Sie nur die Erweiterung x-ms-dynamic-properties konfigurieren.
API-Unterstützung
Damit Sie ein dynamisches Schema konfigurieren können, muss die zugrunde liegende API Unterstützung bieten, indem Sie den Vorgang definieren, der das Schema zurückgibt. Wenn die API noch keine geeignete Aktion hat und Sie nicht in der Lage sind, die API zu ändern oder die Änderungen anzufordern, können Sie möglicherweise kein dynamisches Schema implementieren.
Der Vorgang, den das Schema zurückgibt, kann einen oder mehrere Parameter annehmen, die von der Laufzeit des benutzerdefinierten Konnektors übergeben werden. Diese Parameter können Konstanten sein oder andere Daten darstellen, die auf der Aktionskarte gesammelt werden. Diese Daten können von der API verwendet werden, um die Liste der Parameter zu filtern, die als Teil des Schemas zurückgegeben werden. Im vorherigen Beispiel Rechnungsart wird als Parameter an den Vorgang übergeben, um das dynamische Schema abzurufen.
Die Antwort des Vorgangs, der für das dynamische Schema verwendet wird, muss ein gültiges JSON-Schema sein. Das folgende Beispiel zeigt, was das Contoso-API-GetInvoiceSchema zurückgibt.
Beachten Sie die folgenden wichtigen Punkte zum Inhalt:
Der Typ muss angegeben werden und wird zur Identifizierung des Parameterdatentyps verwendet.
Zusammenfassung und Beschreibung werden in im Power Automate-Designer verwendet, um die Parameter für den Entwickler zu identifizieren.
Die Erweiterungseigenschaft x-ms-visibility kann angegeben werden, um zu zeigen, wo dieser Parameter Ihrer Meinung nach immer angezeigt werden sollte (Wert „wichtig“) oder ob eine Benutzeraktion erforderlich ist, um ihn dem Entwickler anzuzeigen, z. B. Erweiterten Link auf einer Flowkarte auswählen (Wert „Erweitert“). Da diese Informationen dynamisch abgerufen werden, können sie abhängig von den verfügbaren Kontextinformationen variieren.
Das erforderliche Array enthält die Liste der erforderlichen Parameter.
Die dynamische Schemaerweiterung konfigurieren
Um die Erweiterung x-ms-dynamic-schema oder die Erweiterung x-ms-dynamic-properties zu konfigurieren, müssen Sie die OpenAPI-Definition des benutzerdefinierten Konnektors direkt bearbeiten. Derzeit ist keine Unterstützung für benutzerdefinierte Konnektordesigner zum Bearbeiten dieser Werte verfügbar.
Das folgende Bild zeigt, wie die Konfiguration der AddInvoice-Parameter nach dem Import der von der API bereitgestellten OpenAPI-Definition aussah.
Das vorstehende Beispiel zeigt, dass AddInvoice ein CreateInvoiceRequest-Objekt als Eingabe verwendet. Die Eigenschaften werden durch ein referenziertes #/definitions/Invoice definiert, bei dem es sich um eine gemeinsame Definition aller Rechnungseigenschaften handelt.
Um den Aufruf der dynamischen Schemaerweiterung zu implementieren, können Sie die Eigenschaften durch die konfigurierte Erweiterung ersetzen.
Anstatt eine fest codierte Liste von Eigenschaften zu haben, wird die Operation GetInvoiceSchema aufgerufen, um die Liste basierend auf dem Parameter typeId abzurufen.
Durch die Implementierung eines dynamischen Schemas auf Ihrem benutzerdefinierten Konnektor können Sie für den Entwickler klarstellen, welche Parameter für die Aktion verwendet werden müssen.