Een OpenAPI-definitie uitbreiden voor een aangepaste connector

  • Artikel

Eén manier om aangepaste connectors te maken voor Azure Logic Apps, Microsoft Power Automate of Microsoft Power Apps, is het leveren van een OpenAPI-definitiebestand. Dit is een taalagnostisch document dat op de computer kan worden gelezen en waarin de bewerkingen en parameters van de API worden beschreven. Samen met de kant-en-klare functionaliteit van OpenAPI, kunt u ook de volgende OpenAPI-uitbreidingen opnemen wanneer u aangepaste connectors maakt voor Logic Apps en Power Automate:

In de volgende secties worden deze uitbreidingen beschreven.

summary

Hiermee geeft u de titel op voor de actie (bewerking).

Van toepassing op: bewerkingen
Aanbevolen: gebruik een zin voor summary.
Voorbeeld: Wanneer een gebeurtenis wordt toegevoegd aan agenda of Een e-mailbericht verzenden

'summary' voor elke bewerking.

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

x-ms-summary

Hiermee geeft u de titel op voor een entiteit.

Van toepassing op: parameters, antwoordschema
Aanbevolen: gebruik een titel voor x-ms-summary.
Voorbeeld: Agenda-id, Onderwerp, Beschrijving van gebeurtenis

'x-ms-summary' voor elke entiteit.

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

description

Hiermee wordt een uitgebreide uitleg van de functionaliteit van de bewerking of de indeling en functie van een entiteit opgegeven.

Van toepassing op: bewerkingen, parameters, antwoordschema
Aanbevolen: gebruik een zin voor description.
Voorbeeld: Deze bewerking wordt geactiveerd wanneer een nieuwe gebeurtenis wordt toegevoegd aan de agenda, Geef het onderwerp van de e-mail op enzovoort

'description' voor elke bewerking of entiteit.

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

x-ms-visibility

Hiermee wordt de zichtbaarheid van de entiteit voor een gebruiker opgegeven.

Mogelijke waarden: important, advanced en internal
Van toepassing op: bewerkingen, parameters, schema's

  • important-bewerkingen en -parameters worden altijd eerst weergegeven voor de gebruiker.
  • advanced-bewerkingen en -parameters zijn verborgen onder een aanvullend menu.
  • internal-bewerkingen en -parameters zijn verborgen voor de gebruiker.

Notitie

Voor parameters die internal en required zijn, moet u standaardwaarden opgeven.

Voorbeeld: in het menu Meer informatie en het menu Geavanceerde opties weergeven worden advanced-bewerkingen en -parameters verborgen.

'x-ms-visibility' voor het weergeven of verbergen van bewerkingen en parameters.

"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

Wordt gebruikt voor het versie- en levenscyclusbeheer van een bewerking.

Van toepassing op: bewerkingen

  • family—Een tekenreeks die de familiemap van een bewerking aanduidt.
  • revision—Een geheel getal die het revisienummer aanduidt.
  • replacement—Een object dat de vervangende API-gegevens en -bewerkingen omvat.
"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-operation-context

Wordt gebruikt voor het simuleren van een triggeractivering om een triggerafhankelijke stroom te testen.

Van toepassing op: bewerkingen

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

x-ms-capabilities

Op het niveau van de connector is dit een overzicht van de mogelijkheden die de connector biedt, waaronder specifieke bewerkingen.

Van toepassing op: connectors

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

Op het niveau van de bewerking wordt dit gebruikt om te bepalen of de bewerking het uploaden van chunks en/of statische chunkgrootten ondersteunt en of dit door de gebruiker kan worden opgegeven.

Van toepassing op: bewerkingen

  • chunkTransfer—Een booleaanse waarde die aangeeft of chunkoverdracht wordt ondersteund.
"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

Hiermee wordt aangegeven of de huidige bewerking een trigger is die een enkele gebeurtenis oplevert. Als dit veld ontbreekt, betekent dit dat het gaat om een action-bewerking.

