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

[アーティクル]
04/24/2024

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

注意

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

インストール

[https://www.python.org/downloads](Python downloads) から Python 3.5 以降をインストールします。 Python 3.5 以降のバージョンの Python のダウンロード リンクを選択します。 Linux と macOS X については、そのページの適切なリンクに従います。 OS 固有の任意のパッケージマネージャーを使用してインストールすることもできます。
インストーラーを実行してインストールを開始し、「Python X.X を PATH に追加する」チェックボックスをオンにします。
以下を実行して、インストールパスが PATH 変数に含まれていることを確認します。

python --version
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

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

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 によく寄せられる報告に関する質問を参照してください。

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

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

次の方法で共有

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

インストール

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

API 定義 (Swagger) ファイル

API プロパティファイル

アイコンファイル

スクリプトファイル

設定ファイル

コマンドライン操作

ログアウト

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

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

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

Swagger JSON を検証する

ベストプラクティス

制限

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

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

その他のリソース

次の方法で共有

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

インストール

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

API 定義 (Swagger) ファイル

API プロパティ ファイル

アイコン ファイル

スクリプト ファイル

設定ファイル

コマンド ライン操作

ログイン

ログアウト

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

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

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

Swagger JSON を検証する

ベスト プラクティス

制限

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

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

その他のリソース

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

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

API プロパティファイル

アイコンファイル

スクリプトファイル

コマンドライン操作

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

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

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

ベストプラクティス