Delen via


Een aangepaste connector maken met een OpenAPI-extensie

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:

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"

'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: "Kalender-ID", "Onderwerp", "Gebeurtenisbeschrijving"

'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, 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"

'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 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.

'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 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

Dynamic-values 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.

Dynamische waarden kunnen op twee manieren worden gedefinieerd:

  1. 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."
            }
        }
    }
    
  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 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 bovendien naar eigenschappen binnen parameters verwijst, moet u de nieuwe extensie x-ms-dynamic-list toevoegen samen met x-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 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."
          }
        }
      } 
      

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 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.

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 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
  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 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 bovendien naar eigenschappen binnen parameters verwijst, moet u de nieuwe extensie x-ms-dynamic-properties samen met x-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 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 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

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.