Udvide en OpenAPI-definition for en brugerdefineret connector

Du kan oprette brugerdefinerede connectorer til Azure Logic Apps, Microsoft Power Automate eller Microsoft Power Apps på én måde ved at angive en OpenAPI-definitionsfil, som er et dokument uden et defineret sprog, som kan maskinlæses, og som beskriver handlinger og parametre for din API. Sammen med OpenAPI's brugsklare funktionalitet kan du også inkludere disse OpenAPI-udvidelser, når du opretter brugerdefinerede connectorer til Logic Apps og 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

Her er flere oplysninger om disse udvidelser:

Oversigt

Specificerer handlingens titel.
Gælder for: Handlinger
Anbefalet: Brug Første bogstav i sætning med stort for summary.
Eksempel: "Når en hændelse føjes til kalender" eller "Send en mail"

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

x-ms-summary

Specificerer titlen for et objekt.
Gælder for: Parametre, Svarskema
Anbefalet: Brug Alle ord med stort begyndelsesbogstav for x-ms-summary.
Eksempel: "Kalender-id", "Emne", "Beskrivelse Af Hændelse" osv

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

beskrivelse

Angiver en detaljeret beskrivelse af handlingens funktioner eller et objekts format og funktion.
Gælder for: Handlinger, Parametre, Svarskema
Anbefalet: Brug Første bogstav i sætning med stort for description.
Eksempel: "Denne handling udløses, når en ny hændelse føjes til kalenderen", "Angiv emnet i mailen" osv

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

x-ms-visibility

Angiver objektets synlighed over for brugeren.
Mulige værdier: important, advanced og internal
Gælder for: Handlinger, Parametre og Skemaer

• important handlinger og parametre vises altid for brugeren først.
• advanced handlinger og parametre er skjult under en yderligere menu.
• internal handlinger og parametre er skjult for brugeren.

Eksempel: Menuen Se mere og Vis avancerede indstillinger skjuler advanced handlinger og parametre.

"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

Bruges til versionsstyring og livscyklusstyring i forbindelse med en handling.
Gælder for: Handling

• family—En streng, der angiver handlingens familiemappe.
• revision—Et heltal, der angiver revisionsnummeret.
• replacement—Et objekt, der indeholder oplysninger og handlinger i forbindelse med erstatnings-API'en.

"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-handling-kontekst

Bruges til at simulere udløsningen af en udløser for at aktivere test af et udløserafhængigt flow.
Gælder for: Handling

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

x-ms-capabilities

På connector-niveauet er dette en oversigt over de egenskaber, der tilbydes af connectoren, herunder bestemte handlinger.
Gælder for: Connector

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

På handlingsniveauet bruges denne til at identificere, at handlingen understøtter segmenteret overførsel og/eller den statiske segmentstørrelse og kan leveres af brugeren.
Gælder for: Handling

• chunkTransfer—En boolesk værdi, der angiver, om segmenteret overførsel understøttes.

"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

Angiver, om den aktuelle handling er en udløser, der producerer en enkelt hændelse. Fravær af dette felt betyder, at det er en Action-handling.
Gælder for: Handling

• single—Objektsvar
• batch—Matrixsvar

"x-ms-trigger": "batch"

x-ms-trigger-hint

En beskrivelse af, hvordan en hændelse skal aktiveres for en udløserhandling.
Gælder for: Handling

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

x-ms-notification-content

Indeholder en skemadefinition af en anmodning om webhook-meddelelse. Dette er skemaet for webhook-nyttedata, der er postet af eksterne tjenester til URL-adressen for meddelelsen.
Gælder for: Handling

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

x-ms-notification-url

Angiver en boolesk værdi, hvis en URL-adresse for en webhook-meddelelse skal placeres i denne parameter/dette felt for en webhook-registreringshandling.
Gælder for: Parameter/inputfelt

"x-ms-notification-url": true

x-ms-url-encoding

Angiver, om den aktuelle stiparameter skal være dobbelt-URL-adressekodet double eller enkelt-URL-adressekodet single. Fravær af dette felt betyder single-kodning.
Gælder for: Stiparameter

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

Brug dynamiske værdier

