Vytvoření vlastního konektoru pomocí rozhraní příkazového řádku

Článek
04/24/2024

S vývojem vlastních konektorů platformy Microsoft Power Platform vám pomůže nástroj příkazového řádku paconn.

Poznámka

Tyto poznámky k verzi popisují funkce, které možná ještě nebyly vydané.
Informace o plánovaném vydání těchto funkcí najdete v novinkách a plánech pro Common Data Model a integraci dat.
Časové osy doručení a plánované funkce se můžou změnit, případně může dojít k úplnému zrušení vydání (viz Zásady společnosti Microsoft).

Instalace

Z webu [https://www.python.org/downloads](Python downloads) si nainstalujte Python 3.5 nebo novější. Vyberte odkaz Stáhnout u libovolné verze Pythonu vyšší než 3.5. Pokud používáte Linux nebo macOS X, přejděte na stránce na odpovídající odkaz. Instalaci můžete provést také pomocí libovolného správce balíčků pro váš operační systém.
Spuštěním instalačního programu zahajte instalaci a nezapomeňte zaškrtnout políčko Add Python X.X to PATH (Přidat Python X.X do proměnné PATH).
Spuštěním následujícího příkazu ověřte, že je instalační cesta v proměnné PATH:

python --version
Po dokončení instalace Pythonu spuštěním následujícího příkazu nainstalujte paconn:

pip install paconn

Pokud se zobrazí chybová zpráva „Přístup byl odepřen“, zvažte použití možnosti --user nebo spuštění příkazu jako správce (Windows).

Adresář a soubory vlastního konektoru

Vlastní konektor se skládá ze dvou až čtyř souborů: definice Open API Swaggeru, souboru vlastností rozhraní API, volitelné ikony konektoru a volitelného souboru skriptu csharp. Tyto soubory se obvykle nacházejí v adresáři, jehož názvem je ID konektoru.

Adresář vlastního konektoru někdy může obsahovat i soubor settings.json. I když tento soubor není součástí definice konektoru, může se použít jako úložiště argumentů pro rozhraní příkazového řádku.

Soubor definice rozhraní API (swagger)

Soubor definice rozhraní API popisuje rozhraní API pro vlastní konektor s využitím specifikace OpenAPI. Označuje se také jako soubor Swagger. Další informace o definicích API používaných k zápisu vlastního konektoru naleznete v tématu Vytvoření vlastního konektoru z definice OpenAPI. Podívejte se také na kurt v článku Rozšíření definice OpenAPI pro vlastní konektor.

Soubor vlastností rozhraní API

Soubor vlastností rozhraní API obsahuje některé vlastnosti pro vlastní konektor. Tyto vlastnosti nejsou součástí definice rozhraní API. Obsahují například informace o barvě značky, informace o ověřování atd. Typický soubor vlastností rozhraní API vypadá nějak jako tento příklad:

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

Další informace o jednotlivých vlastnostech najdete níže:

properties: Kontejner informací.
connectionParameters: Definice parametrů připojení pro službu.
iconBrandColor: Barva značky ikony vlastního konektoru v šestnáctkovém kódu HTML.
scriptOperations: Seznam operací, které jsou provedeny kódem ze souboru skriptu. Prázdný seznam scriptOperations říká, že všechny operace jsou prováděny kódem ze souboru skriptu.
capabilities: Popis funkcí konektoru, např. že je určený pouze pro cloud nebo je to místní brána atd.
policyTemplateInstances: Volitelný seznam instancí a hodnot šablon zásad použitých ve vlastním konektoru.

Soubor ikony

Soubor ikony je malý obrázek představující ikonu vlastního konektoru.

Soubor skriptu

Skript je soubor skriptu CSX, který je nasazen pro vlastní konektor a spuštěn pro každé volání podmnožiny operací konektoru.

Soubor nastavení

Místo zadávání argumentů na příkazovém řádku je možné k jejich zadání použít soubor settings.json. Typický soubor settings.json vypadá nějak jako tento příklad:

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

V souboru nastavení se očekávají následující položky. Pokud nějaká požadovaná možnost chybí, v konzole se zobrazí výzva k zadání chybějících informací.

connectorId: Řetězec ID vlastního konektoru. Tento parametr je vyžadován u operace stahování a aktualizace, ale ne u operace vytvoření nebo ověření. Pro příkaz vytvoření bude vytvořen nový vlastní konektor s novým ID. Pokud potřebujete aktualizovat vlastní konektor, který se právě vytvořil s použitím stejného souboru nastavení, nezapomeňte soubor nastavení aktualizovat tak, aby obsahoval správné ID nového konektoru z operace vytvoření.
environment: Řetězec ID prostředí vlastního konektoru. Tento parametr je vyžadován u všech operací kromě operace ověření.
apiProperties: Cesta k souboru vlastností apiProperties.json. Tento parametr je povinný u operací vytvoření a aktualizace. Pokud se tato možnost použije při stahování, soubor se stáhne do daného umístění; jinak bude uložen jako soubor apiProperties.json.
apiDefinition: Cesta k souboru Swagger. Tento parametr je povinný u operací vytvoření, aktualizace a ověření. Pokud se tato možnost použije při operaci stahování, soubor bude zapsán do daného umístění; jinak bude uložen jako soubor apiDefinition.swagger.json.
icon: Cesta k volitelnému souboru ikony. Pokud tento parametr není zadán, operace vytvoření a aktualizace budou používat výchozí ikonu. Pokud se tato možnost použije při operaci stahování, soubor bude zapsán do daného umístění; jinak bude uložen jako soubor icon.png.
script: Cesta k volitelnému souboru skriptu. Operace vytvoření a aktualizace budou používat pouze hodnotu uvnitř zadaného parametru. Pokud se tato možnost použije při operaci stahování, soubor bude zapsán do daného umístění; jinak bude uložen jako soubor script.csx.
powerAppsUrl: URL API pro Power Apps. Ve výchozím nastavení je tento parametr volitelný a je nastaven na https://api.powerapps.com.
powerAppsApiVersion: Verze API, kterou chcete použít pro Power Apps. Ve výchozím nastavení je tento parametr volitelný a je nastaven na 2016-11-01.

Operace příkazového řádku

Přihlaste se do Power Platform spuštěním:

paconn login

Tento příkaz vás vyzve k přihlášení kódem zařízení. Postupujte podle zobrazených pokynů a přihlaste se. Ověření instančním objektem není v tomto okamžiku podporováno.

Odhlášení

Odhlaste se spuštěním příkazu:

paconn logout

Stažení souborů vlastního konektoru

Soubory konektoru se vždy stáhnou do podadresáře, jehož názvem je ID konektoru. Pokud zadáte cílový adresář, tento podadresář se vytvoří v zadaném adresáři. Jinak se vytvoří v aktuálním adresáři. Kromě tří souborů konektoru operace stažení zapíše také čtvrtý soubor settings.json obsahující parametry použité ke stažení souborů.

Soubory vlastního konektoru můžete stáhnout spuštěním následujících příkazů:

paconn download

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

paconn download -s [Path to settings.json]

Pokud nezadáte ID prostředí nebo ID konektoru, příkaz vás vyzve k zadání chybějících argumentů. Pokud se konektor úspěšně stáhne, příkaz na výstupu zobrazí umístění stažených souborů.

Všechny argumenty je možné zadat také pomocí souboru settings.json.

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.

Vytvoření nového vlastního konektoru

Nový vlastní konektor lze vytvořit ze souborů konektorů spuštěním operace create. Konektor můžete vytvořit spuštěním následujících příkazů:

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

nebo

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]

