Egyéni összekötő létrehozása a CLI használatával

Cikk
06/27/2024

A paconn parancssori eszköz úgy lett kialakítva, hogy segítse a Microsoft Power Platform egyéni összekötőinek fejlesztését.

Megjegyzés

Ezek a kibocsátási megjegyzések olyan funkciókat ismertetnek, amelyek esetleg még nem jelentek meg.
Ha meg szeretné tudni, hogy mikor tervezik kiadni ezt a funkciót, tekintse meg a Common Data Model és az adatintegráció újdonságait és terveit.
A kézbesítési határidők és a tervezett funkciók változhatnak vagy nem szállíthatók (lásd a Microsoft szabályzatát).

Telepítés

Telepítse a Python 3.5+ -ot [https://www.python.org/downloads](Python downloads). Válassza a Letöltés csatolás lehetőséget a Python 3.5-nél nagyobb Python bármely verzióján. Linux és macOS X rendszeren kövesse a weboldal megfelelő hivatkozását. Ezenkívül tetszés szerinti rendszerspecifikus csomagkezelőt is használhat a telepítéshez.
A telepítés megkezdéséhez futtassa a telepítőt, és győződjön meg arról, hogy az „Add Python X.X to PATH” (A Python X.X hozzáadása a PATH változóhoz) jelölőnégyzet be van jelölve.
Győződjön meg arról, hogy a telepítési útvonal szerepel a PATH változóban. Ehhez futtassa a következőt:

python --version
A Python telepítése után végezze el a paconn telepítését a következő parancs futtatásával:

pip install paconn

Ha hibaüzenetet kap, amely szerint "A hozzáférés megtagadva", fontolja meg az --user opció használatát vagy a parancs rendszergazdaként való futtatását (Windows).

Egyéni összekötők könyvtára és fájljai

Az egyéni összekötő két-négy fájlból áll: egy Open API-hencegő definícióból, egy API-tulajdonságfájlból, az összekötő opcionális ikonjából és egy opcionális csharp szkriptfájlból. A fájlok általában a könyvtár neveként az összekötő azonosítóját használó könyvtárban találhatók meg.

Bizonyos esetekben az egyéni összekötő könyvtára egy settings.json fájlt is tartalmazhat. Bár ez a fájl nem része az összekötő definíciójának, használható a parancssori felület argumentumtárolójaként.

API-definíciós (hencegő) fájl

Az API-definíciós fájl a specifikációt használó OpenAPI egyéni összekötő API-ját írja le. Ez Swagger-fájl néven is ismert. További információ az egyéni összekötők írásához használt API-definíciókról: Egyéni összekötő létrehozása definícióból OpenAPI. Tekintse át az oktatóanyagot is az Egyéni összekötő OpenAPI definíciójának kiterjesztése cikkben.

API-tulajdonságok fájlja

Az API tulajdonságfájlja az egyéni összekötő bizonyos tulajdonságait tartalmazza. Ezek a tulajdonságok nem képezik az API-definíció részét. Olyan információkat tartalmaz, mint például a márka színe, a hitelesítési adatok stb. Egy API tipikus tulajdonságfájlja a következő mintához hasonlóan néz ki:

{
  "properties": {
    "capabilities": [],
    "connectionParameters": {
      "api_key": {
        "type": "securestring",
        "uiDefinition": {
          "constraints": {
            "clearText": false,
            "required": "true",
            "tabIndex": 2
          },
          "description": "The KEY for this API",
          "displayName": "KEY",
          "tooltip": "Provide your KEY"
        }
      }
    },
    "iconBrandColor": "#007EE6",
    "scriptOperations": [
        "getCall",
        "postCall",
        "putCall"
    ],
    "policyTemplateInstances": [
      {
        "title": "MyPolicy",
        "templateId": "setqueryparameter",
        "parameters": {
            "x-ms-apimTemplateParameter.name": "queryParameterName",
            "x-ms-apimTemplateParameter.value": "queryParameterValue",
            "x-ms-apimTemplateParameter.existsAction": "override"
        }
      }
    ]    
  }
}

Az egyes tulajdonságokkal kapcsolatos információk alább olvashatók:

properties: Az információ tárolója.
connectionParameters: Meghatározza a szolgáltatás kapcsolati paraméterét.
iconBrandColor: Az egyéni összekötőhöz tartozó ikon márkaszíne hexadecimális HTML-kódban megadva.
scriptOperations: A parancsfájllal végrehajtott műveletek listája. Az üres scriptOperations lista azt jelzi, hogy minden művelet a parancsfájllal van végrehajtva.
capabilities: Ismerteti az összekötő képességeit, például csak felhő, helyszíni átjáró stb.
policyTemplateInstances: Egy opcionális lista az egyéni összekötőben használt szabályzatsablon-példányokkal és értékekkel.

Ikon fájl

Az ikonfájl az egyéni összekötő ikonját jelképező kis méretű kép.

Parancsfájl

A szkript egy CSX-szkriptfájl, amely az egyéni összekötőhöz van telepítve, és az összekötő műveleteinek egy részkészletének minden hívásakor végrehajtásra kerül.

Beállítások fájl

Ahelyett, hogy az argumentumokat a parancssorban adná meg, használhatja a settings.json fájlt azok megadásához. Egy tipikus settings.json fájl a következő mintához hasonlóan néz ki:

{
  "connectorId": "CONNECTOR-ID",
  "environment": "ENVIRONMENT-GUID",
  "apiProperties": "apiProperties.json",
  "apiDefinition": "apiDefinition.swagger.json",
  "icon": "icon.png",
  "script": "script.csx",
  "powerAppsApiVersion": "2016-11-01",
  "powerAppsUrl": "https://api.powerapps.com"
}

A beállításfájlban az alábbi elemek szerepelhetnek. Ha hiányzik egy beállítás, de szükség van rá, a konzol kérni fogja a hiányzó információkat.

connectorId: Az egyéni összekötő kapcsolati azonosítósztringje. Ez a paraméter szükséges a letöltési és frissítési műveletekhez, de nem szükséges a létrehozási vagy érvényesítési művelethez. A rendszer létrehoz egy új egyéni összekötőt az új azonosítóval a create parancshoz. Ha az imént létrehozott egyéni összekötőt ugyanazzal a beállításfájllal szeretné frissíteni, győződjön meg arról, hogy a beállításfájl megfelelően frissült a létrehozási műveletből származó új összekötő-azonosítóval.
environment: Az egyéni összekötő környezeti azonosítósztringje. Ez a paraméter az érvényesítési művelet kivételével minden művelethez szükséges.
apiProperties: Az API tulajdonságait tartalmazó apiProperties.json fájl elérési útja. A létrehozási és frissítési műveletekhez szükséges. Ha ez az opció jelen van a letöltés során, a fájl letöltésre kerül az adott helyre; ellenkező esetben mentésre apiProperties.json kerül.
apiDefinition: A Swagger-fájl elérési útja. A létrehozási, frissítési és érvényesítési műveletekhez szükséges. Ha ez az opció jelen van a letöltési művelet során, akkor az adott helyen lévő fájl íródik; ellenkező esetben mentésre apiDefinition.swagger.json kerül.
icon: Az opcionális ikonfájl elérési útja. A létrehozási és frissítési műveletek az alapértelmezett ikont fogják használni, ha ez a paraméter nincs megadva. Ha ez az opció jelen van a letöltési művelet során, akkor az adott helyen lévő fájl íródik; ellenkező esetben mentésre icon.png kerül.
script: Az opcionális parancsfájl elérési útja. A létrehozási és frissítési műveletek csak a megadott paraméteren belüli értéket fogják használni. Ha ez az opció jelen van a letöltési művelet során, akkor az adott helyen lévő fájl íródik; ellenkező esetben mentésre script.csx kerül.
powerAppsUrl: A Power Apps API URL-címe. Ez a paraméter nem kötelező, és alapértelmezés szerint be https://api.powerapps.com van állítva.
powerAppsApiVersion: A Power Apps-hoz használandó API-verzió. Ez a paraméter nem kötelező, és alapértelmezés szerint be 2016-11-01 van állítva.

Parancssori műveletek

Jelentkezzen be a a Power Platform felületre a következő futtatásával:

paconn login

Ez a parancs arra kéri, hogy jelentkezzen be az eszköz kódjának bejelentkezési folyamatával. Kövesse a bejelentkezési utasításokat. Az egyszerű szolgáltatásalapú hitelesítés jelenleg nem támogatott.

Kijelentkezés

Kijelentkezés a következő futtatásával:

paconn logout

Egyéni összekötőfájlok letöltése

Az összekötőfájlokat a rendszer mindig egy alkönyvtárba tölti le, a könyvtár neve pedig az összekötő-azonosító lesz. Ha meg van adva a célkönyvtár, az alkönyvtár a megadott könyvtáron belül jön létre. Egyéb esetben az aktuális könyvtárban jön létre. A három összekötőfájlon kívül a letöltési művelet egy settings.json nevű negyedik fájlba is írni fog, amely a fájlok letöltéséhez használt paramétereket tartalmazza.

Töltse le az egyéni összekötő fájljait a következő parancsok egyikének futtatásával:

paconn download

paconn download -e [Power Platform Environment GUID] -c [Connector ID]

paconn download -s [Path to settings.json]

Ha nincs megadva a környezeti vagy összekötő-azonosító, a parancs kérni fogja a hiányzó argumentumo(ka)t. Sikeres letöltés esetén a fenti parancs kimenete tartalmazza az összekötő letöltési helyét.

Az argumentumok ezen kívül egy settings.json fájl használatával is megadhatók.

Arguments
   --cid -c       : The custom connector ID.
   --dest -d      : Destination directory.
   --env -e       : Power Platform environment GUID.
   --overwrite -w : Overwrite all the existing connector and settings files.
   --pau -u       : Power Platform URL.
   --pav -v       : Power Platform API version.
   --settings -s  : A settings file containing required parameters.
                    When a settings file is specified some command 
                    line parameters are ignored.

Új egyéni összekötő létrehozása

A művelet futtatásával create új egyéni összekötő hozható létre az összekötőfájlokból. Összekötőt az alábbi parancsok egyikének futtatásával hozhat létre:

paconn create --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json]

