使用 CLI 创建自定义连接器

2025-06-24

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)。

自定义连接器目录和文件

自定义连接器由两个到四个文件组成：

Open API/Swagger 定义
API 属性文件
连接器的可选图标
可选的 csharp 脚本文件

这些文件位于将连接器 ID 用作目录名称的目录中。

有时，自定义连接器目录中包含一个 settings.json 文件。尽管此文件不是连接器定义的一部分，但您可以将其用作 CLI 的参数存储。

API 定义 (Swagger) 文件

API 定义文件使用 OpenAPI 规范（即 Swagger 文件）描述自定义连接器的 API。有关 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# 脚本 (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 作为目录名的子目录中。当指定目标目录时，会在指定目录下创建子目录。否则，会在当前目录下创建。除了三个连接器文件外，下载操作还将写入第四个名为 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。如果对创建命令使用的是 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 在您的环境中更新连接器的项目。为此，请创建连接器项目的两个版本：

创建一个包含 stackOwner 属性的版本并提交认证。
创建第二个省略 stackOwner 的版本，以便您在自有环境中进行更新。

我们正在努力消除限制，完成后将更新此节内容。

报告问题和反馈

如果遇到该工具的任何 bug，请在 GitHub 存储库的问题部分中提交问题。

如果你认为自己发现的安全漏洞符合 Microsoft 对安全漏洞的定义，请将报告提交给 MSRC。有关详细信息，请参阅 MSRC 关于报告的常见问题解答。

提供反馈

我们非常感谢大家提出有关连接器平台问题或新功能想法的反馈。要提供反馈，请转到提交问题或获取连接器帮助，然后选择反馈类型。

通过