Dynamiske værdier er en liste over indstillinger, hvor brugeren kan vælge inputparametre til en handling. 

Gælder for: Parametre 

Sådan bruger du dynamiske værdier

Du kan definere dynamiske værdier på to måder:

1. Brug x-ms-dynamic-values

   Navn	Obligatorisk	Beskrivelse
   operationId	Ja	Den handling, der returnerer værdierne.
   parameters	Ja	Et objekt, der angiver de inputparametre, der kræves for at aktivere en handling af dynamiske værdier.
   value-collection	Nej	En stistreng, der evalueres til en matrix af objekter i svarets nyttedata. Hvis value-collection ikke er specificeret, vurderes svaret som en matrix.
   value-title	Nej	En stistreng i objektet i "value-collection", der henviser til beskrivelsen af værdien.
   value-path	Nej	En stistreng i objektet i "value-collection", der henviser til parameterværdien.

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

   Bemærk

   Det er muligt at have tvetydige parameterreferencer, når der bruges dynamiske værdier. I følgende definition af en handling refererer de dynamiske værdier f.eks. til feltet id, som er flertydigt i definitionen, da det ikke er klart, om det refererer til parameterens id eller egenskaben 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

   Der findes ikke en metode til at referere til parametre entydigt. Denne funktion findes muligvis i fremtiden. Hvis du vil have, at din handling skal drage fordel af eventuelle nye opdateringer, skal du tilføje den nye udvidelse x-ms-dynamic-list sammen med x-ms-dynamic-values. Hvis din dynamiske udvidelse desuden refererer til egenskaber i parametre, skal du tilføje den nye udvidelse x-ms-dynamic-list sammen med x-ms-dynamic-values. De parameterreferencer, der peger på egenskaber, skal udtrykkes som stistrenge.

   • parameters—Denne egenskab er et objekt, hvor hver inputegenskab for den dynamiske handling, der kaldes, er defineret med et statisk værdifelt eller en dynamisk reference til kildehandlingens egenskab. Begge disse indstillinger er defineret nedenfor.

   • value—Dette er den konstantværdi, der skal bruges til inputparameteren. Eksempelvis er inputparameteren for handlingen GetDynamicList med navnet version defineret med en statisk værdi 2.0 i det følgende eksempel.

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

   • parameterReference—Dette er parameterens fulde referencesti, der starter med parameternavnet efterfulgt af stistrengen til den egenskab, der skal refereres til. Inputegenskaben for handlingen GetDynamicList med navnet property1, som findes under parameteren destinationInputParam1, er f.eks. defineret som en dynamisk reference til en egenskab kaldet property1 under parameteren sourceInputParam1 i kildehandlingen.

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

     Bemærk

     Hvis du vil referere til en egenskab, der er markeret som intern, med en standardværdi, skal du bruge standardværdien som en statisk værdi i definitionen her i stedet for parameterReference. Standardværdien fra listen bruges ikke, hvis den er defineret vha. parameterReference.

     Navn	Obligatorisk	Beskrivelse
     operationId	Ja	Den handling, der returnerer listen.
     parameters	Ja	Et objekt, der angiver de inputparametre, der kræves for at aktivere en handling for en dynamisk liste.
     itemsPath	Nej	En stistreng, der evalueres til en matrix af objekter i svarets nyttedata. Hvis itemsPath ikke er angivet, evalueres svaret som en matrix.
     itemTitlePath	Nej	En stistreng i objektet i  itemsPath , der henviser til beskrivelsen af værdien.
     itemValuePath	Nej	En stistreng i objektet i  itemsPath , der refererer til elementets værdi.

     Med x-ms-dynamic-list kan du bruge parameterreferencer med stistrengen til den egenskab, du refererer til. Brug disse parameterreferencer for både nøglen og værdien af referencen til den dynamiske handlingsparameter.

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

Brug dynamisk skema

Det dynamiske skema angiver, at skemaet for den aktuelle parameter eller det aktuelle svar er dynamisk. Dette objekt kalder en handling, der er defineret af værdien i dette felt, finder skemaet dynamisk og viser den relevante brugergrænseflade til indsamling af brugerinput eller visning af tilgængelige felter.

Gælder for: Parametre, Svar

