Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Eén manier om aangepaste connectoren voor Microsoft Copilot Studio, Azure Logic Apps, Microsoft Power Automate of Microsoft Power Apps te maken, is door een OpenAPI definitiebestand te verstrekken. Dit is een taalneutraal, machineleesbaar document dat de bewerkingen en parameters van uw API beschrijft. 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:
summary
x-ms-summary
description
x-ms-visibility
x-ms-api-annotation
x-ms-operation-context
x-ms-capabilities
x-ms-trigger
x-ms-trigger-hint
x-ms-notification-content
x-ms-notification-url
x-ms-url-encoding
x-ms-dynamic-values and x-ms-dynamic-list
x-ms-dynamic-schema and x-ms-dynamic-properties
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 zinshoofdlettergebruik voor summary
.
Voorbeeld: "Wanneer een gebeurtenis aan de agenda wordt toegevoegd" of "Een e-mail verzenden"
"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, responsschema
Aanbevolen: Gebruik hoofdlettergebruik voor x-ms-summary
.
Voorbeeld: "Kalender-ID", "Onderwerp", "Gebeurtenisbeschrijving"
"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, responsschema
Aanbevolen: gebruik zinshoofdlettergebruik voor description
.
Voorbeeld: "Deze bewerking wordt geactiveerd wanneer een nieuwe gebeurtenis aan de agenda wordt toegevoegd", "Geef het onderwerp van de e-mail op"
"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 aan de gebruiker getoond. -
advanced
bewerkingen en parameters zijn verborgen onder een extra menu. -
internal
bewerkingen en parameters zijn verborgen voor de gebruiker.
Notitie
Voor parameters die internal
en required
zijn, moet u standaardwaarden opgeven.
Voorbeeld: De menu's Meer weergeven en Geavanceerde opties weergeven verbergen advanced
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 de bewerking aangeeft. -
revision
—Een geheel getal dat het revisienummer aangeeft. -
replacement
—Een object dat de vervangende API-informatie en -bewerkingen bevat.
"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. Het ontbreken van dit veld betekent dat het hier om een action
bewerking gaat.
Van toepassing op: bewerkingen
-
single
—Objectrespons -
batch
—Array-respons
"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 dubbel URL-gecodeerd double
of enkel URL-gecodeerd single
moet zijn. De afwezigheid van dit veld geeft single
codering aan.
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
Procedure voor het gebruiken van dynamische waarden
Notitie
Een padstring is een JSON-aanwijzer die geen voorafgaande slash bevat. Dit is dus een JSON-aanwijzer: /property/childProperty, en dit is een padreeks: property/childProperty.
Dynamische waarden kunnen op twee manieren worden gedefinieerd:
Gebruik
x-ms-dynamic-values
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. Dit is onduidelijk in de definitie, omdat niet duidelijk is of er 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." } } }
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 uw bewerking profiteert van nieuwe updates, voegt u de nieuwe extensie
x-ms-dynamic-list
toe samen metx-ms-dynamic-values
. Als uw dynamische extensie bovendien naar eigenschappen binnen parameters verwijst, moet u de nieuwe extensiex-ms-dynamic-list
toevoegen samen metx-ms-dynamic-values
. De parameterverwijzingen die naar eigenschappen verwijzen, moeten worden uitgedrukt als padtekenreeksen.parameters
—Deze eigenschap is een object waarbij 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. In het volgende voorbeeld wordt de invoerparameter van de bewerking GetDynamicList bewerking genaamd versie gedefinieerd met behulp van de statische waarde 2.0.{ "operationId": "GetDynamicList", "parameters": { "version": { "value": "2.0" } } }
parameterReference
—Dit is het volledige parameterreferentiepad, beginnend met de parameternaam gevolgd door de padtekenreeks van de eigenschap waarnaar moet worden verwezen. De invoereigenschap van de bewerking GetDynamicList met de naam property1, die zich onder de parameter destinationInputParam1 bevindt, wordt 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 eigenschap wilt verwijzen die als intern is gemarkeerd met een standaardwaarde, moet u hier in de definitie de standaardwaarde als statische waarde gebruiken
parameterReference
. De standaardwaarde uit de lijst wordt niet gebruikt als deze is gedefinieerd door usingparameterReference
.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 array.itemTitlePath Nee Een padtekenreeks in het object binnen itemsPath
die verwijst naar de beschrijving van de waarde.itemValuePath Nee Een padtekenreeks in het object binnen itemsPath
die verwijst naar de waarde van het item.Gebruik bij
x-ms-dynamic-list
parameterverwijzingen 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:
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 Auto's:
In deze versie selecteert de gebruiker Eten:
Procedure voor het gebruiken van het dynamisch schema
Notitie
Een padstring is een JSON-aanwijzer die geen voorafgaande slash bevat. Dit is dus een JSON-aanwijzer: /property/childProperty, en dit is een padreeks: property/childProperty.
Het dynamische schema kan op twee manieren worden gedefinieerd:
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 is opgegeven, wordt ervan uitgegaan dat het antwoord het schema in de eigenschappen van het hoofdobject bevat. 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, wat niet deterministisch uit de definitie kan worden afgeleid, of er nu wordt verwezen 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 Kaartverkoop 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 uw bewerking profiteert van nieuwe updates, voegt u de nieuwe extensie
x-ms-dynamic-properties
toe samen metx-ms-dynamic-schema
. Als uw dynamische extensie bovendien naar eigenschappen binnen parameters verwijst, moet u de nieuwe extensiex-ms-dynamic-properties
samen metx-ms-dynamic-schema
toevoegen. De parameterverwijzingen die naar eigenschappen verwijzen, moeten worden uitgedrukt als padtekenreeksen.parameters
—Deze eigenschap is een object waarbij 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. In het volgende voorbeeld is de invoerparameter van de bewerking GetDynamicSchema met de naam version gedefinieerd met de statische waarde 2.0.{ "operationId": "GetDynamicSchema", "parameters": { "version": { "value": "2.0" } } }
parameterReference
—Dit is het volledige parameterreferentiepad, beginnend met de parameternaam gevolgd door de padtekenreeks van de eigenschap waarnaar moet worden verwezen. De invoereigenschap van de bewerking GetDynamicSchema genaamd property1 , die zich onder de parameter destinationInputParam1 bevindt, wordt bijvoorbeeld gedefinieerd als een dynamische verwijzing naar een eigenschap met de naam property1 onder parameter sourceInputParam1 van de bronbewerking.{ "operationId": "GetDynamicSchema", "parameters": { "destinationInputParam1/property1": { "parameterReference": "sourceInputParam1/property1" } } }
Notitie
Als u naar een eigenschap wilt verwijzen die als intern is gemarkeerd met een standaardwaarde, moet u hier in de definitie de standaardwaarde als statische waarde gebruiken
parameterReference
. De standaardwaarde uit het schema wordt niet gebruikt als deze is gedefinieerd metparameterReference
.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 is opgegeven, wordt ervan uitgegaan dat het antwoord het schema in het hoofdobject bevat. 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 voor 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 definitie OpenAPI
Gerelateerde informatie
Overzicht van aangepaste connectoren
Feedback geven
We stellen feedback over problemen met ons connectorplatform of ideeën voor nieuwe functies zeer op prijs. Als u feedback wilt geven, gaat u naar Problemen indienen of hulp krijgen met connectoren en selecteert u het type feedback.