Egyéni összekötő definíciójának OpenAPI kiterjesztése

Cikk
09/07/2023

Egyéni összekötők létrehozásának egyik módja a Azure Logic Apps, vagy Microsoft Power Automate egy Microsoft Power Apps definíciós fájl biztosítása, amely egy nyelvtől független, géppel olvasható dokumentum, OpenAPI amely leírja az API műveleteit és paramétereit. A beépített funkciók mellett OpenAPI a következő OpenAPI bővítményeket is belefoglalhatja, amikor egyéni összekötőket hoz létre a Logic Apps és 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

A következő szakaszok ezeket a bővítményeket ismertetik.

összegzés

A művelet címe.

Hatóköre: Műveletek
Ajánlott: Használjon kis- és nagybetűket summary.
Például: „Esemény felvételekor” vagy „E-mail küldése”.

"összefoglaló" minden művelethez.

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

x-ms-summary

Egy entitás címe.

A következőkre vonatkozik: Paraméterek, válaszséma
Ajánlott: Használja a cím kis- és nagybetűit x-ms-summary.
Példa: "Naptárazonosító", "Tárgy", "Esemény leírása"

"x-ms-summary" minden entitáshoz.

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

description

A művelet funkciójának vagy egy entitás formátumának és funkciójának szöveges leírása.

A következőkre vonatkozik: Műveletek, paraméterek, válaszséma
Ajánlott: Használjon kis- és nagybetűket description.
Példa: "Ez a művelet akkor aktiválódik, amikor új eseményt adnak hozzá a naptárhoz", "Adja meg a levél tárgyát"

Az egyes műveletek vagy entitások "leírása".

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

x-ms-visibility

Azt határozza meg, hogy az entitás hogyan jelenik meg a felhasználók számára.

A lehetséges értékek: important, advanced és internal
A következőkre vonatkozik: Műveletek, paraméterek, sémák

Az important műveletek és paraméterek mindig elsőként fognak megjelenni a felhasználó számára.
Az advanced műveletek és paraméterek egy másik menüben lesznek elrejtve.
Az internal műveletek és paraméterek el lesznek rejtve a felhasználó elől.

Megjegyzés

Az és internal required paraméterekhez meg kell adnia az alapértelmezett értékeket.

Példa: A További információ és a Speciális beállítások megjelenítése menük elrejtik a műveleteket és a advanced paramétereket.

"x-ms-visibility" a műveletek és paraméterek megjelenítéséhez vagy elrejtéséhez.

"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

Egy művelet verziószámozásához és életciklus-kezelésére használható.

Hatóköre: Műveletek

family—Egy, a művelet családmappáját jelölő sztring.
revision— A verziószámot jelölő egész szám.
replacement—Egy, a helyettesítő API információit és műveleteit tartalmazó objektum.

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

x-ms-operation-context

Egy eseményindító aktiválásának szimulálására szolgál, hogy tesztelni lehessen az eseményindítótól függő folyamatokat.

Hatóköre: Műveletek

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

x-ms-capabilities

Az összekötő szintjén használva ez az összekötő által kínált képességek áttekintése, beleértve az adott műveleteket is.

A következőkre vonatkozik: Csatlakozók

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

A művelet szintjén használva ez annak azonosítására szolgál, hogy a művelet támogatja-e az adattömbök feltöltését és/vagy a statikus adattömbméretet, és a felhasználó megadhatja.

Hatóköre: Műveletek

chunkTransfer— Egy logikai érték, amely azt jelzi, hogy az adattömbátvitel támogatott-e.

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

x-ms-trigger

Azonosítja, hogy az aktuális művelet egyetlen eseményt létrehozó eseményindító-e. A mező hiánya azt jelenti, hogy ez egy action művelet.

Hatóköre: Műveletek

single—Objektum válasza
batch—Tömb válasza

"x-ms-trigger": "batch"

x-ms-trigger-hint

Annak a leírása, hogyan aktiválható egy esemény egy eseményindító művelethez.

Hatóköre: Műveletek

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

x-ms-notification-content

