Microsoft Power PlatformCsatlakozók CLI-címe

  • Cikk

Megjegyzés

Ezek a kibocsátási megjegyzések olyan funkciókat írnak le, 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ágai és tervei című témakört. A szállítási határidők és a tervezett funkciók változhatnak, vagy előfordulhat, hogy nem szállítják ki (a Microsoft szabályzatát).

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

Telepítés folyamatban

  1. Telepítse a Python 3.5+ from címet [https://www.python.org/downloads](Python downloads). Válassza a Letöltés hivatkozást a Python bármely Python 3.5-nél nagyobb 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.

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

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

  4. 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 a "Hozzáférés megtagadva" hibaüzenetet kap, fontolja meg az --user opció használatát vagy a parancs rendszergazdaként (Windows) történő futtatását.

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

Az egyéni összekötők két-négy fájlból állnak: egy Open API swagger-definícióból, egy API-tulajdonságfájlból, egy opcionális ikonból az összekötőhöz é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.

Az API definíciós (Swagger-) fájlja

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

Az API tulajdonságfá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 az összes művelet végrehajtása a parancsfájllal történik.

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

Ikonfá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ére irányuló minden híváshoz végrehajtva van.

Beállításfá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 a létrehozási vagy érvényesítési művelethez nem. 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ó a letöltés során jelen van, a fájl letöltésre kerül az adott helyre; különben 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; különben mentésre apiDefinition.swagger.json kerül.

  • icon: A választható 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; különben mentésre icon.png kerül.

  • script: A választható 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; különben 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 a következőre 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 a következőre 2016-11-01 van állítva.

Parancssori műveletek

Bejelentkezés

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ésre vonatkozó utasításokat. A szolgáltatáselv-alapú hitelesítés jelenleg nem támogatott.

Kijelentkezés

Kijelentkezés futtatással:

paconn logout

Egyéni összekötő fájljainak 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

or

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

or

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ők fájljaibó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]

or

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]

or

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ágfá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 egy 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 create művelethez hasonlóan egy 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]

or

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]

or

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ót és az API-tulajdonságfá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 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.

Swagger JSON ellenőrzése

Az érvényesítési művelet egy swagger-fájlt vesz fel, és ellenőrzi, hogy megfelel-e az összes ajánlott szabálynak. Ellenőrizze a swagger-fájlt a következő futtatásával:

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

or

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.

Gyakorlati tanácsok

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 a frissítés, telepítse újra az összekötőt úgy, hogy újrafuttatja az update parancsot a forrásvezérlő 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.

Veremtulajdonos tulajdonsága & 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 tulajdonság jelen van a stackOwner apiProperties.json fájlban. Ennek megkerülő megoldásaként hozza létre az összekötő-összetevők két verzióját: Az első a tanúsítványra beküldött verzió, amely tartalmazza a stackOwner tulajdonságot. A másodikból ki van hagyva a tulajdonság, amely lehetővé teszi a frissítést a stackOwner környezetében. 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ába ütközik az eszközzel kapcsolatban, küldjön be egy problémát a GitHub-adattár Problémák szakaszában.

Ha úgy gondolja, hogy olyan biztonsági rést talált, amely megfelel a Microsoft biztonsági résre vonatkozó definíciójának, küldjön jelentést az MSRC webhelynek. 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.