Egyéni összekötő létrehozása kiterjesztéssel OpenAPI

Cikk
04/24/2024

Egyéni összekötők létrehozásának egyik módja a Azure Logic Apps, Microsoft Power Automate, vagy Microsoft Power Apps egy OpenAPI definíciós fájl biztosítása, amely egy nyelvfüggetlen, géppel olvasható dokumentum, 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 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álasz sé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álasz sé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 advanced a műveleteket és a 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ú double vagy egyetlen URL-kódolású 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ág-lekérdezésre 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 GetDynamicSchema nevű tulajdonság 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

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.

Megosztás a következőn keresztül:

Egyéni összekötő létrehozása kiterjesztéssel OpenAPI

ö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

Visszajelzés küldése

További források

Megosztás a következőn keresztül:

Egyéni összekötő létrehozása kiterjesztéssel OpenAPI

ö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