Eine OpenAPI-Definition für einen benutzerdefinierten Connector erweitern

  • Artikel

Eine Möglichkeit, benutzerdefinierte Connectors für Azure Logic Apps, Microsoft Power Automate oder Microsoft Power Apps zu erstellen, ist die Bereitstellung einer OpenAPI-Definitionsdatei. Diese Datei ist ein sprachunabhängiges, maschinenlesbares Dokument, das die Vorgänge und Parameter Ihrer API beschreibt. Zusammen mit der sofort einsatzbereiten Funktionalität von OpenAPI können Sie die folgenden OpenAPI-Erweiterungen auch beim Erstellen von benutzerdefinierten Connectors für Logic Apps und Power Automate einschließen:

Diese Erweiterungen werden in den folgenden Abschnitten beschrieben.

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“

„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 Mail an“

„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 und internal
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-api-annotation

Wird für die Versions- und Lebenszyklusverwaltung eines Vorgangs verwendet.

Gilt für: Vorgänge

  • family: Eine Zeichenfolge, die den Ordner der Vorgangsfamilie angibt.
  • revision: Ein Integer-Wert, der die Revisionsnummer angibt.
  • replacement: Ein Objekt, das die Informationen und Vorgänge der Ersatz-API enthält.
"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-operation-context

Dient zum Simulieren einer Triggerauslösung, um das Testen eines triggerabhängigen Flows zu ermöglichen.

Gilt für: Vorgänge

