Delen via

Een aangepaste connector maken met een OpenAPI-extensie

Een manier om aangepaste connectors te maken voor Microsoft Copilot Studio, Azure Logic Apps, Microsoft Power Automate of Microsoft Power Apps is door een OpenAPI-definitiebestand op te geven. Een OpenAPI-definitiebestand is een taalneutraal, machineleesbaar document dat de bewerkingen en parameters van uw API beschrijft. Naast de out-of-the-box-functionaliteit van OpenAPI kunt u ook de volgende OpenAPI-extensies opnemen wanneer u aangepaste connectors voor Logic Apps en Power Automate maakt:

In de volgende secties worden deze uitbreidingen beschreven.

samenvatting

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"

'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, responsschema
Aanbevolen: Gebruik hoofdlettergebruik 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...
        }]
    }
},

beschrijving

Biedt een gedetailleerde uitleg over de functionaliteit van de bewerking of de indeling en functie van een entiteit.

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

'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

  • De gebruiker ziet altijd eerst bewerkingen important en parameters.
  • De gebruiker ziet alleen bewerkingen advanced en parameters wanneer ze een extra menu gebruiken.
  • De gebruiker ziet geen internal bewerkingen en parameters.

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.

'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

Gebruiken voor versiebeheer 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

Gebruik deze eigenschap om het activeren van een trigger te simuleren, zodat u een triggerafhankelijke stroom kunt testen.

Van toepassing op: bewerkingen

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

x-ms-capabilities

Wanneer u deze eigenschap op connectorniveau gebruikt, biedt deze een overzicht van de mogelijkheden die de connector biedt, inclusief specifieke bewerkingen.

Van toepassing op: connectoren

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

Wanneer u deze eigenschap op bewerkingsniveau gebruikt, wordt aangegeven dat de bewerking ondersteuning biedt voor segmenten uploaden en statische segmentgrootte, die de gebruiker kan bieden.

Van toepassing op: bewerkingen

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

x-ms-trigger

Geeft aan of de huidige bewerking een trigger is die één gebeurtenis produceert. Als dit veld afwezig is, is de bewerking een action.

Van toepassing op: bewerkingen

  • single—Objectrespons
  • batch—Array-respons
"x-ms-trigger": "batch"

x-ms-trigger-hint

Beschrijft 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 schema definieert de belading van de webhook die externe services naar de meldings-URL sturen.

Geldt voor: bronnen

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

x-ms-notification-url

Gebruik een Booleaanse waarde om op te geven of een webhookmeldings-URL moet worden opgenomen in deze parameter of veld voor een webhookregistratiebewerking.

Van toepassing op: Parameters en invoervelden

"x-ms-notification-url": true

x-ms-url-encoding

Geef op of de huidige padparameter dubbele URL-codering (double) of enkele URL-codering () moet gebruiken.single Als dit veld ontbreekt, wordt het standaard single gecodeerd.

Van toepassing op: padparameters

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

x-ms-dynamic-values

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

Van toepassing op: Parameters

Dynamische waarden voor het weergeven van lijsten.

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.

U kunt dynamische waarden op twee manieren definiëren:

  • 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 gebruik van dynamische waarden kan leiden tot dubbelzinnige parameterverwijzingen. In de volgende definitie van een bewerking verwijzen de dynamische waarden bijvoorbeeld naar de veld-id. De definitie maakt niet duidelijk of de verwijzing naar de parameter-id of de eigenschap requestBody/idis.

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

  • Gebruik x-ms-dynamic-list

    U kunt niet eenduidig verwijzen naar parameters. 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 met x-ms-dynamic-values. Als uw dynamische extensie verwijst naar eigenschappen binnen parameters, moet u ook de nieuwe extensie x-ms-dynamic-list toevoegen.x-ms-dynamic-values De parameterverwijzingen die naar eigenschappen verwijzen, moeten worden uitgedrukt als padtekenreeksen.

    • parameters— Deze eigenschap is een object waarin u elke invoereigenschap van de dynamische bewerking definieert die wordt aangeroepen met een statisch waardeveld of een dynamische verwijzing naar de eigenschap van de bronbewerking. Beide opties worden gedefinieerd in de volgende sectie.

    • 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 pad naar de parameter, te beginnen 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 wilt verwijzen naar een eigenschap die als intern is gemarkeerd met een standaardwaarde, gebruikt u de standaardwaarde als een statische waarde in de definitie hier, in plaats van parameterReference. De standaardwaarde uit de lijst wordt niet gebruikt als deze is gedefinieerd door using 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 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."
    }
  }
}

x-ms-dynamic-schema

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 de volgende afbeelding ziet u hoe het invoerformulier wordt gewijzigd 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 de volgende afbeelding ziet u hoe de uitvoer verandert, op basis van het item dat de gebruiker selecteert in de vervolgkeuzelijst. In deze versie selecteert de gebruiker Auto's:

De gebruiker selecteert Cars (auto's)

In deze versie selecteert de gebruiker Eten:

De gebruiker selecteert Food (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.

U kunt dynamisch schema op twee manieren definiëren:

  • 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 u deze eigenschap niet opgeeft, wordt ervan uitgegaan dat het antwoord het schema bevat in de eigenschappen van het hoofdobject. Indien gespecificeerd, moet de succesvolle 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 kunnen ambigu verwijzingen bevatten. 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

Verbindingsstuk 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 met x-ms-dynamic-schema. Als uw dynamische extensie verwijst naar eigenschappen binnen parameters, moet u ook de nieuwe extensie x-ms-dynamic-properties toevoegen.x-ms-dynamic-schema De parameterverwijzingen die naar eigenschappen verwijzen, moeten worden uitgedrukt als padtekenreeksen.

    • parameters— Deze eigenschap is een object waarin u elke invoereigenschap van de dynamische bewerking definieert die wordt aangeroepen met een statisch waardeveld of een dynamische verwijzing naar de eigenschap van de bronbewerking. Beide opties worden gedefinieerd in de volgende sectie.

    • 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 wilt verwijzen naar een eigenschap die als intern is gemarkeerd met een standaardwaarde, gebruikt u de standaardwaarde als een statische waarde in de definitie hier, in plaats van parameterReference. De standaardwaarde uit het schema wordt niet gebruikt als deze is 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 is opgegeven, wordt ervan uitgegaan dat het antwoord het schema in het hoofdobject bevat. Indien gespecificeerd, moet de succesvolle respons de eigenschap bevatten. Voor een leeg of ongedefinieerd schema moet deze waarde null zijn.

    Met behulp van x-ms-dynamic-properties kunt u parameterverwijzingen gebruiken met de padstring van de eigenschap waarnaar wordt verwezen, zowel voor de sleutel als de waarde van de referentie van de dynamische operatieparameter.

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

Overzicht van aangepaste connectoren

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.

  • Last updated on