paconn create -e [Power Platform Environment GUID] --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json] --icon [Path to icon.png] --secret [The OAuth2 client secret for the connector]

paconn create -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Ha a környezet nincs megadva, a parancs kérni fogja azt. Az API-definíciót és az API-tulajdonságokat tartalmazó fájlt azonban a parancssori argumentum vagy egy beállításfájl részeként kell megadni. Az OAuth2 titkos kódot az OAuth2-t használó összekötők esetén meg kell adni. A parancs a sikeres befejezéskor kiírja az újonnan létrehozott egyéni összekötő összekötő-azonosítóját. Ha settings.json-fájlt használ a create parancshoz, az újonnan létrehozott összekötő frissítése előtt frissítse azt az új összekötő-azonosítóval.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --api-prop    : Location for the API properties JSON document.
   --env -e      : Power Platform environment GUID.
   --icon        : Location for the icon file.
   --script -x   : Location for the script file.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --secret -r   : The OAuth2 client secret for the connector.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Meglévő egyéni összekötő frissítése

A művelethez hasonlóan egy create meglévő egyéni összekötő is frissíthető a update művelettel. Összekötőt az alábbi parancsok egyikének futtatásával frissíthet:

paconn update --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json]

paconn update -e [Power Platform Environment GUID] -c [Connector ID] --api-prop [Path to apiProperties.json] --api-def [Path to apiDefinition.swagger.json] --icon [Path to icon.png] --secret [The OAuth2 client secret for the connector]

