Dela via

Skapa ett anpassat anslutningsprogram med en OpenAPI-definition

  • Artikel

Ett sätt att skapa anpassade anslutningsprogram för Azure Logic Apps, Microsoft Power Automate eller Microsoft Power Apps är att tillhandahålla en OpenAPI-definitionsfil, som är ett språkagnostiskt, maskinläsbart dokument som beskriver åtgärder och parametrar för ditt API. Tillsammans med OpenAPI:s färdiga funktionalitet kan du även inkludera dessa OpenAPI-tillägg när du skapar anpassade anslutningsprogram för Logic Apps och Power Automate:

I följande avsnitt beskrivs dessa tillägg.

Sammanfattning

Anger namnet för åtgärden.

Gäller för: åtgärder
Rekommenderat: Använd inledande versal i mening för summary.
Exempel: ”När en händelse läggs till i kalendern” eller ”Skicka ett e-postmeddelande”

”sammanfattning” för varje åtgärd.

"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
Rekommenderat: Använd inledande versal i rubrik för x-ms-summary.
Exempel: ”Kalender-ID”, ”Ämne”, ”Händelsebeskrivning”

”x-ms-summary” för varje entitet.

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

description

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

Gäller för: åtgärder, parametrar, svarsschema
Rekommenderat: Använd inledande versal i mening för description.
Exempel: ”Den här åtgärden utlöses när en ny händelse har lagts till i kalendern”, ”Ange ämnet för e-postmeddelandet.”

”beskrivning” för varje åtgärd eller entitet.

"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: åtgärder, parametrar, scheman

  • important åtgärder och parametrar visas alltid för användaren först.
  • advanced åtgärder och parametrar är dolda under en ytterligare meny.
  • internal åtgärder och parametrar är dolda från användaren.

Anteckning

För parametrar som är internal och required, måste du ange standardvärden.

Exempel: se mer-menyn och visa avancerade alternativ-menyn döljer advanced åtgärder och parametrar.

x-ms-visibility för att visa eller dölja å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ärdsfamiljens mapp.
  • revision—Ett heltal som anger revisionsnumret.
  • replacement—Ett objekt som innehåller ersättningens API-information och -åtgärder.
"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-operation-context

Används för att simulera starten av en utlösare för att möjliggöra testning av 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

På nivån för anslutningsprogram är det här en översikt över de funktioner som erbjuds av anslutningsprogrammet, inklusive specifika åtgärder.

Gäller för: anslutningsprogram

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

På åtgärdsnivån används det här för att identifiera att åtgärden stöder segmenteringsuppladdning och/eller statisk segmentstorlek och kan tillhandahållas av användaren.

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

Identifierar om den aktuella åtgärden är en utlösare som skapar en enskild händelse. Frånvaro av det här fältet innebär att det är en action-åtgärd.

Gäller för: åtgärder

  • single—Objektsvar
  • batch—Matrissvar
"x-ms-trigger": "batch"

x-ms-trigger-hint

En beskrivning av hur du startar en händelse för en utlösarå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 är schemat för en webhook-nyttolast som publicerats av externa tjänster till meddelande-URL:en.

Gäller: resurser

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

x-ms-notification-url

Identifierar i ett booleskt värde om en webhook-meddelande-URL ska placeras i den här parametern/det här fältet för en webhook-registreringsåtgärd.

Gäller för: parameter/inmatningsfält

"x-ms-notification-url": true

x-ms-url-encoding

Identifierar om den aktuella sökvägsparametern ska ha dubbel URL-kodning double eller enkel URL-kodning single. Frånvaro av det här fältet innebär single-kodning.

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

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

Använd dynamiska värden

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 

Dynamiska värden för att visa listor.

Hur du använder dynamiska värden

Anteckning

