Skapa en anpassad anslutning med ett OpenAPI-tillägg

Ett sätt att skapa anpassade anslutningsappar för Microsoft Copilot Studio, Azure Logic Apps, Microsoft Power Automate eller Microsoft Power Apps är att tillhandahålla en OpenAPI-definitionsfil. En OpenAPI-definitionsfil är ett språkagnostiskt, maskinläsbart dokument som beskriver api:ets åtgärder och parametrar. Tillsammans med OpenAPI:s färdiga funktioner kan du även inkludera följande OpenAPI-tillägg när du skapar anpassade anslutningsappar för Logic Apps och 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

I följande avsnitt beskrivs dessa tillägg.

Sammanfattning

Anger namnet för åtgärden.

Gäller för: Operationer
Rekommenderas: Använd meningens initiala versal för summary.
Exempel: "När en händelse läggs till i kalendern" eller "Skicka ett e-postmeddelande"

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

x-ms-summary

Anger namnet för en entitet.

Gäller för: Parametrar, svarsschema
Rekommenderas: Använd inledande versal för x-ms-summary.
Exempel: Kalender-ID, Ämne, Händelsebeskrivning

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

beskrivning

Innehåller en detaljerad förklaring av åtgärdens funktioner eller en entitets format och funktion.

Gäller för: Åtgärder, parametrar, svarsschema
Rekommenderas: Använd satsfall för description.
Exempel: "Den här åtgärden utlöses när en ny händelse läggs till i kalendern", "Ange ämnet för e-postmeddelandet".

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

x-ms-visibility

Anger den användarriktade synligheten för en entitet.

Möjliga värden: important, advanced, och internal
Gäller för: Operationer, parametrar, scheman

• Användaren ser important alltid åtgärder och parametrar först.
• Användaren ser advanced endast åtgärder och parametrar när de använder en extra meny.
• Användaren ser internal inte åtgärder och parametrar.

Exempel: Menyerna Visa mer och Visa avancerade alternativ döljer advanced åtgärder och parametrar.

"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

Används för versionshantering och livscykelhantering av en åtgärd.

Gäller för: åtgärder

• family– En sträng som anger åtgärdens familjemapp.
• revision—Ett heltal som anger revisionsnumret.
• replacement– Ett objekt som innehåller information och åtgärder för det ersättande API:et.

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

x-ms-operation-context

Använd den här egenskapen för att simulera utlösaren så att du kan testa ett utlösarberoende flöde.

Gäller för: åtgärder

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

x-ms-capabilities

När du använder den här egenskapen på anslutningsnivå ger den en översikt över de funktioner som anslutningsappen erbjuder, inklusive specifika åtgärder.

Gäller för: kontakter

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

När du använder den här egenskapen på åtgärdsnivå identifierar den att åtgärden stöder segmentuppladdning och statisk segmentstorlek, vilket användaren kan tillhandahålla.

Gäller för: åtgärder

• chunkTransfer– Ett booleskt värde som anger om segmentöverföring stöds.

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

x-ms-trigger

Anger om den aktuella åtgärden är en utlösare som skapar en enskild händelse. Om det här fältet saknas är åtgärden en action.

Gäller för: åtgärder

• single—Objektets svar
• batch—Svar från matris

"x-ms-trigger": "batch"

x-ms-trigger-hint

Beskriver av hur du startar en händelse för en utlösande åtgärd.

Gäller för: åtgärder

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

x-ms-notification-content

Innehåller en schemadefinition för en webhook-meddelandebegäran. Det här schemat definierar den webhook-nyttolast som externa tjänster publicerar till meddelande-URL:en.

Gäller: resurser

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

x-ms-notification-url

Använd ett booleskt värde för att ange om en webhook-meddelande-URL ska inkluderas i den här parametern eller fältet för en webhookregistreringsåtgärd.

Gäller för: Parametrar och indatafält

"x-ms-notification-url": true

x-ms-url-encoding

Ange om den aktuella sökvägsparametern ska använda dubbel URL-kodning (double) eller enkel URL-kodning (single). Om det här fältet saknas, kodas det som standard till single.

Gäller för: sökvägsparametrar

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

x-ms-dynamic-values

Dynamiska värden är en lista med alternativ där användaren kan välja indataparametrar för en åtgärd. 

Gäller för: Parametrar

Hur du använder dynamiska värden

Du kan definiera dynamiska värden på två sätt:

• Använd x-ms-dynamic-values

  Namn	Krävs	Beskrivning
  operationId	Ja	Den åtgärd som returnerar värdena.
  parameters	Ja	Ett objekt som tillhandahåller de indataparametrar som krävs för att anropa en åtgärd för dynamiska värden.
  value-collection	Nej	En sökvägssträng som utvärderas till en matris med objekt i svarets nyttolast. Om "value-collection" inte har angetts, utvärderas svaret som en matris.
  value-title	Nej	En sökvägssträng i objektet inuti "value-collection" som refererar till en beskrivning av värdet.
  value-path	Nej	En sökvägssträng i objektet inuti "value-collection" som refererar till parametervärdet.

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

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