Van toepassing op: bewerkingen

  • single—Objectreactie
  • batch—Matrixreactie
"x-ms-trigger": "batch"

x-ms-trigger-hint

Een beschrijving van hoe u een gebeurtenis kunt starten voor een triggerbewerking.

Van toepassing op: bewerkingen

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

x-ms-notification-content

Bevat een schemadefinitie van een meldingsaanvraag voor een webhook. Dit is het schema voor een webhookpayload dat door externe services wordt geplaatst bij de meldings-URL.

Geldt voor: resources

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

x-ms-notification-url

Bepaalt in een booleaanse waarde of er in deze parameter/dit veld een webhookmeldings-URL moet worden geplaatst voor de registratiebewerking van een webhook.

Van toepassing op: parameters/invoervelden

"x-ms-notification-url": true

x-ms-url-encoding

Geeft aan of de huidige padparameter double (dubbel) of single (enkel) in de URL gecodeerd moet zijn. Als dit veld ontbreekt, is er sprake van single-codering.

Van toepassing op: padparameters

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

Dynamische waarden gebruiken

Dynamische waarden zijn een lijst met opties waarmee de gebruiker invoerparameters voor een bewerking kan selecteren. 

Van toepassing op: parameters 

Dynamic-values voor het weergeven van lijsten.

Procedure voor het gebruiken van dynamische waarden

Notitie

Een padtekenreeks is een JSON-aanwijzer die geen voorwaartse slash aan het begin bevat. Dit is dus een JSON-aanwijzer: /property/childProperty en dit een padtekenreeks: property/childProperty.

Dynamische waarden kunnen op twee manieren worden gedefinieerd:

  1. x-ms-dynamic-values gebruiken

    Naam Vereist Beschrijving
    operationId Ja De bewerking die de waarden retourneert.
    parameters Ja Een object dat de invoerparameters levert die zijn vereist voor het aanroepen van een bewerking met dynamic-values.
    value-collection Nee Een padtekenreeks waarmee een matrix van objecten in de nettolading van de respons wordt geëvalueerd. Als value-collection niet is opgegeven, wordt de respons geëvalueerd als een matrix.
    value-title Nee Een padtekenreeks in het object binnen value-collection die verwijst naar de beschrijving van de waarde.
    value-path Nee Een padtekenreeks in het object binnen value-collection die verwijst naar de parameterwaarde. 
    "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>"
        }
    }
}

    Notitie

    Het is mogelijk om dubbelzinnige parameterverwijzingen te hebben bij het gebruik van dynamische waarden. In de volgende definitie van een bewerking verwijzen de dynamische waarden bijvoorbeeld naar het veld id, wat dubbelzinnig is omdat niet duidelijk is of wordt verwezen naar de parameter id of naar de eigenschap requestBody/id.

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

    Er is geen manier om ondubbelzinnig naar parameters te verwijzen. Deze functie komt mogelijk in de toekomst beschikbaar. Als u wilt dat de bewerking gebruikmaakt van nieuwe updates, voegt u de nieuwe extensie x-ms-dynamic-list toe samen met x-ms-dynamic-values. Bovendien, als de dynamische extensie verwijst naar eigenschappen binnen parameters, moet u de nieuwe extensie x-ms-dynamic-list toevoegen met x-ms-dynamic-values. De parameterverwijzingen die naar eigenschappen verwijzen, moeten worden uitgedrukt als padtekenreeksen.

    • parameters—Deze eigenschap is een object waar elke invoereigenschap van de aangeroepen dynamische bewerking wordt gedefinieerd met een statisch waardeveld of een dynamische verwijzing naar de eigenschap van de bronbewerking. Beide opties zijn gedefinieerd in het volgende.

    • value—Dit is de letterlijke waarde die moet worden gebruikt voor de invoerparameter. De invoerparameter van de bewerking GetDynamicList met de naam version is in het volgende voorbeeld bijvoorbeeld gedefinieerd met de statische waarde 2.0.

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

    • parameterReference—Dit is het volledige parameterverwijzingspad, beginnend met de parameternaam, gevolgd door de padtekenreeks van de eigenschap waarnaar wordt verwezen. Zo wordt de invoereigenschap van de bewerking GetDynamicList genaamd property1, onder de parameter destinationInputParam1, bijvoorbeeld gedefinieerd als een dynamische verwijzing naar een eigenschap met de naam property1 onder de parameter sourceInputParam1 van de bronbewerking.

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

      Notitie

      Als u naar een als intern gemarkeerde eigenschap wilt verwijzen met een standaardwaarde, moet u in de definitie de standaardwaarde als statische waarde gebruiken in plaats van parameterReference. De standaardwaarde uit de lijst wordt niet gebruikt als deze wordt gedefinieerd met parameterReference.

      Naam Vereist Beschrijving
      operationId Ja De bewerking die de lijst retourneert.
      parameters Ja Een object dat de invoerparameters levert die zijn vereist voor het aanroepen van een bewerking met een dynamische lijst.
      itemsPath Nee Een padtekenreeks waarmee een matrix van objecten in de nettolading van de respons wordt geëvalueerd. Als itemsPath niet is opgegeven, wordt het antwoord geëvalueerd als een matrix.
      itemTitlePath Nee Een padtekenreeks in het object binnen itemsPath die naar de beschrijving van de waarde verwijst.
      itemValuePath Nee Een padtekenreeks in het object binnen itemsPath die verwijst naar de waarde van het item.

      Met x-ms-dynamic-list gebruikt u parameterreferenties met de padtekenreeks van de eigenschap waarnaar u verwijst. Gebruik deze parameterverwijzingen voor zowel de sleutel als de waarde van de parameterverwijzing voor de dynamische bewerking.

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

