CLI でカスタム コネクタを作成する

paconn コマンド ライン ツールは、Microsoft Power Platform カスタム コネクタの開発を支援するように設計されています。

注意

  • これらのリリース ノートでは、まだリリースされていない可能性のある機能について説明します。
  • この機能のリリースがいつ予定されているかを確認するには、Common Data Model とデータ統合の新機能と予定されている機能に移動してください。
  • 配信タイムラインと予定されている機能は、変更されることがあります。また、出荷されない可能性もあります (Microsoft ポリシーを参照)。

インストール

  1. [https://www.python.org/downloads](Python downloads) から Python 3.5 以降をインストールします。 Python 3.5 以降のバージョンの Python のダウンロード リンクを選択します。 Linux と macOS X については、そのページの適切なリンクに従います。 OS 固有の任意のパッケージ マネージャーを使用してインストールすることもできます。

  2. インストーラーを実行してインストールを開始し、「Python X.X を PATH に追加する」 チェック ボックスをオンにします。

  3. 以下を実行して、インストール パスが PATH 変数に含まれていることを確認します。

    python --version

  4. Python のインストール後、以下を実行して paconn をインストールします。

    pip install paconn

    「アクセスが拒否されました」というエラーが表示された場合、--user オプションを使用するか、コマンドを管理者として実行する (Windows) ことを検討してください。

カスタム コネクタのディレクトリとファイル

カスタム コネクタは、Open API Swagger 定義、API プロパティ ファイル、コネクタのオプション アイコン、およびオプションの csharp スクリプト ファイルのうち、2 〜 4 つのファイルで構成されます。 ファイルは、通常、ディレクトリ名にコネクタ ID が使用されているディレクトリに配置されています。

カスタム コネクタのディレクトリに settings.json ファイルが含まれていることがあります。 このファイルはコネクタ定義には含まれませんが、CLI の argument-store として使用できます。

API 定義 (Swagger) ファイル

API 定義ファイルには、OpenAPI 仕様を使用したカスタム コネクタの API が記述されています。 これは Swagger ファイルとも呼ばれます。 カスタム コネクタの作成に使用される API 定義の詳細については、次の URL にアクセスしてください。OpenAPI 定義からカスタム コネクタを作成するに移動してください。 また、カスタム コネクタの OpenAPI 定義を拡張するの記事のチュートリアルも確認してください。

API プロパティ ファイル

API プロパティ ファイルには、カスタム コネクタのプロパティがいくつか含まれています。 これらのプロパティは API 定義には含まれません。 これには、ブランドの色、認証情報などの情報が含まれます。 一般的な API プロパティ ファイルは次のサンプルのようになります。

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

各プロパティの詳細については、以下を参照してください。

  • properties: 情報のコンテナー。

  • connectionParameters: サービスの接続パラメーターを定義します。

  • iconBrandColor: カスタム コネクタ用 HTML 16 進コードのアイコン ブランドの色。

  • scriptOperations: スクリプト ファイルで実行される操作のリスト。 空の scriptOperations リストは、すべての操作がスクリプト ファイルで実行されることを示します。

  • capabilities: コネクタの機能 (クラウドのみ、オンプレミス ゲートウェイなど) を説明します。

  • policyTemplateInstances: 省略可能。カスタム コネクタで使用されるポリシー テンプレートのインスタンスと値の一覧。

アイコン ファイル

アイコン ファイルは、カスタム コネクタ アイコンを表す小さな画像です。

スクリプト ファイル

スクリプトは、カスタム コネクタ用にデプロイされ、コネクタの操作のサブセットへのすべての呼び出しに対して実行される CSX スクリプト ファイルです。

設定ファイル

コマンド ラインで引数を指定するのではなく settings.json ファイルを使用することができます。 一般的な settings.json ファイルは次のサンプルのようになります。

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

設定ファイルで予想される項目を次に示します。 必要なオプションが指定されていない場合は、不足している情報の入力を求めるメッセージが表示されます。

  • connectorId: カスタム コネクタのコネクタ ID 文字列。 このパラメーターは、ダウンロードおよび更新操作には必要ですが、作成または検証操作には必要ありません。 create コマンド用に、新しい ID を持つ新しいカスタム コネクタが作成されます。 同じ設定ファイルを使用して作成されたカスタム コネクタを更新する必要がある場合は、設定ファイルが、作成操作の新しいコネクタ ID で正しく更新されていることを確認します。

  • environment: カスタム コネクタの環境 ID 文字列。 このパラメーターは、検証操作を除くすべての操作に必要です。

  • apiProperties: API プロパティ apiProperties.json ファイルの相対パス。 これは作成および更新操作に必要です。 ダウンロード中にこのオプションが存在すると、ファイルは指定した場所にダウンロードされます。それ以外の場合は、apiProperties.json として保存されます。

  • apiDefinition: Swagger ファイルのパス。 これは作成、更新、および検証操作に必要です。 ダウンロード操作中にこのオプションが存在すると、指定した場所のファイルに書き込まれます。それ以外の場合は、apiDefinition.swagger.json として保存されます。

  • icon: オプション アイコン ファイルのパス。 このパラメーターが指定されていない場合、作成および更新操作はデフォルトのアイコンを使用します。 ダウンロード操作中にこのオプションが存在すると、指定した場所のファイルに書き込まれます。それ以外の場合は、icon.png として保存されます。

  • script: オプション スクリプト ファイルのパス。 作成および更新操作は、指定されたパラメーター内の値のみ使用します。 ダウンロード操作中にこのオプションが存在すると、指定した場所のファイルに書き込まれます。それ以外の場合は、script.csx として保存されます。

  • powerAppsUrl: Power Apps の API URL。 既定では、この値はオプションであり、https://api.powerapps.com に設定されます。

  • powerAppsApiVersion: Power Apps で使用する API バージョン。 既定では、この値はオプションであり、2016-11-01 に設定されます。

コマンド ライン操作

ログイン

次を実行して、Power Platform にログインします。

paconn login

このコマンドにより、デバイス コードのログイン プロセスを使用してログインするように求められます。 ログインを求めるプロンプトに従います。 現時点では、サービス プリンシパル認証はサポートされていません。

ログアウト

以下を実行してログアウトします。

paconn logout

カスタム コネクタ ファイルのダウンロード

コネクタ ファイルは、必ずディレクトリ名にコネクタ ID が使用されているサブディレクトリにダウンロードされます。 ターゲット ディレクトリが指定されている場合、サブディレクトリは、指定されたディレクトリに作成されます。 それ以外の場合は、現在のディレクトリに作成されます。 ダウンロード操作により、3 つのコネクタ ファイルのほか、settings. json という 4 番目のファイルも書き込まれます。このファイルには、ファイルのダウンロードに使用されるパラメーターが含まれています。

以下を実行して、カスタム コネクタ ファイルをダウンロードします。

paconn download

or

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

or

paconn download -s [Path to settings.json]

環境またはコネクタ ID が指定されていない場合、不足している引数の入力を求められます。 ダウンロードが正常に行われると、コマンドによってコネクタのダウンロード先が出力されます。

すべての引数を settings.json file を使用して指定することもできます。

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.

新しいカスタム コネクタの作成

新しいカスタム コネクタは、コネクタ ファイルから create 操作を実行して作成できます。 以下を実行して、コネクタを作成します。

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]

