OpenAPI-Erweiterungen für benutzerdefinierte Connectors in Microsoft Flow

Einführung

Wenn Sie benutzerdefinierte Connectors für Microsoft Flow, Azure Logic Apps oder Microsoft PowerApps erstellen möchten, müssen Sie eine OpenAPI-Definitionsdatei angeben. Hierbei handelt es sich um ein sprachunabhängiges maschinenlesbares Dokument, in dem die Vorgänge und Parameter der API beschrieben werden. Zusammen mit der Out-of-Box-Funktionalität von OpenAPI können Sie diese OpenAPI-Erweiterungen auch beim Erstellen von benutzerdefinierten Connectors für Logic Apps und Flow einschließen:

  • summary
  • x-ms-summary
  • description
  • x-ms-visibility
  • x-ms-dynamic-values
  • x-ms-dynamic-schema

Für diese Erweiterungen gelten die folgenden Details:

summary

Gibt den Titel für die Aktion (den Vorgang) an.
Gilt für: Vorgänge
Empfohlen: Verwenden Sie einen Großbuchstaben am Anfang des Satzes für summary.
Beispiel: „Wenn dem Kalender ein Ereignis hinzugefügt wird“ oder „E-Mail senden“

„summary“ für jeden Vorgang

"actions" {
  "Send_an_email": {
    /// Other action properties here...
    "summary": "Send an email",
    /// Other action properties here...
  }
},

x-ms-summary

Gibt den Titel für eine Entität an.
Gilt für: Parameter, Antwortschema
Empfohlen: Verwenden Sie große Anfangsbuchstaben für x-ms-summary.
Beispiel: „Kalender-ID“, „Betreff“, „Ereignisbeschreibung“ usw.

„x-ms-summary“ für jede Entität

"actions" {
  "Send_an_email": {
    /// Other action properties here...
    "parameters": [ 
      {
        /// Other parameters here...
        "x-ms-summary": "Subject",
        /// Other parameters here...
      }
    ]
  }
},

description

Gibt eine ausführliche Erläuterung der Funktionalität eines Vorgangs oder das Format und die Funktion einer Entität an.
Gilt für: Vorgänge, Parameter, Antwortschema
Empfohlen: Verwenden Sie einen Großbuchstaben am Anfang des Satzes für description.
Beispiel: „Dieser Vorgang wird ausgelöst, wenn dem Kalender ein neues Ereignis hinzugefügt wird“, „Geben Sie den Betreff der E-Mail an“ usw.

"description" für jeden Vorgang oder jede Entität

"actions" {
  "Send_an_email": {
     "description": "Specify the subject of the mail",
     /// Other action properties here...
  }
},

x-ms-visibility

Gibt die Sichtbarkeit einer Entität für den Benutzer an.
Mögliche Werte: important, advanced undinternal
Gilt für: Vorgänge, Parameter, Schemas

  • important-Vorgänge und -Parameter werden dem Benutzer immer zuerst angezeigt.
  • advanced-Vorgänge und -Parameter werden in einem zusätzlichen Menü ausgeblendet.
  • internal-Vorgänge und -Parameter werden vor dem Benutzer verborgen.

Hinweis

Für Parameter, die internal und required sind, müssen Sie Standardwerte angeben.

Beispiel: Die Menüs Weitere anzeigen und Erweiterte Optionen anzeigen verbergen advanced-Vorgänge und -Parameter.

„x-ms-visibility“ für das Ein- oder Ausblenden von Vorgängen und Parametern

"actions" {
  "Send_an_email": {
     /// Other action properties here...
     "parameters:": [
         {
           "name": "Subject",
           "type": "string",
           "description": "Specify the subject of the mail",
           "x-ms-summary": "Subject",
           "x-ms-visibility": "important",
           /// Other parameter properties here
         }
     ]
     /// Other action properties here...
  }
},

x-ms-dynamic-values

Zeigt eine mit Daten aufgefüllte Liste für den Benutzer an, damit er Eingabeparameter für einen Vorgang auswählen kann.
Gilt für: Parameter
Verwendung: Fügen Sie der Definition des Parameters das x-ms-dynamic-values-Objekt hinzu. Dieses OpenAPI-Beispiel zeigt die Syntax.

„x-ms-dynamic-values“ zum Anzeigen von Listen

Eigenschaften für „x-ms-dynamic-values“

Name Erforderlich oder optional Beschreibung
operationID Erforderlich Der Vorgang, der zum Auffüllen der Liste mit Daten aufgerufen wird.
value-path Erforderlich Eine Pfadzeichenfolge im Objekt in value-collection, die auf den Parameterwert 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 die 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.

Das folgende Beispiel zeigt die Eigenschaften in x-ms-dynamic-values:

"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}"
     }
  }
}

Beispiel: Alle OpenAPI-Erweiterungen bis zu diesem Punkt

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

x-ms-dynamic-schema

Gibt an, dass das Schema für den aktuellen Parameter oder die aktuelle Antwort dynamisch ist. Dieses Objekt kann einen Vorgang aufrufen, der durch den Wert dieses Felds definiert ist, das Schema dynamisch ermitteln und die entsprechende Benutzeroberfläche für das Erfassen von Benutzereingaben anzeigen oder verfügbare Felder anzeigen.

Gilt für: Parameter, Antwort

Verwendung: Fügen Sie das x-ms-dynamic-schema-Objekt einem Anforderungsparameter oder einer Antworttextdefinition hinzu. Dieses OpenAPI-Beispiel zeigt die Syntax.

Dieses Beispiel zeigt, wie sich das Eingabeformular basierend auf dem Element ändert, das der Benutzer aus der Dropdownliste auswählt:

„x-ms-dynamic-schema“ für dynamische Parameter

Und dieses Beispiel zeigt, wie sich die Ausgaben basierend auf dem Element ändern, das der Benutzer aus der Dropdownliste auswählt. In dieser Version wählt der Benutzer „Cars“ aus:

„x-ms-dynamic-schema-response“ für das ausgewählte Element „Cars“

In dieser Version wählt der Benutzer „Food“ aus:

„x-ms-dynamic-schema-response“ für das ausgewählte Element „Food“

Eigenschaften für „x-ms-dynamic-schema“

Name Erforderlich oder optional Beschreibung
operationID Erforderlich Der Vorgang, der zum Abrufen des Schemas aufgerufen wird.
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 aufweist.
Wenn keine Angabe erfolgt, wird davon ausgegangen, dass die Antwort das Schema in den Eigenschaften des Stammobjekts enthält.

Das folgende Beispiel zeigt einen dynamischen Parameter:

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

Das folgende Beispiel zeigt eine 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