nebo

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

Pokud nezadáte ID prostředí, příkaz vás vyzve k jeho zadání. V rámci argumentu příkazového řádku nebo souboru nastavení je však potřeba zadat definici rozhraní API a soubor rozhraní API. Pro konektory využívající OAuth2 je potřeba zadat tajný klíč OAuth2. Příkaz po úspěšném dokončení vytváření konektoru na výstupu zobrazí ID nově vytvořeného vlastního konektoru. Pokud pro příkaz create používáte soubor settings.json, před aktualizací nově vytvořeného konektoru nezapomeňte tento soubor aktualizovat tak, aby obsahoval ID nového konektoru.

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.

Aktualizace existujícího vlastního konektoru

Obdobně jako u operace create lze existující vlastní konektor aktualizovat pomocí operace update. Konektor můžete aktualizovat spuštěním následujících příkazů:

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

nebo

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]

nebo

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

Pokud nezadáte ID prostředí nebo ID konektoru, příkaz vás vyzve k zadání chybějících argumentů. V rámci argumentu příkazového řádku nebo souboru nastavení je však potřeba zadat definici rozhraní API a soubor rozhraní API. Pro konektory využívající OAuth2 je potřeba zadat tajný klíč OAuth2. Příkaz po úspěšném dokončení aktualizace na výstupu zobrazí ID aktualizovaného konektoru. Pokud pro příkaz update používáte soubor settings.json, ujistěte se, že obsahuje správná ID prostředí a konektoru.

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.