環境が指定されていない場合は、コマンドによって入力が求められます。 ただし、API 定義および API プロパティ ファイルは、コマンド ライン引数または設定ファイルの一部として指定する必要があります。 OAuth2 を使用するコネクタについては、OAuth2 シークレットを指定する必要があります。 正常に完了すると、コマンドは新しく作成されたカスタム コネクタのコネクタ ID を出力します。 作成コマンドに settings.json ファイルを使用している場合は、必ず新しいコネクタ ID でそれを更新してから、新しく作成されたコネクタを更新してください。

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.

既存のカスタム コネクタの更新

create 操作では、update 操作を使用して既存のカスタム コネクタ更新できます。 以下を実行して、コネクタを更新します。

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]

環境またはコネクタ ID が指定されていない場合、不足している引数の入力を求められます。 ただし、API 定義および API プロパティ ファイルは、コマンド ライン引数または設定ファイルの一部として指定する必要があります。 OAuth2 を使用するコネクタについては、OAuth2 シークレットを指定する必要があります。 正常に完了すると、コマンドは更新されたコネクタ ID を出力します。 更新コマンドに settings.json ファイルを使用している場合は、正しい環境とコネクタ ID が指定されていることを確認します。

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 を検証する

検証操作は、Swagger ファイルを受け取り、推奨されるすべてのルールに従っているかどうかを検証します。 次のコマンドを実行して、Swagger ファイルを検証します。

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

または

paconn validate -s [Path to settings.json]

このコマンドは、検証の結果に応じて、エラー、警告、または成功のメッセージを出力します。

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.

ベスト プラクティス

すべてのカスタム コネクタをダウンロードし、git またはその他のソース管理システムを使用してファイルを保存します。 正しくない更新プログラムがある場合は、ソース管理システムから正しいファイル セットを使用して更新コマンドを再実行し、コネクタを再デプロイします。

運用環境にデプロイする前に、テスト環境でカスタム コネクタと設定ファイルをテストします。 環境とコネクタ ID が正しいことを、必ずもう一度確認してください。

制限

このプロジェクトは、Power Automate および Power Apps 環境でのカスタム コネクタの作成、更新、およびダウンロードに制限されています。 環境が指定されていない場合は、選択対象の一覧に Power Automate 環境だけが表示されます。 カスタム コネクタ以外の場合、Swagger ファイルは返されません。

stackOwner プロパティと apiProperties ファイル

現在のところ、stackOwner プロパティが apiProperties.json ファイルに存在する場合に、Paconn を使用して環境内のコネクタのアーティファクトを更新できない原因となっている制限があります。 これを回避するには、コネクタ アーティファクトの 2 つのバージョンを作成します。1 つ目は、証明書に送信され、stackOwner プロパティを含むバージョンです。 2 つ目は、環境内での更新を有効にするために stackOwner プロパティが省略されているバージョンです。 現在、制限の除去に取り組んでおり、完了するとこのセクションが更新されます。

問題の報告とフィードバック

ツールにバグを発見した場合は、GitHub リポジトリの Issues セクションで問題を送信してください。

Microsoft のセキュリティ脆弱性の定義 を満たすセキュリティの脆弱性が見つかったと思われる場合は、MSRC に報告 してください。 詳細については、MSRC によく寄せられる報告に関する質問 を参照してください。

フィードバックを提供する

コネクタ プラットフォームの問題点や新機能のアイデアなどのフィードバックをお待ちしています。 フィードバックを提供するには、「問題を送信するか、コネクタに関するヘルプを入手する」にアクセスし、フィードバックの種類を選択します。