paconn update -s [Path to settings.json] --secret [The OAuth2 client secret for the connector]

Ha nincs megadva környezeti vagy összekötő-azonosító, a parancs kérni fogja a hiányzó argumentumo(ka)t. Az API-definíciós és API-tulajdonságfájlt azonban meg kell adni a parancssori argumentum vagy egy beállításfájl részeként. Az OAuth2 titkos kódot az OAuth2-t használó összekötők esetén meg kell adni. A parancs a sikeres befejezéskor kiírja a frissített összekötő-azonosítót. Ha settings.json fájlt használ a frissítési parancshoz, győződjön meg arról, hogy a megfelelő környezet és összekötő-azonosító van megadva.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --api-prop    : Location for the API properties JSON document.
   --cid -c      : The custom connector ID.
   --env -e      : Power Platform environment GUID.
   --icon        : Location for the icon file.
   --script -x   : Location for the script file.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --secret -r   : The OAuth2 client secret for the connector.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Hencegő JSON ellenőrzése

Az érvényesítési művelet egy hencegő fájlt vesz fel, és ellenőrzi, hogy követi-e az összes ajánlott szabályt. Swagger-fájl érvényesítéséhez futtassa a következőt:

paconn validate --api-def [Path to apiDefinition.swagger.json]

paconn validate -s [Path to settings.json]

