使用 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”复选框。
运行以下命令，确保安装路径在 PATH 变量中：

python --version
安装完 Python 后，运行以下命令以安装 paconn：

pip install paconn

如果您收到显示“访问被拒绝”的错误，请考虑使用 --user 选项或以管理员身份运行命令 (Windows)。

自定义连接器目录和文件

自定义连接器由两到四个文件组成：Open API swagger 定义、API 属性文件、连接器的可选图标和可选的 csharp 脚本文件。这些文件通常位于将连接器 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：自定义连接器中使用的策略模板实例和值的可选列表。

图标文件

图标文件是表示自定义连接器图标的小图像。

脚本文件

脚本是为自定义连接器部署的 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：自定义连接器的环境 ID 字符串。除验证操作外，所有操作都需要此参数。
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

下载自定义连接器文件

连接器文件始终下载到将连接器 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 是否正确。

限制

在 Power Automate 和 Power Apps 环境中，该项目仅支持创建、更新和下载自定义连接器。如果未指定环境，系统只会列出 Power Automate 环境供你选择。对于非自定义连接器，不返回 Swagger 文件。

stackOwner 属性和 apiProperties 文件

目前，当 apiProperties.json 文件中存在 stackOwner 属性时，有一个限制阻止您使用 Paconn 在您的环境中更新连接器的项目。解决此问题的方法是，创建两个版本的连接器项目：第一个是提交给认证的包含 stackOwner 属性的版本。第二个省略 stackOwner 属性以在您的环境中启用更新。我们正在努力消除限制，完成后将更新此节内容。

报告问题和反馈

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

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

提供反馈

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

通过