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

paconn のコマンドラインツールは、Copilot Studio と 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) ことを検討してください。

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

カスタムコネクタは 2 つから 4 つのファイルで構成されます。

API/Swagger の定義を開きます
API プロパティファイル
コネクタのオプションのアイコン
オプションの csharp スクリプトファイル

ファイルは、ディレクトリ名にコネクタ ID が使用されているディレクトリに配置されています。

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

API 定義 (Swagger) ファイル

API 定義ファイルには、OpenAPI 仕様を使用したカスタムコネクタの API が記述されています (別名 swagger)。 API 定義ファイルを使用してカスタムコネクタを作成する方法の詳細については、OpenAPI 定義からカスタムコネクタを作成するにアクセスしてください。また、カスタムコネクタの OpenAPI 定義を拡張するの記事のチュートリアルも確認してください。

API プロパティファイル

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: 省略可能。カスタムコネクタで使用されるポリシーテンプレートのインスタンスと値の一覧。

アイコンファイル

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

スクリプトファイル

Visual C# スクリプト (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 文字列。 ダウンロードと更新の操作にはコネクタ ID パラメータが必要となりますが、作成と検証操作には必要ありません。作成コマンドは、新しい ID を持つ新しいカスタムコネクタを作成します。同じ設定ファイルを使用して既存のカスタムコネクタを更新する必要がある場合は、作成操作で取得した新しいコネクタ ID で設定ファイルを更新します。
environment: カスタムコネクタの環境 ID 文字列。検証操作を除くすべての操作には、このパラメータが必要です。
apiProperties: API プロパティファイルの相対パス。作成と更新操作には、API プロパティーファイルが必要です。ダウンロード時にこのオプションが選択されている場合、ファイルはその場所にダウンロードされます。それ以外の場合、ファイルは apiProperties.json という名前で保存されます。
apiDefinition: Swagger ファイルのパス。これは作成、更新、検証操作には、API 定義ファイルが必要です。ダウンロード操作時にこのオプションが選択されている場合、ファイルはその場所にダウンロードされます。それ以外の場合、ファイルは 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 が正しいことを、必ずもう一度確認してください。

制限

このプロジェクトは、Copilot Studio、Power Automate、Power Apps の環境におけるカスタムコネクタの作成、更新、ダウンロードに限定されています。環境が指定されていない場合、Power Automate 環境のみを選択できます。カスタムコネクタ以外の場合、Swagger ファイルは返されません。

注意

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

現在、API プロパティファイルに stackOwner プロパティが存在する場合、Paconn を使用して環境内のコネクタのアーティファクトを更新できないという制限があります。これを回避するには、コネクタアーティファクトの 2 つのバージョンを作成します。

stackOwner プロパティを含むバージョンを 1 つ作成し、認定のために送信します。
stackOwner を省略した 2 つ目のバージョンを作成して、ご利用の環境で更新できるようにします。

現在、制限の除去に取り組んでおり、完了するとこのセクションが更新されます。

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

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

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

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

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

Last updated on 2025-06-24

次の方法で共有

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

インストール

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

API 定義 (Swagger) ファイル

API プロパティ ファイル

アイコン ファイル

スクリプト ファイル

設定ファイル

コマンド ライン操作

ログイン