"x-ms-operation-context": {
        "simulate": {
          "operationId": "GetItems_V2",
          "parameters": {
            "$top": 1
          }
        }

x-ms-capabilities

Bei Verwendung auf der Connector-Ebene handelt es sich hierbei um eine Übersicht über die Funktionen des Connectors (einschließlich spezifischer Vorgänge).

Gilt für: Connectors

"x-ms-capabilities": {
  "testConnection": {
    "operationId": "GetCurrentUser"
  },
}

Bei Verwendung auf der Vorgangsebene wird mit dieser Option ermittelt, ob der Vorgang segmentiertes Hochladen und/oder eine statische Blockgröße unterstützt und vom Benutzer angegeben werden kann.

Gilt für: Vorgänge

  • chunkTransfer: Ein boolescher Wert, der angibt, ob die segmentierte Übertragung unterstützt wird.
"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

Gibt an, ob es sich beim aktuellen Vorgang um einen Trigger handelt, der ein einzelnes Ereignis erzeugt. Wenn dieses Feld nicht vorhanden ist, handelt es sich um einen Vorgang vom Typ action.

Gilt für: Vorgänge

  • single: Objektantwort
  • batch: Arrayantwort
"x-ms-trigger": "batch"

x-ms-trigger-hint

Eine Beschreibung, die angibt, wie ein Ereignis für einen Triggervorgang ausgelöst wird.

Gilt für: Vorgänge

"x-ms-trigger-hint": "To see it work, add a task in Outlook."

x-ms-notification-content

Enthält eine Schemadefinition einer Webhookbenachrichtigungsanforderung. Hierbei handelt es sich um das Schema für eine Webhooknutzlast, die von externen Diensten an die Benachrichtigungs-URL gesendet wird.

Gilt für: Ressourcen

"x-ms-notification-content": {
      "schema": {
        "$ref": "#/definitions/WebhookPayload"
      }
    },

x-ms-notification-url

Gibt über einen booleschen Wert an, ob in diesem Parameter/Feld eine Webhookbenachrichtigungs-URL für einen Webhookregistrierungsvorgang platziert werden soll.

Gilt für: Parameter/Eingabefelder

"x-ms-notification-url": true

x-ms-url-encoding

Gibt an, ob für den aktuellen Pfadparameter eine doppelte URL-Codierung (double) oder eine einfache URL-Codierung (single) verwendet werden soll. Wenn dieses Feld nicht vorhanden ist, wird die einfache Codierung (single) verwendet.

Gilt für: Pfadparameter

"x-ms-url-encoding": "double"

Dynamische Werte verwenden

Dynamische Werte sind eine Liste von Optionen für den Benutzer zur Auswahl von Eingabeparametern für eine Operation. 

Gilt für: Parameter 

Dynamische Werte für das Anzeigen von Listen.

Wie man dynamische Werte verwendet

Hinweis

Eine Pfadzeichenfolge ist ein JSON-Zeiger, der keinen führenden Schrägstrich enthält. Dies ist also ein JSON-Pointer: /property/childProperty, und dies ist eine Pfadangabe: property/childProperty.

Es gibt zwei Möglichkeiten, um dynamische Werte zu definieren:

  1. x-ms-dynamic-values verwenden

    Name Erforderlich Beschreibung
    operationId Ja Die Operation, die die Werte zurückgibt.
    parameters Ja Ein Objekt, das die Eingabeparameter bereitstellt, die zum Aufrufen einer Operation mit dynamischen Werten erforderlich sind.
    value-collection Nein Eine Pfadzeichenfolge, die zu einem Array von Objekten in der Antwortnutzlast ausgewertet wird. Wenn die Wertauflistung nicht angegeben ist, wird die Antwort als Array ausgewertet.
    value-title Nein Eine Pfadzeichenfolge im Objekt innerhalb der Wertauflistung, die sich auf die Beschreibung des Wertes bezieht.
    value-path Nein Eine Pfadzeichenfolge im Objekt innerhalb der Wertauflistung, die sich auf den Parameterwert bezieht. 
    "x-ms-dynamic-values": {
    "operationId": "PopulateDropdown",
    "value-path": "name",
    "value-title": "properties/displayName",
    "value-collection": "value",
    "parameters": {
        "staticParameter": "<value>",
        "dynamicParameter": {
            "parameter": "<name of the parameter to be referenced>"
        }
    }
}

    Hinweis

    Es ist möglich, mehrdeutige Parameterreferenzen zu haben, wenn dynamische Werte verwendet werden. In der folgenden Definition eines Vorgangs beziehen sich die dynamischen Werte beispielsweise auf das Feld id, was aus der Definition mehrdeutig ist, da nicht klar ist, ob es sich auf den Parameter id oder die Eigenschaft requestBody/id bezieht.

    {
    "summary": "Tests dynamic values with ambiguous references",
    "description": "Tests dynamic values with ambiguous references.",
    "operationId": "TestDynamicValuesWithAmbiguousReferences",
    "parameters": [{
        "name": "id",
        "in": "path",
        "description": "The request id.",
        "required": true
    }, {
        "name": "requestBody",
        "in": "body",
        "description": "query text.",
        "required": true,
        "schema": {
            "description": "Input body to execute the request",
            "type": "object",
            "properties": {
                "id": {
                    "description": "The request Id",
                    "type": "string"
                },
                "model": {
                    "description": "The model",
                    "type": "string",
                    "x-ms-dynamic-values": {
                        "operationId": "GetSupportedModels",
                        "value-path": "name",
                        "value-title": "properties/displayName",
                        "value-collection": "value",
                        "parameters": {
                            "requestId": {
                                "parameter": "id"
                            }
                        }
                    }
                }
            }
        }
    }],
    "responses": {
        "200": {
            "description": "OK",
            "schema": {
                "type": "object"
            }
        },
        "default": {
            "description": "Operation Failed."
        }
    }
}

  2. x-ms-dynamic-list

    Es gibt keine Möglichkeit, Parameter eindeutig zu referenzieren. Diese Funktion kann in Zukunft bereitgestellt werden. Wenn Ihr Vorgang neue Updates nutzen soll, fügen Sie die neue Erweiterung x-ms-dynamic-list zusammen mit x-ms-dynamic-values hinzu. Wenn Ihre dynamische Erweiterung auf Eigenschaften in Parametern verweist, müssen Sie außerdem die neue Erweiterung x-ms-dynamic-list zusammen mit x-ms-dynamic-values hinzufügen. Die Parameterreferenzen, die auf Eigenschaften verweisen, müssen als Pfadzeichenfolgen ausgedrückt werden.

    • parameters: Bei dieser Eigenschaft handelt es sich um ein Objekt, bei dem jede Eingabeeigenschaft des aufgerufenen dynamischen Vorgangs entweder mit einem statischen Wertfeld oder einem dynamischen Verweis auf die Eigenschaft des Quellvorgangs definiert ist. Diese beiden Optionen werden im Folgenden definiert.

    • value: Dies ist der Literalwert, der für den Eingabeparameter zu verwenden ist. Im folgenden Beispiel ist der Eingabeparameter des Vorgangs GetDynamicList namens Version mithilfe eines statischen Werts von 2.0 definiert.

      {
    "operationId": "GetDynamicList",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}

    • parameterReference: Dies ist der vollständige Parameter-Referenzpfad, beginnend mit dem Parameternamen, gefolgt von der Pfadzeichenfolge der zu referenzierenden Eigenschaft. Zum Beispiel wird die Eingabeeigenschaft des Vorgangs GetDynamicList namens property1, die sich unter dem Parameter destinationInputParam1 befindet, als dynamischer Verweis auf eine Eigenschaft namens property1 unter dem Parameter sourceInputParam1 des Quellvorgangs definiert.

      {
    "operationId": "GetDynamicList",
      "parameters": {
          "destinationInputParam1/property1": {
            "parameterReference": "sourceInputParam1/property1"
    }
  }
}

      Hinweis

      Wenn Sie auf eine Eigenschaft verweisen möchten, die als intern markiert ist und einen Standardwert hat, müssen Sie in diesem Fall anstelle von parameterReference den Standardwert als statischen Wert in der Definition verwenden. Der Standardwert aus der Liste wird nicht verwendet, wenn er mit parameterReference definiert ist.

      Name Erforderlich Beschreibung
      operationId Ja Der Vorgang, der die Liste zurückgibt.
      parameters Ja Ein Objekt, das die zum Aufrufen eines dynamischen Listenvorgangs erforderlichen Eingabeparameter bereitstellt.
      itemsPath Nein Eine Pfadzeichenfolge, die zu einem Array von Objekten in der Antwortnutzlast ausgewertet wird. Wenn  itemsPath  nicht angegeben ist, wird die Antwort als Array ausgewertet.
      itemTitlePath Nein Eine Pfadzeichenfolge im Objekt in  itemsPath , die auf die Beschreibung des Werts verweist.
      itemValuePath Nein Eine Pfadzeichenfolge im Objekt in  itemsPath , die auf den Wert des Elements verweist.

      Verwenden Sie mit x-ms-dynamic-list Parameterverweise mit der Pfadzeichenfolge der Eigenschaft, auf die Sie verweisen. Verwenden Sie diese Parameterreferenzen sowohl für den Schlüssel als auch für den Wert der dynamischen Betriebsparameterreferenz.

      {
  "summary": "Tests dynamic values with ambiguous references",
  "description": "Tests dynamic values with ambiguous references.",
  "operationId": "TestDynamicListWithAmbiguousReferences",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The request id.",
      "required": true
    },
    {
      "name": "requestBody",
      "in": "body",
      "description": "query text.",
      "required": true,
      "schema": {
        "description": "Input body to execute the request",
        "type": "object",
        "properties": {
          "id": {
            "description": "The request id",
            "type": "string"
          },
          "model": {
            "description": "The model",
            "type": "string",
            "x-ms-dynamic-values": {
              "operationId": "GetSupportedModels",
              "value-path": "name",
              "value-title": "properties/displayName",
              "value-collection": "cardTypes",
              "parameters": {
                "requestId": {
                  "parameter": "id"
                }
              }
            },
            "x-ms-dynamic-list": {
              "operationId": "GetSupportedModels",
              "itemsPath": "cardTypes",
              "itemValuePath": "name",
              "itemTitlePath": "properties/displayName",
              "parameters": {
                "requestId": {
                  "parameterReference": "requestBody/id"
                }
              }
            }
          }
        }
      }
    }
  ],
  "responses": {
    "200": {
      "description": "OK",
      "schema": {
        "type": "object"
      }
    },
    "default": {
      "description": "Operation Failed."
    }
  }
}