Dynamisch schema gebruiken

Het dynamische schema geeft aan dat het schema voor de huidige parameter of respons dynamisch is. Met dit object wordt een bewerking aangeroepen die wordt gedefinieerd door de waarde in dit veld, op dynamische wijze het schema gedetecteerd en wordt de juiste gebruikersinterface voor het verzamelen van gebruikersinvoer of de beschikbare velden weergegeven.

Van toepassing op: parameters, antwoorden

In deze afbeelding wordt weergegeven hoe het invoerformulier verandert op basis van het item dat de gebruiker selecteert in de lijst:

Het formulier verandert op basis van de selectie die de gebruiker maakt.

In deze afbeelding wordt weergegeven hoe de uitvoer verandert op basis van het item dat de gebruiker selecteert in de vervolgkeuzelijst. In deze versie selecteert de gebruiker Cars (auto's)

De gebruiker selecteert Cars (auto's)

In deze versie selecteert de gebruiker Food (eten):

De gebruiker selecteert Food (eten)

Procedure voor het gebruiken van het dynamisch schema

Notitie

Een padtekenreeks is een JSON-aanwijzer die geen voorwaartse slash aan het begin bevat. Dit is dus een JSON-aanwijzer: /property/childProperty en dit een padtekenreeks: property/childProperty.

Het dynamische schema kan op twee manieren worden gedefinieerd:

  1. x-ms-dynamic-schema:

    Naam Vereist Beschrijving
    operationId Ja De bewerking die het schema retourneert.
    parameters Ja Een object dat de invoerparameters levert die zijn vereist voor het aanroepen van een bewerking met dynamic-schema.
    value-path Nee Een padtekenreeks die verwijst naar de eigenschap met het schema. Als dit niet wordt opgegeven, wordt ervan uitgegaan dat de respons het schema bevat in de eigenschappen van het hoofdobject. Indien gespecificeerd, moet de geslaagde respons de eigenschap bevatten. Voor een leeg of ongedefinieerd schema moet deze waarde null zijn. 
      {
  "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"
      }
    }
  }

    Notitie

    De parameters bevatten mogelijk dubbelzinnige verwijzingen. In de volgende definitie van een bewerking verwijst het dynamische schema bijvoorbeeld naar een veld met de naam query, die niet deterministisch kan worden opgemaakt uit de definitie—, ongeacht of dit veld verwijst naar het parameterobject query of naar de tekenreekseigenschap query/query.

    {

    "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."
        }
    }
}
    Voorbeelden van open source-connectors
    Connector Scenario Koppeling
    Ticketsysteem Schema ophalen voor details van een geselecteerde gebeurtenis Ticketsysteem

  2. x-ms-dynamic-properties:

    Er is geen manier om ondubbelzinnig naar parameters te verwijzen. Deze functie komt mogelijk in de toekomst beschikbaar. Als u wilt dat de bewerking gebruikmaakt van nieuwe updates, voegt u de nieuwe extensie x-ms-dynamic-properties toe samen met x-ms-dynamic-schema. Bovendien, als de dynamische extensie verwijst naar eigenschappen binnen parameters, moet u de nieuwe extensie x-ms-dynamic-properties toevoegen met x-ms-dynamic-schema. De parameterverwijzingen die naar eigenschappen verwijzen, moeten worden uitgedrukt als padtekenreeksen.

    • parameters—Deze eigenschap is een object waar elke invoereigenschap van de aangeroepen dynamische bewerking wordt gedefinieerd met een statisch waardeveld of een dynamische verwijzing naar de eigenschap van de bronbewerking. Beide opties zijn gedefinieerd in het volgende.

    • value—Dit is de letterlijke waarde die moet worden gebruikt voor de invoerparameter. De invoerparameter van de bewerking GetDynamicSchema met de naam versie is in het volgende voorbeeld bijvoorbeeld gedefinieerd met de statische waarde 2.0.

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

    • parameterReference—Dit is het volledige parameterverwijzingspad, beginnend met de parameternaam, gevolgd door de padtekenreeks van de eigenschap waarnaar wordt verwezen. Zo wordt de invoereigenschap van de bewerking GetDynamicSchema genaamd property1, onder de parameter destinationInputParam1, bijvoorbeeld gedefinieerd als een dynamische verwijzing naar een eigenschap met de naam property1 onder de parameter sourceInputParam1 van de bronbewerking.

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

      Notitie

      Als u naar een als intern gemarkeerde eigenschap wilt verwijzen met een standaardwaarde, moet u in de definitie de standaardwaarde als statische waarde gebruiken in plaats van parameterReference. De standaardwaarde uit het schema wordt niet gebruikt als deze wordt gedefinieerd met parameterReference.

      Naam Vereist Beschrijving
      operationId Ja De bewerking die het schema retourneert.
      parameters Ja Een object dat de invoerparameters levert die zijn vereist voor het aanroepen van een bewerking met dynamic-schema.
      itemValuePath Nee Een padtekenreeks die verwijst naar de eigenschap met het schema. Als dit niet wordt opgegeven, wordt ervan uitgegaan dat de respons het schema bevat in het hoofdobject. Indien gespecificeerd, moet de geslaagde respons de eigenschap bevatten. Voor een leeg of ongedefinieerd schema moet deze waarde null zijn.

      Met x-ms-dynamic-properties kunnen parameterverwijzingen worden gebruikt met de padtekenreeks van de eigenschap waarnaar moet worden verwezen, zowel voor de sleutel als voor de waarde van de parameterverwijzing van de dynamische bewerking.

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

Volgende stap

Een aangepaste connector maken op basis van een OpenAPI-definitie

Zie ook

Overzicht van aangepaste connectors

Feedback geven

We stellen feedback over problemen met ons connectorplatform of ideeën voor nieuwe functies zeer op prijs. Om feedback te geven, gaat u naar Problemen melden of hulp krijgen met connectoren en selecteer uw feedbacktype.