Ověření souboru JSON Swaggeru

Operace ověření vezme soubor Swaggeru a ověří, zda dodržuje všechna doporučená pravidla. Soubor swagger ověřte spuštěním příkazu:

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

nebo

paconn validate -s [Path to settings.json]

Příkaz vytiskne zprávu o chybě, varování nebo úspěšném dokončení v závislosti na výsledku ověření.

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.

Osvědčené postupy

Stáhněte si všechny vlastní konektory a k uložení souborů použijte git nebo jakýkoli jiný systém správy zdrojového kódu. V případě nesprávné aktualizace nasaďte konektor znovu opětovným spuštěním příkazu update se správnou sadou souborů ze systému správy zdrojového kódu.

Před nasazením vlastního konektoru a souboru nastavení do produkčního prostředí je otestujte v testovacím prostředí. Vždy pečlivě zkontrolujte správnost ID prostředí a konektoru.

Omezení

Tento projekt umožňuje vytvoření, aktualizaci a stažení vlastního konektoru pouze v prostředí Power Automate a Power Apps. Pokud prostředí nezadáte, budete mít na výběr pouze prostředí Power Automate. Jiné než vlastní konektory nevrací soubor Swagger.

Vlastnost stackOwner a soubor apiProperties

V současné době existuje omezení, které vám brání aktualizovat artefakty konektoru ve vašem prostředí pomocí Paconn, když se v souboru apiProperties.json nachází vlastnost stackOwner. Problém se dá vyřešit vytvořením dvou verzí artefaktů konektoru: první je verze, která byla předložena k certifikaci a obsahuje vlastnost stackOwner. Druhý má vlastnost stackOwner vynechánu, aby ji bylo možné aktualizovat ve vašem prostředí. Na odstranění omezení pracujeme a po dokončení tuto sekci aktualizujeme.

Hlášení problémů a názory

Pokud v nástroji narazíte na jakékoli chyby, nahlaste problém v části Issues (Problémy) našeho úložiště GitHub.

Pokud si myslíte, že jste našli ohrožení zabezpečení, které odpovídá definici Microsoftu pro ohrožení zabezpečení, odešlete zprávu do střediska MSRC. Další informace najdete v nejčastějších dotazech k oznamování ve středisku MSRC.

Poskytnutí názorů

Velmi si vážíme vašich názorů na problémy s naší platformou konektorů nebo nových nápadů na funkce. Chcete-li poskytnout zpětnou vazbu, přejděte do části Odeslat problémy nebo získat pomoc s konektory a vyberte typ zpětné vazby.

Sdílet prostřednictvím

Vytvoření vlastního konektoru pomocí rozhraní příkazového řádku

Instalace

Adresář a soubory vlastního konektoru

Soubor definice rozhraní API (swagger)

Soubor vlastností rozhraní API

Soubor ikony

Soubor skriptu

Soubor nastavení

Operace příkazového řádku

Odhlášení

Stažení souborů vlastního konektoru

Vytvoření nového vlastního konektoru

Aktualizace existujícího vlastního konektoru

Ověření souboru JSON Swaggeru

Osvědčené postupy

Omezení

Hlášení problémů a názory

Poskytnutí názorů

Další materiály

Sdílet prostřednictvím

Vytvoření vlastního konektoru pomocí rozhraní příkazového řádku

Instalace

Adresář a soubory vlastního konektoru

Soubor definice rozhraní API (swagger)

Soubor vlastností rozhraní API

Soubor ikony

Soubor skriptu

Soubor nastavení

Operace příkazového řádku

Přihlášení

Odhlášení

Stažení souborů vlastního konektoru

Vytvoření nového vlastního konektoru

Aktualizace existujícího vlastního konektoru

Ověření souboru JSON Swaggeru

Osvědčené postupy

Omezení

Hlášení problémů a názory

Poskytnutí názorů

Další materiály