Egy webhook értesítési kérelmének sémadefinícióját tartalmazza. Ez a webhook külső szolgáltatások által az értesítési URL-ben közzétett hasznos adatainak sémája.

A következőkre vonatkozik: Erőforrások

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

x-ms-notification-url

Egy logikai értékben azonosítja, hogy webhook-értesítési URL-címet kell-e elhelyezni ebben a paraméterben/mezőben egy webhook-regisztrációs művelethez.

A következőkre vonatkozik: Paraméterek/beviteli mezők

"x-ms-notification-url": true

x-ms-url-encoding

Meghatározza, hogy az aktuális elérési út paraméter dupla URL-kódolású vagy egyetlen URL-kódolású double single legyen-e. A mező hiánya kódolást jelez single .

A következőkre vonatkozik: Elérésiút-paraméterek

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

Dinamikus értékek használata

A dinamikus értékek lehetőségek listáját kínálják a felhasználó számára, amelyből kiválaszthatja egy művelet bemeneti paramétereit. 

Hatóköre: Paraméterek 

Dinamikus értékek listák megjelenítéséhez.

A dinamikus értékek használata

Megjegyzés

Az elérési út sztring egy JSON-mutató, amely nem tartalmazza a kezdő perjelet. Tehát ez egy JSON-mutató: /property/childProperty, és ez egy útvonal-karakterlánc: property/childProperty.

A dinamikus értékek kétféle módon határozhatók meg:

A x-ms-dynamic-values használata

Név szerint	Szükséges	Ismertetés
operationId	Igen	Az értékeket visszaadó művelet.
paraméterek	Igen	Egy objektum, amely megadja a dinamikus-értékek művelet meghívásához szükséges bemeneti paramétereket.
value-collection	Nem	A válaszban objektumokból álló tömbként kiértékelt útvonal-karakterlánc. Ha az érték-gyűjtemény nincs megadva, a válasz tömbként lesz értelmezve.
value-title	Nem	Az objektumon belüli érték-gyűjteményben található útvonal-karakterlánc, amely az érték leírására hivatkozik.
value-path	Nem	Az objektumon belüli érték-gyűjteményben található útvonal-karakterlánc, amely a paraméterértékre hivatkozik.

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

Megjegyzés

Dinamikus értékek használatakor előfordulhat, hogy nem egyértelműek a paraméterek hivatkozásai. Egy művelet következő definíciójában például a dinamikus értékek a mezőazonosítóra hivatkoznak, ami nem egyértelmű a definíciótól, mert nem egyértelmű, hogy az id paraméterre vagy a requestBody/id tulajdonságra hivatkozik-e.

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

x-ms-dynamic-list

A paraméterekre nem lehet egyértelműen hivatkozni. Ez a funkció a jövőben elérhető lehet. Ha azt szeretné, hogy a művelet kihasználhassa az új frissítéseket, adja hozzá az új x-ms-dynamic-list bővítményt az x-ms-dynamic-values bővítménnyel együtt. Továbbá, ha a dinamikus bővítmény a paramétereken belüli tulajdonságokra hivatkozik, akkor hozzá kell adni az új x-ms-dynamic-list bővítményt az x-ms-dynamic-values bővítménnyel együtt. A tulajdonságokra mutató paraméterhivatkozásokat elérésiút-sztringként kell kifejezni.

parameters—Ez a tulajdonság egy olyan objektum, amelyben a meghívott dinamikus művelet minden bemeneti tulajdonsága állandó érték mezővel vagy a forrásoldali művelet tulajdonságára mutató dinamikus hivatkozással van definiálva. Mindkét beállítás meghatározása a következőkben található.
value—Ez a bemeneti paraméterhez használható konstansérték. A következő példában a GetDynamicList művelet version nevű műveletének bemeneti paraméterét a 2.0 statikus érték határozza meg.
```
{
    "operationId": "GetDynamicList",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```

