使用 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 變數中：

python --version
安裝 python 之後，請執行下列命令來安裝 paconn：

pip install paconn

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

自訂連接器目錄和檔案

自訂連接器由兩到四個檔案組成：Open API Swagger 定義、API 屬性檔、連接器的選擇性圖示，以及選擇性的 csharp 指令檔。這些檔案通常位於使用連接器識別碼作為目錄名稱的目錄中。

有時候，自訂連接器目錄可能會包含 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：自訂連接器中所使用原則範本執行個體和值的選擇性清單。

圖示檔案

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

指令檔

該指令碼是為自訂連接器部署的 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：自訂連接器的連接器識別碼字串。這是下載和更新作業所需的參數，但建立或驗證作業不需要此參數。將為建立命令建立具有新識別碼的新自訂連接器。如果您需要使用相同設定檔案更新剛剛建立的自訂連接器，請確定用建立作業的新連接器識別碼正確地更新設定檔案。
environment：自訂連接器的環境識別碼字串。除了驗證作業之外，所有作業都需要此參數。
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

下載自訂連接器檔案

連接器檔案一律會下載到具有連接器識別碼作為目錄名稱的子目錄中。當指定目的地目錄時，將會在指定處建立子目錄。否則，會在目前的目錄中建立。除了三個連接器檔案之外，下載作業也會寫入名為 settings.json 的第四個檔案，其中包含用來下載檔案的參數。

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

paconn download

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

paconn download -s [Path to settings.json]

未指定環境或連接器識別碼時，命令會提示您輸入遺漏的引數。如果成功下載，此命令會輸出連接器的下載位置。

您也可以使用 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 祕密。此命令會列印成功完成的新建立自訂連接器的連接器識別碼。如果您針對 create 命令使用 settings.json 檔案，請務必在更新新建立的連接器之前，以新的連接器識別碼更新它。

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]

未指定環境或連接器識別碼時，命令會提示您輸入遺漏的引數。不過，必須在命令列引數或設定檔案中提供 API 定義和 API 屬性檔案。使用 OAuth2 的連接器必須取得 OAuth2 祕密。此命令會列印已成功完成的更新連接器識別碼。如果您針對 update 命令使用 settings.json 檔案，請確認已指定正確的環境和連接器識別碼。

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 命令，以重新部署連接器。

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

限制

此專案僅限於在 Power Automate 和 Power Apps 環境中建立、更新及下載自訂連接器。未指定環境時，只有 Power Automate 環境會被列出作為選擇。對非自訂連接器，不會傳回 Swagger 檔案。

stackOwner 屬性和 apiProperties 檔案

目前，當 apiProperties.json 文件中存在 stackOwner 屬性時，有一個限制會阻止您使用 Paconn 在環境中更新連接器的成品。若要解決此問題，請建立兩個版本的連接器成品：第一個是提交給認證的版本，包含 stackOwner 屬性。第二個是省略 stackOwner 屬性，以在您的環境中進行更新。我們正在努力消除限制，並將在完成之後更新此區段。

回報問題與意見反應

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

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

提供意見反應

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

共用方式為