使用 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) 執行該命令。

自訂連接器目錄和檔案

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

開放 API/swagger 定義
API 屬性檔案
連接器的可選圖示
可選的 csharp 命令碼檔案

這些檔案位於以連接器 ID 作為目錄名稱的目錄中。

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

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 十六進位碼中的圖示品牌色彩。
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 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 或任何其他原始檔控制系統來儲存檔案。如果更新不正確，請藉由使用來自原始檔控制系統中的一組正確檔案重新執行 update 命令，以重新部署連接器。

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

限制

此專案僅限於在 Copilot Studio、Power Automate 和 Power Apps 環境中建立、更新和下載自訂連接器。當未指定環境時，您只能選擇一個 Power Automate 環境。對非自訂連接器，不會傳回 Swagger 檔案。

注意

stackOwner 屬性和 API 屬性檔案

目前，當您的 API 屬性檔案中存在 stackOwner 屬性時，就會有一個限制，阻止您使用 Paconn 更新環境中的連接器成品。為解決此問題，請建立兩個版本的連接器成品：

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

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

回報問題與意見反應

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

如果您認為您發現符合 Microsoft 的資訊安全漏洞定義的資訊安全漏洞，請將報告提交給 MSRC。如需詳細資訊，請參閱 MSRC 報告的常見問題集。

提供意見反應

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

Last updated on 2025-06-25

共用方式為