Dette billede viser, hvordan inputformatet ændres baseret på det element, som brugeren vælger på listen:

Dette billede viser, hvordan output ændres baseret på det element, som brugeren vælger på rullelisten. I denne version vælger brugeren Biler:

I denne version vælger brugeren Fødevarer:

Sådan bruger du dynamisk skema

Du kan definere et dynamisk skema på to måder:

1. x-ms-dynamic-schema:

   Navn	Obligatorisk	Beskrivelse
   operationId	Ja	Den handling, der returnerer skemaet.
   parameters	Ja	Et objekt, der angiver de inputparametre, der kræves for at aktivere en handling for dynamisk skema.
   value-path	Nej	En stistreng, der henviser til den egenskab, der har skemaet. Hvis det ikke er angivet, antages svaret at indeholde skemaet i rodobjektets egenskaber. Hvis det er angivet, skal det vellykkede svar indeholde egenskaben. I forbindelse med et tomt eller ikke-defineret skema er dens værdi NULL.

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

   Bemærk

   Der kan være flertydige referencer i parametrene. I den følgende definition af en handling refererer det dynamiske skema f.eks. til et felt med navnet query, som ikke kan udledes deterministisk af definitionen—uanset om det refererer til parameterobjektet query eller strengegenskaben 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."
           }
       }
   }
   

   Eksempler fra Open Source-connectorer

   Connector	Scenarie	Link
   Billetsalg	Få skema med detaljer om den valgte hændelse	Billetsalg

2. x-ms-dynamic-properties:

   Der findes ikke en metode til at referere til parametre entydigt. Denne funktion findes muligvis i fremtiden. Hvis du vil have, at din handling skal drage fordel af eventuelle nye opdateringer, skal du tilføje den nye udvidelse x-ms-dynamic-properties sammen med x-ms-dynamic-schema. Hvis din dynamiske udvidelse desuden refererer til egenskaber i parametre, skal du tilføje den nye udvidelse x-ms-dynamic-properties sammen med x-ms-dynamic-schema. De parameterreferencer, der peger på egenskaber, skal udtrykkes som stistrenge.

   • parameters—Denne egenskab er et objekt, hvor hver inputegenskab for den dynamiske handling, der kaldes, er defineret med et statisk værdifelt eller en dynamisk reference til kildehandlingens egenskab. Begge disse indstillinger er defineret nedenfor.

   • value—Dette er den konstantværdi, der skal bruges til inputparameteren. Inputparameteren for GetDynamicSchema med navnet version er f.eks. defineret med en statisk værdi 2.0 i det følgende eksempel.

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

   • parameterReference—Dette er parameterens fulde referencesti, der starter med parameternavnet efterfulgt af stistrengen til den egenskab, der skal refereres til. Inputegenskaben for handlingen GetDynamicSchema med navnet property1, som findes under parameteren destinationInputParam1, er f.eks. defineret som en dynamisk reference til en egenskab kaldet property1 under parameteren sourceInputParam1 i kildehandlingen.

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

     Bemærk

     Hvis du vil referere til en egenskab, der er markeret som intern, med en standardværdi, skal du bruge standardværdien som en statisk værdi i definitionen her i stedet for parameterReference. Standardværdien fra skemaet bruges ikke, hvis den er defineret vha. parameterReference.

     Navn	Obligatorisk	Beskrivelse
     operationId	Ja	Den handling, der returnerer skemaet.
     parameters	Ja	Et objekt, der angiver de inputparametre, der kræves for at aktivere en handling for dynamisk skema.
     itemValuePath	Nej	En stistreng, der henviser til den egenskab, der har skemaet. Hvis det ikke er angivet, antages svaret at indeholde skemaet i rodobjektet. Hvis det er angivet, skal det vellykkede svar indeholde egenskaben. I forbindelse med et tomt eller ikke-defineret skema er dens værdi NULL.

     Med x-ms-dynamic-properties kan parameterreferencer bruges sammen med stistrengen for den egenskab, der skal refereres til, både for nøglen og værdien for parameterreferencen for den dynamiske handling.

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

Næste trin

• Oprette en brugerdefineret connector fra en OpenAPI-definition
• Oversigt over brugerdefinerede connectorer