Die dynamische Liste der Werteerweiterungen verwenden
Wenn Sie einen Parameter für eine Aktion auf einem benutzerdefinierten Konnektor konfigurieren, ist die Erfahrung des Standardentwicklers zur Eingabe des Parameterwerts ein einfaches Textfeld. Wenn Sie einen Parameter auf einer Aktion Rechnung hinzufügen mit dem Namen Rechnungsart-ID haben, würde die Herstellererfahrung ähnlich wie im folgenden Bild aussehen.
Der Entwickler müsste die richtigen Werte für das Feld Rechnungsart-ID kennen, das in diesem Beispiel die folgenden Werte sind.
| Wert | Beschriftung |
|---|---|
| 1 | Einkaufsbestellung |
| 2 | Keine Einkaufsbestellung |
Ein Entwickler müsste 1 eingeben, um anzuzeigen, dass die Rechnung vom Typ Einkaufsbestellung ist. Um diese OpenAPI-Definition zu vereinfachen, sollten Sie das Enumerationsschlüsselwort unterstützen. Sie können eine Aufzählung mit einer Liste von Werten definieren, aus denen der Entwickler auswählen kann.
Sie können eine Aufzählung mithilfe des benutzerdefinierten Konnektordesigners konfigurieren, indem Sie die Parameterkonfiguration bearbeiten. Wenn Sie in der Konfiguration Statisch im Bereich Dropdowntyp auswählen, können Sie eine durch Kommas getrennte Liste von Werten bereitstellen. Der folgende Screenshot zeigt, wie die Rechnungsart-ID-Konfiguration aussehen würde.
Sie können auch den Swagger-Editor verwenden und die Aufzählung hinzufügen, wie im folgenden Bild gezeigt.
Darüber hinaus, wenn Sie sich die Entwicklerumgebung in Power Automate angesehen haben, würde es nun dem folgenden Bild ähneln.
Während die Erfahrung verbessert wird, muss der Entwickler dennoch wissen, was der Wert von 1 oder 2 bedeutet. Sie können die Bedeutung dieser Werte in der Parameterbeschreibung beschreiben, um den Prozess für Entwickler zu vereinfachen. Die Verwendung von Aufzählungen eignet sich am besten zur Selbstbeschreibung von Daten, z. B. wenn Sie einen Parameter für Tage fällig haben und eine Aufzählung für 30,60,90 benutzen, das wäre einfach zu verstehen und zu benutzen. Eine weitere Einschränkung bei der Verwendung von der Aufzählung besteht darin, dass Sie die benutzerdefinierte Konnektoraufzählungsdefinition bearbeiten und die aktualisierte Version des Konnektors veröffentlichen müssen, wenn die API neue zulässige Werte hinzufügt. Um die Erfahrung weiter zu verbessern, hat Microsoft die OpenAPI-Erweiterung x-ms-dynamic-values hinzugefügt.
Dynamische Werte konfigurieren
Sie können die Erweiterung x-ms-dynamic-values eines Parameters konfigurieren, damit die Liste der Werte von der zugrunde liegenden API abgerufen wird.
Die Vorteile dieses Ansatzes sind:
Sie können eine Bezeichnung konfigurieren, die der Benutzer zusätzlich zum Wert sieht.
Die zurückgegebenen Werte repräsentieren immer die korrekten Werte aus der API.
Die API kann die Liste der Werte basierend auf Sicherheit oder anderen Anforderungen pro Benutzer oder pro Verbindung kürzen.
Andere Parameterwerte können an die API übergeben werden, um das Filtern der zurückgegebenen Liste zu ermöglichen.
Die Ausgabe eines Feldes kann als Eingabeparameter für einen anderen API-Aufruf verwendet werden, sodass abhängige Optionen wie Länder‑/Regionen‑ und Statuslisten erstellt werden können.
Die API, mit der Sie arbeiten, muss eine Operation bereitstellen, die ein Array gültiger Werte und optional deren Beschreibungen zurückgibt. Um das vorherige Beispiel von Rechnungsart-ID zu unterstützen, stellte die API eine ListInvoiceTypes-Operation bereit, die die folgenden Daten zurückgab.
Im benutzerdefinierten Konnektordesigner für das Parameter Rechnungsart-ID können Sie die Erweiterung x-ms-dynamic-values durch Auswahl von Dynamisch und dann der Angabe einer Betriebs-ID und der Eigenschaften Wert und Wert-Anzeigename festlegen. Der folgende Screenshot zeigt die Konfiguration für die Rechnungsart-ID.
Sie können auch die Erweiterung x-ms-dynamic-values mit dem Swagger-Editor konfigurieren.
Die Verwendung des Swagger-Editors oder das Herunterladen und Bearbeiten der JSON-Datei ist erforderlich, wenn Sie Parameter für die Erweiterung konfigurieren.
Nachdem die Erweiterung konfiguriert wurde, wird dem Entwickler eine benutzerfreundlichere Umgebung geboten, wenn er die Aktion verwendet.
In Ergänzung zur Eigenschaft x-ms-dynamic-values hat Microsoft auch eine neuere Erweiterung namens x-ms-dynamic-list implementiert. Im Konzept erreichen beide das gleiche Ziel, den Parameter der Aktion zu einer Dropdownliste zu machen, aus der der Benutzer auswählen kann. Beachten Sie die Eigenschaft x-ms-dynamic-values als Version 1 und die Erweiterung x-ms-dynamic-list als Version 2. Wenn Sie ältere vorhandene Flows unterstützen, empfehlen wir, beide in Ihrer Definition zu implementieren. Wenn Sie nur neu erstellte Flows unterstützen, verwenden Sie nur x-ms-dynamic-list. Die Erweiterung x-ms-dynamic-list verbessert das Schema für die Aktionsparameter und ermöglicht das Auflösen einiger mehrdeutiger Verweise. Wenn eine Anforderung beispielsweise eine Pfadparameter-ID und eine Parameter-ID als Teil des Anforderungshauptteils hat, ermöglicht Ihnen die Spezifikation x-ms-dynamic-list, die beiden Parameter zu unterscheiden, während x-ms-dynamic-values diese API nicht unterstützen könnte.
Um die Erweiterung x-ms-dynamic-list zu konfigurieren, müssen Sie die OpenAPI-Definition direkt ändern, weil der Designer des benutzerdefinierten Konnektors nur x-ms-dynamic-values konfiguriert. Das folgende Bild zeigt die Konfiguration x-ms-dynamic-values, die auch eine Konfiguration x-ms-dynamic-list hinzugefügt hat.
Durch das Konfigurieren dynamischer Werte für Parameter für einen benutzerdefinierten Konnektor kann der benutzerdefinierte Konnektor für Entwickler benutzerfreundlicher werden.