En sökvägssträng är en JSON-pekare som inte innehåller det inledande snedstrecket. Detta är en JSON-pekare: /property/childProperty och detta är en sökvägssträng: egenskap/childProperty.

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

  1. Använda x-ms-dynamic-values

    Namn Krävs Beskrivning
    operationId Ja Den åtgärd som returnerar värdena.
    parametrar Ja Ett objekt som tillhandahåller de indataparametrar som krävs för att anropa en åtgärd för "dynamic-values".
    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 en beskrivning av vä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>"
        }
    }
}

    Anteckning

    Du kan ha tvetydiga parameter referenser när du använder dynamiska värden. Om du till exempel vill följa definitionen av en åtgärd refererar dynamiska värden till fältet id, som är tvetydigt från definitionen eftersom det inte är uppenbart om det refererar till parametern id eller egenskapen 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

    Det finns inget sätt att referera till parametrar entydigt. Den här funktionen kan tillhandahållas i framtiden. Om du vill att åtgärden ska dra nytta av nya uppdateringar lägger du till det nya tillägget x-ms-dynamic-list tillsammans med x-ms-dynamic-values. Och om det dynamiska tillägget refererar till egenskaper inom parametrar måste du 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 varje indataegenskap för den dynamiska åtgärd som anropas definieras med antingen ett statiskt värdefält eller en dynamisk referens till källåtgärdens egenskap. Båda dessa alternativ anges nedan.

    • value—Det här är det literala värde som ska användas för indataparametern. Indataparametern för åtgärden GetDynamicList med namnet version definieras till exempel med det statiska värdet 2.0 i följande exempel.

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

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

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

      Anteckning

      Om du vill referera till en egenskap som har markerats som intern med ett standardvärde måste du använda standardvärdet som ett statiskt värde i definitionen här i stället för parameterReference. Standardvärdet från listan används inte om det har definierats med parameterReference.

      Name Obligatoriskt Beskrivning
      operationId Ja Den åtgärd som returnerar listan.
      parametrar Ja Ett objekt som tillhandahåller de indataparametrar som krävs för att anropa en åtgärd för dynamisk lista.
      itemsPath Nej En sökvägssträng som utvärderas till en matris med objekt i svarets nyttolast. Om itemsPath  inte tillhandahålls utvärderas svaret som en matris.
      itemTitlePath Nej En sökvägssträng i objektet inuti itemsPath  som refererar till en beskrivning av värdet.
      itemValuePath No En sökvägssträng i objektet inuti itemsPath  som refererar till objektets värde.

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

Använd dynamiskt 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

Den här bilden visar hur indataformuläret ändras baserat på vilket objekt som användaren väljer från listan:

Formuläret ändras baserat på det val som användaren gör.

Den här bilden visar hur utdata ändras baserat på vilket objekt som användaren väljer från den nedrullningsbara listan: I den här versionen väljer användaren bilar:

Användaren väljer bilar.

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

Användaren väljer mat.

Hur du använder dynamiskt schema

Anteckning

En sökvägssträng är en JSON-pekare som inte innehåller det inledande snedstrecket. Detta är en JSON-pekare: /property/childProperty och detta är en sökvägssträng: egenskap/childProperty.

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

  1. x-ms-dynamic-schema:

    Namn Krävs Beskrivning
    operationId Ja Den åtgärd som returnerar schema.
    parametrar 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 inget annat anges, antas svaret innehålla schemat i rotobjektets egenskaper. Om det här alternativet 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"
      }
    }
  }

    Anteckning

    Det kan finnas tvetydiga referenser i parametrarna. I följande definition av en åtgärd refererar till exempel det dynamiska schemat till ett fält med namnet query, som inte kan tolkas deterministiskt utifrån definitionen—om det refererar till parameterobjektet query eller strängegenskapen 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."
        }
    }
}
    Exempel från anslutningsprogram med öppen källkod
    Koppling Scenario Länka
    Biljetter Hämta schema för information om vald händelse Biljetter

  2. 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 åtgärden ska dra nytta av nya uppdateringar lägger du till det nya tillägget x-ms-dynamic-properties tillsammans med x-ms-dynamic-schema. Och om det dynamiska tillägget refererar till egenskaper inom parametrar måste du 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 varje indataegenskap för den dynamiska åtgärd som anropas definieras med antingen ett statiskt värdefält eller en dynamisk referens till källåtgärdens egenskap. Båda dessa alternativ anges nedan.

    • value—Det här är det literala värde som ska användas för indataparametern. Indataparametern för åtgärden GetDynamicSchema med namnet version definieras till exempel med det statiska värdet 2.0 i följande exempel.

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

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

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

      Anteckning

      Om du vill referera till en egenskap som har markerats som intern med ett standardvärde måste du använda 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 har definierats med parameterReference.

      Name Obligatoriskt Beskrivning
      operationId Ja Den åtgärd som returnerar schema.
      parametrar 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 annat anges, antas svaret innehålla schemat i rotobjektet. Om det här alternativet anges måste svaret innehålla egenskapen. För ett tomt eller odefinierat schema ska värdet vara null.

      Med x-ms-dynamic-properties kan parameterreferenser användas tillsammans med egenskapens sökvägssträng i syfte att refereras, både för nyckeln och för värdet på den dynamiska åtgärdens parameterreferens.

          {
    "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 ett anpassat anslutningsprogram från en OpenAPI-definition

Anpassade anslutningsprogram – en översikt

Ge feedback

Vi uppskattar feedback på problem med vår plattform för anslutningsprogram eller förslag på nya funktioner. Om du vill lämna feedback går du till Skicka problem eller få hjälp med anslutningsprogram och väljer typ av feedback.