• Använd x-ms-dynamic-list

  Du kan inte entydigt referera till parametrar. Den här funktionen kan tillhandahållas i framtiden. Om du vill att din åtgärd ska dra nytta av nya uppdateringar lägger du till det nya tillägget x-ms-dynamic-list tillsammans med x-ms-dynamic-values. Om det dynamiska tillägget refererar till egenskaper inom parametrar måste du också lägga till det nya tillägget x-ms-dynamic-list tillsammans med x-ms-dynamic-values. De parameterreferenser som pekar mot egenskaper måste uttryckas som sökvägssträngar.

  • parameters– Den här egenskapen är ett objekt där du definierar varje indataegenskap för den dynamiska åtgärd som anropas med antingen ett statiskt värdefält eller en dynamisk referens till källåtgärdens egenskap. Båda dessa alternativ definieras i följande avsnitt.

  • value– Det här är det literalvärde som ska användas för indataparametern. I följande exempel definieras indataparametern för åtgärden GetDynamicList med namnet version med hjälp av det statiska värdet 2.0.

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

  • parameterReference– Det här är den fullständiga parameterreferenssökvägen, som börjar med parameternamnet följt av sökvägssträngen för egenskapen som ska refereras till. Till exempel definieras input-egenskapen för åtgärden GetDynamicList med namnet property1, som finns under parametern destinationInputParam1, som en dynamisk referens till en egenskap med namnet property1 under parametern sourceInputParam1 för källåtgärden.

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

Med x-ms-dynamic-list använder du parameterreferenser med sökvägssträngen för den egenskap som du refererar till. Använd de här parameterreferenserna för både nyckeln och värdet för den dynamiska åtgärdsparameterns referens.

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

Dynamiskt schema anger att schemat för den aktuella parametern eller svaret är dynamiskt. Det här objektet kan anropa en åtgärd som definieras av värdet för det här fältet, dynamiskt identifierar schemat och visar rätt användargränssnitt (UI) för att samla in indata från användare eller för att visa tillgängliga fält.

Gäller för: parametrar, svar

Följande bild visar hur indataformuläret ändras baserat på det objekt som användaren väljer i listan:

Följande bild visar hur utdata ändras, baserat på det objekt som användaren väljer i listrutan. I den här versionen väljer användaren Bilar:

I den här versionen väljer användaren Mat:

Hur du använder dynamiskt schema

Du kan definiera dynamiskt schema på två sätt:

• x-ms-dynamic-schema:

  Namn	Krävs	Beskrivning
  operationId	Ja	Den åtgärd som returnerar schema.
  parameters	Ja	Ett objekt som tillhandahåller de indataparametrar som krävs för att anropa en åtgärd för "dynamic-schema".
  value-path	Nej	En sökvägssträng som refererar till egenskapen som har schemat. Om du inte anger den här egenskapen antas svaret innehålla schemat i rotobjektets egenskaper. Om det anges måste svaret innehålla egenskapen. För ett tomt eller odefinierat schema ska värdet vara 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"
        }
      }
    }
  

{

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

Exempel från open source anslutningsappar

• x-ms-dynamic-properties:

  Det finns inget sätt att referera till parametrar entydigt. Den här funktionen kan tillhandahållas i framtiden. Om du vill att din åtgärd ska dra nytta av nya uppdateringar lägger du till det nya tillägget x-ms-dynamic-properties tillsammans med x-ms-dynamic-schema. Om det dynamiska tillägget refererar till egenskaper inom parametrar måste du också lägga till det nya tillägget x-ms-dynamic-properties tillsammans med x-ms-dynamic-schema. De parameterreferenser som pekar mot egenskaper måste uttryckas som sökvägssträngar.

  • parameters– Den här egenskapen är ett objekt där du definierar varje indataegenskap för den dynamiska åtgärd som anropas med antingen ett statiskt värdefält eller en dynamisk referens till källåtgärdens egenskap. Båda dessa alternativ definieras i följande avsnitt.

  • value– Det här är det literalvärde som ska användas för indataparametern. I följande exempel definieras indataparametern för åtgärden GetDynamicSchema med namnet version med det statiska värdet 2.0.

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

  • parameterReference– Det här är den fullständiga parameterreferenssökvägen, som börjar med parameternamnet följt av sökvägssträngen för egenskapen som ska refereras till. Till exempel definieras input-egenskapen för åtgärden GetDynamicSchema med namnet property1, som finns under parametern destinationInputParam1, som en dynamisk referens till en egenskap med namnet property1 under parametern sourceInputParam1 för källåtgärden.

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

  Obs

  Om du vill referera till en egenskap som är markerad som intern med ett standardvärde använder du standardvärdet som ett statiskt värde i definitionen här i stället för parameterReference. Standardvärdet från schemat används inte om det definieras med hjälp av parameterReference.

  Namn	Krävs	Beskrivning
  operationId	Ja	Den åtgärd som returnerar schema.
  parameters	Ja	Ett objekt som tillhandahåller de indataparametrar som krävs för att anropa en åtgärd för "dynamic-schema".
  itemValuePath	Nej	En sökvägssträng som refererar till egenskapen som har schemat. Om inget anges antas svaret innehålla schemat i rotobjektet. Om det anges måste svaret innehålla egenskapen. För ett tomt eller odefinierat schema ska värdet vara null.

  Med hjälp av x-ms-dynamic-properties kan du använda parameterreferenser med egenskapens sökvägssträng för både nyckeln och värdet av parameterreferensen i dynamiska operationer.

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

Gå vidare

Skapa en anpassad anslutning från en OpenAPI-definition

Relaterad information

Översikt över anpassade anslutningar

Lämna feedback

Vi uppskattar feedback på problem med vår anslutningsplattform eller nya funktioner. För att ge feedback går du till Skicka problem eller få hjälp med kontakter och väljer din feedbacktyp.