Einführung

Wenn Sie benutzerdefinierte Connectors in Microsoft Flow verwenden möchten, müssen Sie eine OpenAPI-Definition angeben. Hierbei handelt es sich um ein sprachunabhängiges maschinenlesbares Dokument, in dem die Vorgänge und Parameter der API beschrieben werden. Zusätzlich zur vorgegebenen OpenAPI-Spezifikation sind einige Erweiterungen verfügbar, wenn ein benutzerdefinierter Connector für Microsoft Flow erstellt wird: summary, x-ms-summary, description, x-ms-visibility, x-ms-dynamic-values und x-ms-dynamic-schema.

summary

Der Titel des Vorgangs. Beispiel: „Wenn eine Aufgabe erstellt wird“ oder „Neuen Lead erstellen“.

Gilt für:

  • Vorgänge

summary-annotation

Es wird empfohlen, bei der Zusammenfassung der Vorgänge den Anfangsbuchstaben des Satzes großzuschreiben.

x-ms-summary

Der Titel der Entität. Beispiel: „Aufgabenname“, „Fälligkeitsdatum“ usw.

Gilt für:

  • Parameter
  • Antwortschema

x-ms-summary-annotation

Es wird empfohlen, in „x-ms-summary“ die Groß-/Kleinschreibung wie in Überschriften zu verwenden.

description

Eine ausführliche Erläuterung der Funktionalität eines Vorgangs oder des Formats und der Funktion einer Entität. Beispiel: „Dieser Vorgang wird ausgelöst, wenn eine Aufgabe zum Projekt hinzugefügt wird“.

Gilt für:

  • Vorgänge
  • Parameter
  • Antwortschema

description-annotation

Es wird empfohlen, bei der Beschreibung den Anfangsbuchstaben des Satzes großzuschreiben.

x-ms-visibility

Bestimmt die Sichtbarkeit der Entität für den Benutzer. Die möglichen Werte sind important, advanced und internal.

Mit important markierte Vorgänge und Parameter werden für den Benutzer stets zuerst angezeigt. Mit advanced markierte Vorgänge und Parameter sind hinter dem Menü „advanced“ verborgen. Mit internal markierte Vorgänge und Parameter sind für den Benutzer komplett verborgen.

Hinweis:

Wenn ein Parameter mit internal und required markiert ist, MUSS für den Parameter ein Standardwert angegeben werden.

Gilt für:

  • Vorgänge
  • Parameter
  • Schemas

visibility-annotation

x-ms-dynamic-values

Ermöglicht das Auffüllen einer Dropdownliste zum Erfassen von Eingabeparametern für einen Vorgang.

Gilt für:

  • Parameter

dynamic-values

Verwendung:

Hiermit können Sie einen Parameter definieren, indem Sie das „x-ms-dynamic-values“-Objekt in der Parameterdefinition verwenden.

Hinweis:

Im Swagger-Beispiel erhalten Sie weitere Informationen. Die Benutzeroberfläche für benutzerdefinierte Connectors unterstützt auch das Konfigurieren von Dropdownlisten.

Eigenschaften:

  • operationID [Erforderlich]: Gibt den Vorgang an, der zum Auffüllen der Dropdownliste aufgerufen werden muss.
  • value-path [Erforderlich]: Eine Pfadzeichenfolge im Objekt in „value-collection“, die auf den Wert für den Parameter verweist. Wenn „value-collection“ nicht angegeben wird, wird die Antwort als Array ausgewertet.
  • value-title [Optional]: Eine Pfadzeichenfolge im Objekt in „value-collection“, die auf eine Beschreibung des Werts verweist. Wenn „value-collection“ nicht angegeben wird, wird die Antwort als Array ausgewertet.
  • value-collection [Optional]: Eine Pfadzeichenfolge, die als Array von Objekten in der Nutzlast der Antwort ausgewertet wird.
  • parameters [Optional]: Ein Objekt, dessen Eigenschaften die Eingabeparameter angeben, die zum Aufrufen eines „dynamic-values“-Vorgangs erforderlich sind,

Beispiel:

  "x-ms-dynamic-values": {
    "operationId": "PopulateDropdown",
    "value-path": "name",
    "value-title": "properties/displayName",
    "value-collection": "value",
    "parameters": {
      "staticParameter": "<value>",
      "dynamicParameter": {
        "parameter": "<value_to_pass_to_dynamicParameter>"
      }
    }
  }

Swagger-Beispielcode von OpenAPI:

"/api/lists/{listID-dynamic}": {
      "get": {
        "description": "Get items from a single list - uses dynamic Values and outputs dynamic-schema",
        "summary": "Get's items from the selected list ",
        "operationId": "GetListItems",
        "parameters": [
          {
            "name": "listID-dynamic",
            "type": "string",
            "in": "path",
            "description": "Select List you want outputs from",
            "required": true,
            "x-ms-summary": "Select List",
            "x-ms-dynamic-values": {
              "operationId": "GetLists",
              "value-path": "id",
              "value-title": "name"
            }
          }
        ]

x-ms-dynamic-schema

Dies ist ein Hinweis für den Flow-Designer, dass das Schema für diesen Parameter (oder diese Antwort) dynamisch ist. Sie können einen Vorgang so aufrufen, wie durch den Wert dieses Feld definiert, sodass das Schema dynamisch erkannt wird. Dann kann die entsprechende Benutzeroberfläche angezeigt werden, um Eingaben des Benutzers anzunehmen oder verfügbare Felder anzuzeigen.

Gilt für:

  • Parameter
  • Antwort

Beachten Sie, wie sich das Eingabeformular in der Dropdownliste ändert, je nach der Auswahl für

dynamic-schema-request

Beachten Sie, wie sich die Ausgabe in der Dropdownliste ändert, je nach der Auswahl für

dynamic-schema-response

Verwendung:

Hiermit wird ein Anforderungsparameter oder ein Antworttext mit dem x-ms-dynamic-schema-Objekt kommentiert.

Hinweis:

Im Swagger-Beispiel finden Sie weitere Informationen.

Eigenschaften:

  • operationID [Erforderlich]: Gibt den Vorgang an, der zum Abrufen des Schemas aufgerufen werden muss.
  • parameters [Erforderlich]: Ein Objekt, dessen Eigenschaften die Eingabeparameter angeben, die zum Aufrufen eines „dynamic-schema“-Vorgangs erforderlich sind,
  • value-path [Optional]: Eine Pfadzeichenfolge, die auf die Eigenschaft verweist, die das Schema enthält. Wenn dieser Parameter nicht angegeben wird, wird angenommen, dass die Antwort das Schema in den Eigenschaften des Stammobjekts enthält.

Beispielcode für dynamische Parameter:

  {
    "name": "dynamicListSchema",
    "in": "body",
    "description": "Dynamic Schema of items in selected list",
    "schema": {
      "type": "object",
      "x-ms-dynamic-schema": {
        "operationId": "GetListSchema",
        "parameters": {
          "listID": {
            "parameter": "listID-dynamic"
          }
        },
        "value-path": "items"
      }
    }
  }

Beispielcode für dynamische Antwort:

"DynamicResponseGetListSchema": {
      "type": "object",
      "x-ms-dynamic-schema": {
        "operationId": "GetListSchema",
        "parameters": {
          "listID": {
            "parameter": "listID-dynamic"
          }
        },
        "value-path": "items"
      }
    }

Weitere Schritte

Registrieren eines benutzerdefinierten Connectors

Verwenden einer ASP.NET-Web-API

Registrieren einer Azure Resource Manager-API