Dynamisches Schema verwenden

Das dynamische Schema zeigt an, dass das Schema für den aktuellen Parameter oder die aktuelle Antwort dynamisch ist. Dieses Objekt ruft eine Operation auf, die durch den Wert in diesem Feld definiert ist, entdeckt dynamisch das Schema und zeigt die entsprechende Benutzeroberfläche zum Sammeln von Benutzereingaben oder die verfügbaren Felder an.

Gilt für: Parameter, Antworten

Dieses Bild zeigt, wie sich das Eingabeformular auf der Grundlage des vom Benutzer aus der Liste ausgewählten Elements ändert:

Das Formular ändert sich auf der Grundlage der vom Benutzer getroffenen Auswahl.

Dieses Bild zeigt, wie sich die Ausgaben je nach dem Element ändern, das der Benutzer aus der Dropdownliste auswählt. In dieser Version wählt der Benutzer Autos aus:

Der Benutzer wählt Autos aus.

In dieser Version wählt der Benutzer Lebensmittel:

Der Benutzer wählt Lebensmittel aus.

Wie wird ein dynamisches Schema verwendet?

Hinweis

Eine Pfadzeichenfolge ist ein JSON-Zeiger, der keinen führenden Schrägstrich enthält. Dies ist also ein JSON-Pointer: /property/childProperty, und dies ist eine Pfadangabe: property/childProperty.