A parancs az érvényesítés eredményétől függően kinyomtatja a hibát, figyelmeztetést vagy sikeres üzenetet.

Arguments
   --api-def     : Location for the Open API definition JSON document.
   --pau -u      : Power Platform URL.
   --pav -v      : Power Platform API version.
   --settings -s : A settings file containing required parameters.
                   When a settings file is specified some command 
                   line parameters are ignored.

Ajánlott eljárások

Töltse le az összes egyéni összekötőt, és használja a Gitet vagy bármely más verziókövető rendszert a fájlok mentéséhez. Ha helytelen frissítés történik, telepítse újra az összekötőt úgy, hogy újrafuttatja az update parancsot a verziókövetési rendszer megfelelő fájlkészletével.

Az éles környezetben történő üzembe helyezés előtt tesztelje az egyéni összekötőt és a beállításfájlt egy tesztkörnyezetben. Mindig ellenőrizze, hogy a környezeti és az összekötő-azonosító helyes-e.

Korlátozások

A projekt a Power Automate- és Power Apps-környezetekben az egyéni összekötők létrehozására, frissítésére és letöltésére van korlátozva. Ha a környezet nincs megadva, csak a listában megjelenő Power Automate-környezetek közül választhat. A nem egyéni összekötők esetében a rendszer nem adja vissza a Swagger-fájlt.

stackOwner tulajdonság és apiProperties fájl

Jelenleg van egy korlátozás, amely megakadályozza, hogy frissítse az összekötő összetevőit a környezetben a Paconn használatával, ha a stackOwner tulajdonság jelen van a apiProperties.json fájlban. Ennek áthidaló megoldásaként hozza létre az összekötő-összetevők két verzióját: Az első a tanúsítványra elküldött verzió, amely tartalmazza a stackOwner tulajdonságot. A másodikban a stackOwner tulajdonság nincs megadva, hogy engedélyezze a frissítést a környezeten belül. Dolgozunk a korlátozás megszüntetésén, és amint elkészült, frissítjük ezt a szakaszt.

Problémák jelentése és visszajelzés

Ha bármilyen hibát észlel az eszközzel, küldjön be egy problémát a GitHub-adattár Problémák szakaszában.

Ha úgy véli, hogy olyan biztonsági rést talált, amely megfelel a Microsoft biztonsági rés definíciójának, küldjön jelentést az MSRC címre. További információt itt találhat: Az MSRC-jelentésekkel kapcsolatos gyakori kérdések.

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 a CLI használatával

Telepítés

Egyéni összekötők könyvtára és fájljai

API-definíciós (hencegő) fájl

API-tulajdonságok fájlja

Ikon fájl

Parancsfájl

Beállítások fájl

Parancssori műveletek

Kijelentkezés

Egyéni összekötőfájlok letöltése

Új egyéni összekötő létrehozása

Meglévő egyéni összekötő frissítése

Hencegő JSON ellenőrzése

Ajánlott eljárások

Korlátozások

Problémák jelentése és visszajelzé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 a CLI használatával

Telepítés

Egyéni összekötők könyvtára és fájljai

API-definíciós (hencegő) fájl

API-tulajdonságok fájlja

Ikon fájl

Parancsfájl

Beállítások fájl

Parancssori műveletek

Bejelentkezés

Kijelentkezés

Egyéni összekötőfájlok letöltése

Új egyéni összekötő létrehozása

Meglévő egyéni összekötő frissítése

Hencegő JSON ellenőrzése

Ajánlott eljárások

Korlátozások

Problémák jelentése és visszajelzés

Visszajelzés küldése

További források