使用 Microsoft Power Platform 连接器 CLI

已完成

并非自定义连接器生命周期中的每项任务均可使用制作者门户中的自定义连接器用户界面来执行。 应在自定义连接器生命周期中使用paconn命令行工具执行以下任务:

  • 使用 Maker Portal 创建或编辑自定义连接器后,可下载该连接器进行编辑和源代码管理。 例如,要添加自定义连接属性,您必须下载并编辑文件。

  • 在单个下载定义文件环境中新建自定义连接器。 创建的连接器不包含在解决方案中。 例如,如需副本并且同时保持原连接器不变,可以使用本连接器在相同环境下创建具有不同唯一 ID 的相同连接器。

  • 更新现有连接器。 本步骤可用于更新独立自定义连接器或解决方案中包含的连接器。 例如,您可在编辑连接属性后更新连接器。

  • 验证连接器。 本步骤是认证的必要步骤,检测到的许多错误可以提高自定义连接器的质量。

务必确保其他人未同时使用门户和下载文件编辑自定义连接器,以免更改丢失。 使用命令行工具上传时不检查冲突,仅替换现有定义而不进行合并。

安装命令行工具

paconn命令行工具需要使用 Python 3.5 或更高版本。 应先安装 Python,然后按pip install paconn命令安装工具。 详细安装说明可供使用。

设置文件或参数

您可在运行命令时使用命令行参数,或使用 settings.json 文件配置工具选项。 使用-settings-s parameter 可指定设置文件。 使用设置文件时,忽略其他命令行参数。

使用设置文件可以轻松多次运行命令。 下载自定义连接器时,将在下载过程中创建 settings.json 文件。 以下屏幕截图展示 settings.json 文件示例。

您可以查看详细设置列表了解有关各设置值的详细信息。

身份验证

要使用 paconn 命令,您必须先使用paconn 登录命令进行身份验证。 本命令将为您提供代码并引导您访问 https://microsoft.com/devicelogin,您将在此处使用帐户登录并提供该代码。

完成交互式登录将建立其他 paconn 命令使用的会话。 会话将在一段时间后过期,您需要重新建立会话才能继续使用工具。 您可以随时使用 paconn logout 命令强制结束会话。

由于需要通过交互式用户登录进行身份验证,因此命令行工具可以配合有人参与的自动化脚本使用,但无法在构建管道等无人参与的场景中使用。

下载

使用 paconn download 命令下载现有连接器。 如未提供参数,系统将提示您在环境列表中进行选择,然后在所选环境中的连接器列表中进行选择。

使用-e 参数预选特定环境并跳过环境列表。 获取环境标识符的最简单方法是从制作者门户 URL 获取。

使用本选项将仅显示环境中的可选连接器。

您可以通过-c 参数传递连接器标识符来指定特定连接器,替代交互式选择连接器。 获取连接器标识符的最简单方法是下载连接器,然后从设置文件中复制该值。

因此,您的命令将类似于以下示例:

paconn download -e d80faec4-eb14-4076-9681-9b46b97adbfd -c shared_cr83e-5fcontoso-20invoicing-5f20493607d490e1e0

本命令将下载连接器文件,而不给出提示。

使用标识符的另一项优势在于标识符不同于选择列表中的订单编号,不会在创建或删除环境和连接器时更改。

下载的文件放置在使用连接器 ID命名的文件夹中。 如果目录已存在,命令将失败,您必须手动删除文件夹。 下载的文件包括以下四个文件:

  • apiDefinition.swagger.json - 本 API 定义文件使用 OpenAPI 规范描述自定义连接器的 API。

  • apiProperties.json - API 属性文件包含自定义连接器和策略模板的属性。

  • Icon.png - 图标文件是代表自定义连接器图标的小图像。

  • settings.json - 您可以使用该预配置设置文件代替向各命令提供参数。

创建

paconn 创建命令将使用指定的定义文件在目标环境中创建自定义连接器。 必须通过参数或设置文件指定 API 定义、API 属性和图标。 如未提供参数,创建命令将提示您提供环境 ID 等其他参数。 以下示例展示创建命令:

paconn create ^
  -e [Microsoft 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]

如果连接器使用 OAuth2,您可以使用-secret 参数指定客户端密码值。

更新

paconn 更新命令使用指定的定义文件在目标环境中更新现有自定义连接器。 必须通过参数或设置文件指定 API 定义、API 属性和图标。 如未提供参数,更新命令将提示环境 ID 等其他参数。 以下示例展示更新命令:

paconn update ^
  -e [Microsoft 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]

重要提示

即便已下载副本完成修改,更新仍将替换目标环境中的定义。 务必与正在更新连接器的其他人员进行协调。

Microsoft Power Platform 连接器 CLI 是构建自定义连接器时的必要工具。 在生命周期中使用本工具帮助更改连接器,以及下载用于源代码管理的连接器定义文件副本。