Es gibt zwei Möglichkeiten, ein dynamisches Schema zu definieren:

  1. x-ms-dynamic-schema:

    Name Erforderlich Beschreibung
    operationId Ja Die Operation, die das Schema zurückgibt.
    parameters Ja Ein Objekt, das die Eingabeparameter bereitstellt, die erforderlich sind, um eine dynamische Schemaoperation aufzurufen.
    value-path Nein Eine Pfadzeichenfolge, die auf die Eigenschaft verweist, die das Schema aufweist. Wenn nichts angegeben wird, wird davon ausgegangen, dass die Antwort das Schema in den Eigenschaften des Stammobjekts enthält. Wenn angegeben, muss die erfolgreiche Antwort die Eigenschaft enthalten. Für ein leeres oder undefiniertes Schema sollte dieser Wert null sein. 
      {
  "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"
      }
    }
  }

    Hinweis

    Es kann unter Umständen mehrdeutige Referenzen in den Parametern geben. In der folgenden Definition eines Vorgangs referenziert zum Beispiel das dynamische Schema ein Feld mit dem Namen query, das nicht deterministisch aus der Definition abgeleitet werden kann, unabhängig davon, ob es das Parameterobjekt query oder die Zeichenfolgeneigenschaft query/query referenziert.

    {

    "summary": "Tests dynamic schema with ambiguous references",
    "description": "Tests dynamic schema with ambiguous references.",
    "operationId": "TestDynamicSchemaWithAmbiguousReferences",
    "parameters": [{
        "name": "query",
        "in": "body",
        "description": "query text.",
        "required": true,
        "schema": {
            "description": "Input body to execute the request",
            "type": "object",
            "properties": {
                "query": {
                    "description": "Query Text",
                    "type": "string"
                }
            }
        },
        "x-ms-summary": "query text"
    }],
    "responses": {
        "200": {
            "description": "OK",
            "schema": {
                "x-ms-dynamic-schema": {
                    "operationId": "GetDynamicSchema",
                    "parameters": {
                        "query": {
                            "parameter": "query"
                        }
                    },
                    "value-path": "schema/valuePath"
                }
            }
        },
        "default": {
            "description": "Operation Failed."
        }
    }
}
    Beispiele von Open-Source-Connectors
    Connector Szenario Verknüpfung
    Ticketausstellung Schema für Details eines ausgewählten Ereignisses abrufen Ticketausstellung

  2. x-ms-dynamic-properties:

    Es gibt keine Möglichkeit, Parameter eindeutig zu referenzieren. Diese Funktion kann in Zukunft bereitgestellt werden. Wenn Ihr Vorgang neue Updates nutzen soll, fügen Sie die neue Erweiterung x-ms-dynamic-properties zusammen mit x-ms-dynamic-schema hinzu. Wenn Ihre dynamische Erweiterung auf Eigenschaften in Parametern verweist, müssen Sie außerdem die neue Erweiterung x-ms-dynamic-properties zusammen mit x-ms-dynamic-schema hinzufügen. Die Parameterreferenzen, die auf Eigenschaften verweisen, müssen als Pfadzeichenfolgen ausgedrückt werden.

    • parameters: Bei dieser Eigenschaft handelt es sich um ein Objekt, bei dem jede Eingabeeigenschaft des aufgerufenen dynamischen Vorgangs entweder mit einem statischen Wertfeld oder einem dynamischen Verweis auf die Eigenschaft des Quellvorgangs definiert ist. Diese beiden Optionen werden im Folgenden definiert.

    • value: Dies ist der Literalwert, der für den Eingabeparameter zu verwenden ist. Im folgenden Beispiel wird der Eingabeparameter des Vorgangs GetDynamicSchema namens Version mit einem statischen Wert von 2.0 definiert.

      {
    "operationId": "GetDynamicSchema",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}

    • parameterReference: Dies ist der vollständige Parameter-Referenzpfad, beginnend mit dem Parameternamen, gefolgt von der Pfadzeichenfolge der zu referenzierenden Eigenschaft. Beispielsweise wird die Eingabeeigenschaft der Operation GetDynamicSchema namens property1, die sich unter dem Parameter destinationInputParam1 befindet, als ein dynamischer Verweis auf eine Eigenschaft namens property1 unter dem Parameter sourceInputParam1 des Quellvorgangs definiert.

      {
    "operationId": "GetDynamicSchema",
      "parameters": {
          "destinationInputParam1/property1": {
            "parameterReference": "sourceInputParam1/property1"
    }
  }
}

      Hinweis

      Wenn Sie auf eine Eigenschaft verweisen möchten, die als intern markiert ist und einen Standardwert hat, müssen Sie in diesem Fall anstelle von parameterReference den Standardwert als statischen Wert in der Definition verwenden. Der Standardwert aus dem Schema wird nicht verwendet, wenn er mit parameterReference definiert ist.

      Name Erforderlich Beschreibung
      operationId Ja Der Vorgang, der das Schema zurückgibt.
      parameters Ja Ein Objekt, das die Eingabeparameter bereitstellt, die erforderlich sind, um eine dynamische Schemaoperation aufzurufen.
      itemValuePath Nein Eine Pfadzeichenfolge, die auf die Eigenschaft verweist, die das Schema aufweist. Wenn nicht angegeben, wird angenommen, dass die Antwort das Schema im Stammobjekt enthält. Wenn angegeben, muss die erfolgreiche Antwort die Eigenschaft enthalten. Für ein leeres oder undefiniertes Schema sollte dieser Wert null sein.

      Bei x-ms-dynamic-properties können Parameterverweise mit der Pfadzeichenfolge der Eigenschaft, auf die verwiesen werden soll, sowohl für den Schlüssel als auch den Wert des Parameterverweises des dynamischen Vorgangs verwendet werden.

          {
    "summary": "Tests dynamic schema with ambiguous references",
    "description": "Tests dynamic schema with ambiguous references.",
    "operationId": "TestDynamicSchemaWithAmbiguousReferences",
    "parameters": [{
        "name": "query",
        "in": "body",
        "description": "query text.",
        "required": true,
        "schema": {
            "description": "Input body to execute the request",
            "type": "object",
            "properties": {
                "query": {
                    "description": "Query Text",
                    "type": "string"
                }
            }
        },
        "x-ms-summary": "query text"
    }],
    "responses": {
        "200": {
            "description": "OK",
            "schema": {
                "x-ms-dynamic-schema": {
                    "operationId": "GetDynamicSchema",
                    "parameters": {
                        "version": "2.0",
                        "query": {
                            "parameter": "query"
                        }
                    },
                    "value-path": "schema/valuePath"
                },
                "x-ms-dynamic-properties": {
                    "operationId": "GetDynamicSchema",
                    "parameters": {
                        "version": {
                            "value": "2.0"
                        },
                        "query/query": {
                            "parameterReference": "query/query"
                        }
                    },
                    "itemValuePath": "schema/valuePath"
                }
            }
        },
        "default": {
            "description": "Operation Failed."
        }
      }
    }

Nächster Schritt

Einen benutzerdefinierten Connector auf der Grundlage einer OpenAPI-Definition erstellen

Siehe auch

Übersicht über benutzerdefinierte Connectors

Feedback senden

Wir freuen uns sehr über Feedback zu Problemen mit unserer Connector-Plattform oder neuen Feature-Ideen. Wenn Sie Feedback geben möchten, gehen Sie zu Probleme melden oder Hilfe zu Connectors und wählen Sie einen Feedbacktyp aus.