使用 CLI 建立自訂連接器

paconn命令列工具能幫助你為 Copilot Studio 和 Power Platform 建立自訂連接器。

注意

這項功能可能還不會釋出。
欲了解發布資訊，請參閱 Common Data Model 與 Data Integration 的新功能與規劃。
交付時程和預期功能可能會變動，甚至可能不會推出。更多資訊請參見 Microsoft 政策）。

安裝 Python 和 paconn

從 [https://www.python.org/downloads]（Python 下載）安裝 Python 3.5 或更新版本。選擇任何高於 Python 3.5 版本的 Python 的下載連結。對於 Linux 和 macOS，請使用頁面上的適當連結。你也可以使用你選擇的作業系統專用套件管理器來安裝 Python。
執行安裝程式開始安裝，並勾選「Add Python X.X to PATH」這個選項。
請執行以下操作，確保安裝路徑位於 PATH 變數 中：

python --version
安裝 Python 後，請執行以下操作安裝paconn：

pip install paconn

如果出現提示存取遭拒的錯誤，請考慮使用 --user 選項或以管理員身分 (Windows) 執行該命令。

自訂連接器目錄和檔案

自訂連接器由兩到四個檔案組成：

Open API 或 Swagger 定義
API 屬性檔案
連接器的可選圖示
一個可選的 C# 腳本檔案

你可以在一個以連接器 ID 作為名稱的目錄中找到這些檔案。

有時，自訂連接器目錄包含一個 settings.json 檔案。雖然這個檔案不是連接器定義的一部分，但你可以用它作為 CLI 的參數儲存庫。

API 定義（Swagger）檔案

API 定義檔透過 OpenAPI 規範描述了自訂連接器的 API。此規範也被稱為 Swagger 檔案。欲了解更多關於 API 定義檔案如何幫助你建立自訂連接器的資訊，請參見「從 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 十六進位碼）。
scriptOperations：由命令碼檔案執行的作業清單。空的 scriptOperations 清單表示所有操作都與指令碼檔案一起執行。
capabilities：連接器功能描述，例如僅限雲端及內部部署閘道。
policyTemplateInstances：自訂連接器使用的原則範本執行個體和值的選用清單。

圖示檔案

圖示檔案是代表自訂連接器圖示的小型影像。

腳本檔

Visual C# Script (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 來更新設定檔。
environment：自訂連接器的環境識別碼字串。除驗證外，所有作業都需要此參數。
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 作為目錄名稱的子目錄中。當你指定目的地目錄時，這個目錄就會成為新子目錄的父目錄。如果你沒有指定目的地目錄，子目錄會建立在目前的目錄中。除了三個連接器檔案外，下載操作還會產生第四個檔案，稱為 settings.json 此檔案，包含下載檔案所需的參數。

執行下列命令，下載自訂連接器檔案：

paconn download

或

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

或

paconn download -s [Path to settings.json]

如果你沒指定環境或連接器 ID，指令會提示你輸入缺少的參數。若下載成功，指令會輸出連接程式的下載位置。

你也可以用 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.

建立新的自訂連接器

你可以透過執行這個 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。如果你使用的是 create 指令的 settings.json 檔案，務必先用新的 connector ID 更新它，再更新新建立的 connector。

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 或其他原始碼控制系統來儲存檔案。如果更新不正確，請藉由使用來自版本控制系統中的一組正確檔案重新執行 update 命令，以重新部署連接器。

請先在測試環境中測試自訂連接器和設定檔案，然後再在生產環境中進行部署。每次都請再次檢查環境和連接器識別碼是否正確。

限制

paconn CLI 僅限於在 Copilot Studio、Power Automate 及 Power Apps 環境中建立、更新及下載自訂連接器。當你沒有指定環境時，你只能選擇 Power Automate 環境。對非自訂連接器，不會傳回 Swagger 檔案。

注意

stackOwner 屬性和 API 屬性檔案

目前有一個限制，當您的 API 屬性檔中存在 stackOwner 屬性時，會導致您無法使用 Paconn 更新您環境中的連接器成品。作為一個變通方法，可以建立兩個版本的連接器成品：

建立一個包含 stackOwner 屬性的版本並提交進行認證。
建立省略 stackOwner 的第二個版本，以便您在自己的環境中進行更新。

我們正在努力消除限制，並將在完成之後更新此區段。

回報問題與意見反應

如果您遇到任何與工具有關的錯誤，請在 GitHub 存放庫的問題一節中提出問題。

如果你認為自己發現了符合 Microsoft 安全漏洞定義的安全漏洞，請向 MSRC 提交報告。欲了解更多資訊，請參閱 MSRC 回報相關常見問題。

提供意見反應

非常感謝您提供有關連接器平台問題，或新功能構想的意見反應。若要提供意見反應，請移至提交問題或取得連接器說明，然後選取您的意見反應類型。

上次更新時間： 2026-10-31