parameterReference— Ez a paraméter teljes hivatkozási elérési útja, amely a paraméter nevével kezdődik, amelyet a hivatkozni kívánt tulajdonság elérési útjának karakterlánca követ. Például a GetDynamicList nevű tulajdonság1 művelet bemeneti tulajdonsága, amely a destinationInputParam1 paraméter alatt található, dinamikus hivatkozásként van definiálva a forrásművelet sourceInputParam1 paraméterében található property1 nevű tulajdonságra. ·

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

Megjegyzés

Ha olyan tulajdonságra szeretne hivatkozni, amely alapértelmezett értékkel belsőként van megjelölve, akkor az alapértelmezett értéket statikus értékként kell használnia az itt található definícióban a helyett parameterReference. A rendszer nem használja a lista alapértelmezett értékét, ha azt a használatával definiálja parameterReference.

Name	Szükséges	Description
operationId	Igen	A listát visszaadó művelet.
paraméterek	Igen	Egy objektum, amely megadja a dinamikus lista művelet meghívásához szükséges bemeneti paramétereket.
itemsPath	Nem	A válaszban objektumokból álló tömbként kiértékelt útvonal-karakterlánc. Ha az  `itemsPath`  nincs meghatározva, a rendszer a választ tömbként értékeli ki.
itemTitlePath	Nem	Egy elérési út sztringje az  `itemsPath`  elemen belüli objektumban, amely az érték leírására vonatkozik.
itemValuePath	No	Egy elérési út karakterlánc a benne lévő `itemsPath` objektumban, amely az elem értékére hivatkozik.

Az x-ms-dynamic-list esetében a hivatkozott tulajdonság elérési útjának sztringjével együtt kell használni a paraméterhivatkozásokat. Ezeket a paraméter-hivatkozásokat használja a dinamikus művelet paraméter-hivatkozásának kulcsához és értékéhez is.

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

Dinamikus séma használata

A dinamikus séma jelzi, hogy az erre a paraméterre vagy válaszra vonatkozó séma dinamikus jellegű. Ez az objektum meghív egy műveletet, amelyet a mező értéke határoz meg, dinamikusan felderíti a sémát, és megjeleníti a megfelelő felhasználói felületet a felhasználói bevitel gyűjtéséhez, vagy megjeleníti az elérhető mezőket.

A következőkre vonatkozik: Paraméterek, válaszok

Ez a kép bemutatja, hogyan változik a beviteli űrlap a felhasználó által a listából kiválasztott elem alapján:

Az űrlap a felhasználó választásától függően változik.

Ez a kép bemutatja, hogyan változnak a kimenetek a felhasználó által a legördülő listából kiválasztott elem alapján. Ebben a példában a felhasználó a Autók elemet választja:

A felhasználó kiválasztja az Autók lehetőséget.

Ebben a példában a felhasználó az Élelmiszer elemet választja:

A felhasználó kiválasztja az Étel lehetőséget.

A dinamikus séma használata

Megjegyzés

A dinamikus séma kétféle módon határozható meg:

x-ms-dynamic-schema:

Név szerint	Szükséges	Ismertetés
operationId	Igen	A sémát visszaadó művelet.
paraméterek	Igen	Egy objektum, amely megadja a dinamikus-séma művelet meghívásához szükséges bemeneti paramétereket.
value-path	Nem	Az elérési út sémát tartalmazó tulajdonságra hivatkozó útvonalsztringje. Ha nincs megadva, akkor a kiértékelés azt feltételezi, hogy a válasz a gyökérobjektum tulajdonságaiban tartalmazza a sémát. Ha meg van adva, a sikeres válasznak tartalmaznia kell a tulajdonságot. Üres vagy nem definiált séma esetén ennek az értéknek null értékűnek kell lennie.

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

Megjegyzés

A paraméterekben kétértelmű hivatkozások lehetnek. Egy művelet következő definíciójában például a dinamikus séma egy query nevű mezőre hivatkozik, amely determinisztikusan nem érthető a definícióból, hogy a paraméterobjektum-lekérdezésre— vagy a lekérdezés/lekérdezés sztringtulajdonságra hivatkozik-e . ·

