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

Egyéni összekötő létrehozása bővítménnyel OpenAPI

  • Cikk

Az egyik módja annak, hogy egyéni összekötőket hozzon létre a Azure Logic Apps Microsoft Power Automate, vagy Microsoft Power Apps egy definíciós fájl megadása OpenAPI , 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 felveheti, amikor egyéni összekötőket hoz létre a Logic Apps és Power Automate:

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

összegzés

A művelet címe.

A következőkre vonatkozik: Műveletek
Ajánlott: Mondat kis- és nagybetűinek summary használata.
Példa: "Amikor egy esemény hozzá van adva a naptárhoz" vagy "E-mail küldése"

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

"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 mondatot a következőhöz description:
Példa: "Ez a művelet akkor indul el, ha új eseményt adnak hozzá a naptárhoz", "Adja meg az e-mail tárgyát"

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

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

  • important A műveletek és a paraméterek mindig először a felhasználó számára jelennek meg.
  • advanced A műveletek és a paraméterek egy további menü alatt vannak elrejtve.
  • internal A műveletek és a paraméterek rejtve vannak a felhasználó elől.

Feljegyzés

Az és internal paraméterek required esetében meg kell adnia az alapértelmezett értékeket.

Példa: A Továbbiak és a Speciális beállítások megjelenítése menü elrejti a műveleteket advanced és a paramétereket.

"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– A műveletcsalád mappáját jelölő karakterlánc.
  • revision—A revíziószámot jelölő egész szám.
  • replacement– A helyettesítő API-információkat és műveleteket 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: Összekötők

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

A műveleti szinten való használat esetén ez annak azonosítására szolgál, hogy a művelet támogatja-e az adattömbfeltöltést és/vagy a statikus adattömbméretet, és a felhasználó megadhatja.

Hatóköre: Műveletek

  • chunkTransfer—Logikai érték, amely azt jelzi, hogy támogatott-e az adattömbátvitel.
"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

Azonosítja, hogy az aktuális művelet egyetlen eseményt előidéző 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 egy 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

Azonosítja, hogy az aktuális elérési út paraméternek dupla URL-kódolásúnak double vagy egyetlen URL-kódolásúnak single kell-e lennie. A mező hiánya kódolást jelez single .

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

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

A következőkre vonatkozik: Paraméterek

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

A dinamikus értékek használata

Feljegyzé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 elérési út karakterlánc: property/childProperty.

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

  1. Használ x-ms-dynamic-values

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

    Feljegyzé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, amely nem egyértelmű a definícióból, mert nem egyértelmű, hogy a paraméterre vagy a requestBody/id tulajdonságrahivatkozik-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."
        }
    }
}

  2. x-ms-dynamic-list

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

    • parameters—Ez a tulajdonság egy olyan objektum, ahol a hívott dinamikus művelet minden bemeneti tulajdonsága statikus értékmezővel vagy a forrásművelet tulajdonságára mutató dinamikus hivatkozással van definiálva. Mindkét beállítást az alábbiakban definiáljuk.

    • value– Ez a bemeneti paraméterhez használandó konstans érték. A következő példában a művelet GetDynamicList nevű version nevű művelet bemeneti paramétere a 2.0 statikus értékkel van meghatározva.

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

    • parameterReference—Ez a teljes paraméterhivatkozási útvonal, amely a paraméter nevével kezdődik, majd a hivatkozni kívánt tulajdonság elérési útjának karakterláncával. A GetDynamicList nevű property1 művelet bemeneti tulajdonsága például, amely a destinationInputParam1 paraméteralatt található, dinamikus hivatkozásként van definiálva a sourceInputParam1 paraméter sourceInputParam1 nevűtulajdonságára . 

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

      Feljegyzés

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

      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 itemsPath nincs megadva, a válasz tömbként lesz kiértékelve.
      itemTitlePath Nem Az objektum belsejében itemsPath lévő elérésiút-sztring, amely az érték leírására hivatkozik.
      itemValuePath No A belső itemsPath objektum elérési útjának sztringje, amely az elem értékére hivatkozik.

      Használjon x-ms-dynamic-list paraméterhivatkozásokat a hivatkozott tulajdonság elérési útjának sztringjével. 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 azt mutatja, hogyan változik a beviteli űrlap a felhasználó által a listából kiválasztott elem alapján:

Az űrlap a felhasználó által kiválasztott beállítástól függően változik.

Ez a kép azt mutatja, hogyan változnak a kimenetek a felhasználó által a legördülő listából kiválasztott elem alapján. Ebben a verzióban a felhasználó az Autók lehetőséget választja:

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

Ebben a verzióban a felhasználó az Étel lehetőséget választja:

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

A dinamikus séma használata

Feljegyzé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 elérési út karakterlánc: property/childProperty.

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

  1. 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, a válasz feltételezhetően tartalmazza a sémát a gyökérobjektum tulajdonságaiban. 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"
      }
    }
  }

    Feljegyzé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ő meg a definícióból – függetlenül attól, hogy a paraméterobjektum-lekérdezésrevagy a sztringtulajdonság lekérdezésére/lekérdezésére 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őkről
    Összekötő Forgatókönyv Hivatkozás
    Jegykiadás Séma lekérése a kiválasztott esemény részleteihez Jegykiadás

  2. x-ms-dynamic-properties:

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

    • parameters—Ez a tulajdonság egy olyan objektum, ahol a hívott dinamikus művelet minden bemeneti tulajdonsága statikus értékmezővel vagy a forrásművelet tulajdonságára mutató dinamikus hivatkozással van definiálva. Mindkét beállítást az alábbiakban definiáljuk.

    • value– Ez a bemeneti paraméterhez használandó konstans érték. A következő példában a GetDynamicSchemanevű művelet bemeneti paramétere 2.0 statikus értékkelvan definiálva.

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

    • parameterReference—Ez a teljes paraméterhivatkozási útvonal, amely a paraméter nevével kezdődik, majd a hivatkozni kívánt tulajdonság elérési útjának karakterláncával. A GetDynamicSchema nevű property1 művelet bemeneti tulajdonsága például a sourceInputParam1 paraméteralatt van definiálva, dinamikus hivatkozásként van definiálva a sourceInputParam1 paraméter sourceInputParam1 nevűtulajdonságára . 

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

      Feljegyzés

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

      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, a válasz feltételezi, hogy tartalmazza a sémát a gyökérobjektumban. 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.

      x-ms-dynamic-propertiesA paraméterhivatkozások a hivatkozni kívánt tulajdonság elérési útjának sztringjével használhatók, mind a kulcshoz, mind a dinamikus műveleti paraméterhivatkozás értékéhez.

          {
    "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 elküldése vagy az összekötőkkel kapcsolatos segítség kérése elemre, és válassza ki a visszajelzés típusát.