{

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

Példák nyílt forráskódú összekötőkből

Összekötő	Forgatókönyv	Hivatkozás
Jegykiadás	Séma lekérte a kiválasztott esemény részleteit	Jegykiadás

x-ms-dynamic-properties:

A paraméterekre nem lehet egyértelműen hivatkozni. Ez a funkció a jövőben elérhető lehet. Ha azt szeretné, hogy a művelet kihasználhassa az új frissítéseket, adja hozzá az új x-ms-dynamic-properties bővítményt az x-ms-dynamic-schema bővítménnyel együtt. Továbbá, ha a dinamikus bővítmény a paramétereken belüli tulajdonságokra hivatkozik, akkor hozzá kell adni az új x-ms-dynamic-properties bővítményt az x-ms-dynamic-schema bővítménnyel együtt. A tulajdonságokra mutató paraméterhivatkozásokat elérésiút-sztringként kell kifejezni.

parameters—Ez a tulajdonság egy olyan objektum, amelyben a meghívott dinamikus művelet minden bemeneti tulajdonsága állandó érték mezővel vagy a forrásoldali művelet tulajdonságára mutató dinamikus hivatkozással van definiálva. Mindkét beállítás meghatározása a következőkben található.
value—Ez a bemeneti paraméterhez használható konstansérték. A következő példában a version nevű GetDynamicSchema művelet bemeneti paramétere 2.0 statikus értékkel van definiálva.
```
{
    "operationId": "GetDynamicSchema",
    "parameters": {
      "version": {
        "value": "2.0"
      }
    }
}
```

parameterReference— Ez a paraméter teljes hivatkozási elérési útja, amely a paraméter nevével kezdődik, amelyet a hivatkozni kívánt tulajdonság elérési útjának karakterlánca követ. Például a tulajdonság1 nevű GetDynamicSchema művelet bemeneti tulajdonsága, amely a destinationInputParam1 paraméter alatt található, dinamikus hivatkozásként van definiálva a forrásművelet sourceInputParam1 paraméterében található property1 · nevű tulajdonságra.

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

Megjegyzés

Ha olyan tulajdonságra szeretne hivatkozni, amely alapértelmezett értékkel belsőként van megjelölve, akkor az alapértelmezett értéket statikus értékként kell használnia az itt található definícióban a helyett parameterReference. A séma alapértelmezett értéke nem használatos, ha a használatával van definiálva parameterReference.

Name	Szükséges	Description
operationId	Igen	A sémát visszaadó művelet.
paraméterek	Igen	Egy objektum, amely megadja a dinamikus-séma művelet meghívásához szükséges bemeneti paramétereket.
itemValuePath	Nem	Az elérési út sémát tartalmazó tulajdonságra hivatkozó útvonalsztringje. Ha nincs megadva, akkor a kiértékelés azt feltételezi, hogy a válasz a gyökérobjektumban tartalmazza a sémát. Ha meg van adva, a sikeres válasznak tartalmaznia kell a tulajdonságot. Üres vagy nem definiált séma esetén ennek az értéknek null értékűnek kell lennie.

Az x-ms-dynamic-properties alkalmazásával a paraméterhivatkozások a hivatkozni kívánt tulajdonság elérési útjának sztringjével is használhatók, a dinamikus művelet paraméterhivatkozásának kulcsa és értéke esetében egyaránt.

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

Következő lépés

Egyéni összekötő létrehozása definícióból OpenAPI

Kapcsolódó információk

Egyéni összekötők áttekintése

Visszajelzés küldése

Nagyra értékeljük az összekötőplatform problémáival kapcsolatos visszajelzéseket és az új funkciókkal kapcsolatos ötleteket. Ha visszajelzést szeretne küldeni, lépjen a Problémák küldése vagy segítség kérése az összekötőkkel kapcsolatban részre, és válassza ki a visszajelzés típusát.

Egyéni összekötő definíciójának OpenAPI kiterjesztése

összegzés

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

Dinamikus értékek használata

A dinamikus értékek használata

Dinamikus séma használata

A dinamikus séma használata

Példák nyílt forráskódú összekötőkből

Következő lépés

Kapcsolódó információk

Visszajelzés küldése

További források