从头开始创建自定义连接器

  • 项目

本文是有关在 Azure 逻辑应用、Microsoft Power Automate 和 Microsoft Power Apps 中创建与使用自定义连接器的系列教程的一部分。

备注

请务必阅读自定义连接器概述来了解整个流程。

若要创建自定义连接器，必须描述要连接到的 API，使连接器可识别此 API 的操作和数据结构。 在本主题中，您从头开始创建自定义连接器，而不使用 OpenAPI 定义来描述 Azure 认知服务文本分析 API 情绪操作（我们在此系列的示例）。 而是完全在自定义连接器向导中说明连接器。

有关描述 API 的另一种方式，请转到从 OpenAPI 定义创建自定义连接器。

备注

您当前可以在 Power Automate 和 Power Apps 中从头创建自定义连接器。 对于逻辑应用，您必须至少从基本的 OpenAPI 定义开始。

先决条件

启动自定义连接器向导

  1. 登录到 Power Apps 或 Power Automate。

  2. 在左侧窗格中，选择数据 > 自定义连接器。

  3. 选择新建自定义连接器 > 从空白创建。

  4. 输入自定义连接器的名称，然后选择继续。

    参数 价值
    自定义连接器标题 SentimentDemo

步骤 1：更新一般详细信息

从现在起，我们将演示 Power Automate UI，但在不同技术中执行的步骤大致相同。 我们将指出各个不同之处。

在常规选项卡上，执行以下操作：

  1. 在描述字段中，输入一个有意义的值。 此说明将显示在自定义连接器的详细信息中，可帮助其他用户确定连接器对他们是否有用。

  2. 将主机字段更新为文本分析 API 的地址。 连接器使用 API 主机和基 URL 来确定如何调用 API。

    参数 价值
    说明 使用 Cognitive Services 文本分析情绪 API 来确定文本是积极的还是消极的
    Host westus.api.cognitive.microsoft.com

步骤 2：指定身份验证类型

有多个选项可用于自定义连接器中的身份验证。 认知服务 API 使用 API 密钥身份验证，这就是您为本教程指定的内容。

  1. 在安全性选项卡上的身份验证类型下，选择 API 密钥。

  2. 在 API 密钥下，指定参数标签、名称和位置。 指定一个有意义的标签，因为当某人首次与自定义连接器建立连接时，将显示该标签。 参数名称和位置必须与 API 预期的匹配。 选择连接。

    参数 价值
    参数标签 API 密钥
    参数名称 Ocp-Apim-Subscription-Key
    参数位置 标头

  3. 在向导顶部，请确保名称设置为 SentimentDemo，然后选择创建连接器。

步骤 3：创建连接器定义

自定义连接器向导为您提供了很多选项，用于定义连接器的功能以及它在逻辑应用、流和应用中的公开方式。 我们将在本节中对 UI 加以说明并介绍几个选项，不过我们也鼓励您自己进行探索。

创建操作

首先要创建一个调用文本分析 API 情绪操作的操作。

  1. 在定义选项卡上，左侧窗格显示针对连接器定义的所有操作、触发器（适用于逻辑应用和 Power Automate）和引用。 选择新建操作。

    此连接器中没有触发器。 要了解自定义连接器的触发器，请转到对 Azure 逻辑应用和 Power Automate 使用 Webhook。

  2. 常规区域显示有关当前所选操作或触发器的信息。 为此操作添加摘要、说明和操作 ID。

    参数 价值
    总结 返回表示检测到的情绪的数字评分
    说明 API 返回介于 0 和 1 之间的数字评分。 接近 1 的评分表示积极情绪，而接近 0 的评分表示消极情绪。
    操作 ID DetectSentiment

    保留可见性属性的设置为无。 逻辑应用或流中的操作和参数的这个属性包含以下选项：

    • 无：通常在逻辑应用或流中显示
    • 高级：隐藏在另一个菜单下
    • 内部：向用户隐藏
    • 重要：始终先向用户显示

  3. 请求区域基于对操作的 HTTP 请求显示信息。 选择从示例导入。

  4. 指定连接到 API 所需的信息，指定请求正文（在下图后面提供），然后选择导入。 我们会为您提供此信息，但对于公共 API，您通常会从文本分析 API (v2.0) 等文档获取此信息。

    参数 价值
    谓词 POST
    URL <https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
    Body 使用以下 JSON 代码

    示例:

    {
  "documents": [
    {
      "language": "string",
      "id": "string",
      "text": "string"
    }
  ]
}

  5. 响应区域基于对操作的 HTTP 响应显示信息。 选择添加默认响应。

  6. 指定响应正文，然后选择导入。 正如我们对请求正文所做的那样，我们会在图像之后为您提供此信息，但通常在 API 文档中提供。

    示例:

    {
 "documents": [
   {
     "score": 0.0,
     "id": "string"
   }
 ],
 "errors": [
   {
     "id": "string",
     "message": "string"
   }
 ]
}

  7. 验证区域显示在 API 定义中检测到的任何问题。 检查状态，然后在向导的右上角选择更新连接器。

更新定义

现在让我们更改几项设置，使连接器变得更友好，方便用户在逻辑应用、流或应用中使用它。

  1. 在请求区域中，选择正文，然后选择编辑。

  2. 在参数区域中，现在可以看到 API 预期的三个参数：id、language 和 text。 选择 id，然后选择编辑。

  3. 在架构属性区域中更新参数的值，然后选择返回。

    参数 价值
    称谓 ID
    说明 提交的每个文档的标识符
    Default value 1
    必需 是

  4. 在参数区域中，选择语言 > 编辑，然后使用以下值重复此过程的步骤 2 和步骤 3 中用于 id 的过程。

    参数 价值
    称谓 语言
    说明 文本的两个或四个字符的语言代码
    Default value en
    必需 是

  5. 在参数区域中，选择文本 > 编辑，然后使用以下值重复此过程的步骤 2 和步骤 3 中用于 id 的过程。

    参数 值
    标题 文本
    说明 用于分析情绪的文本
    默认值 无
    必需 是

  6. 在参数区域，选择返回将带您返回主定义选项卡。

  7. 在向导的右上角，选择更新连接器。

步骤 4：（可选）启用连接器作为 AI 插件

仅当您计划认证连接器时，才针对连接器使用 AI 插件(预览版) 选项卡。 若要将连接器用作 AI 插件，连接器必须经过认证。

在启用连接器作为 AI 插件之前，请确保您了解 AI 插件场景的用例，并已查看其他注意事项，例如可支持性、最佳做法和建议。 详细信息：创建连接器 AI 插件（预览版）

  1. 在左侧导航窗格上，选择自定义连接器。

    如果您没有看到自定义连接器，请选择更多 > 发现所有 > 自定义连接器。 该选项将显示在左侧导航窗格上。

  2. 在右上角，从新建自定义连接器菜单中选择一个选项。

  3. 确保您已完成本文中的步骤 1、步骤 2 和步骤 3。

  4. 选择 AI 插件(预览版) 选项卡。

  5. 在插件清单部分中，输入详细信息以启用此连接器作为 AI 插件。

    “插件清单”页面上的字段的屏幕截图。

    字段 Description
    插件清单：名称 AI 插件的名称。
    插件清单：说明 AI 插件的说明。 详细信息：创建连接器 AI 插件（预览版）
    插件清单：联系人电子邮件 此 AI 插件的联系人的电子邮件地址。
    插件清单：法律信息 URL 一个可公开访问的位置，其中发布与您的 AI 插件相关的法律信息。

  6. 向下滚动到插件操作详细信息部分，然后输入连接器 AI 插件中每个操作的操作详细信息。

    “插件操作详细信息”页面上的字段的屏幕截图。

    字段 Description
    插件操作详细信息：摘要 有关用户可以执行的每个 AI 插件操作的摘要。
    插件操作详细信息：说明 用户可以针对此特定 AI 插件操作步骤执行的每个操作的说明。
    复选框：启用作为 Copilot 插件操作 当复选框中出现复选标记时，表示 AI 插件操作已启用。
    复选框：需要用户确认吗？ 当复选框中出现复选标记时，需要用户确认。

    提示

    如果您需要帮助定义操作，请打开 Swagger 编辑器开关。

  7. 向下滚动到参数部分，然后输入连接器 AI 插件的参数详细信息。

    “参数”页面上的字段的屏幕截图。

    字段 Description
    参数：名称 参数的名称。 使用可识别的名称，例如帐户标识符，而不是 ID。
    参数：说明 参数的说明。 使用描述性解释，例如采用 MM/DD/YYYY 格式的联系人的出生日期，而不是 b_date。 此类名称和说明有助于 LLM（大型语言模型）与 AI 插件有效交互。
    参数：摘要 有关参数的摘要信息。
    参数：默认值 参数的默认值。

  8. 在 AI 插件(预览版) 部分下的请求部分中，选择输入参数，然后输入说明。

步骤 5：（可选）使用自定义代码支持

自定义代码转换超出现有策略模板范围的请求和响应有效负载。 转换包括发送外部请求以提取其他数据。 使用代码时，它优先于无代码定义。 这意味着代码将执行，我们不会将请求发送到后端。

备注

  • 此步骤是可选的。 您可以通过忽略此步骤然后转到步骤 6：测试连接器来完成创建连接器的无代码体验。
  • 自定义代码支持在公开预览中提供。

您可以粘贴代码或上载包含代码的文件。 您的代码必须：

  • 用 C# 编写。
  • 最长执行时间为五秒。
  • 文件大小不超过 1 MB。

有关编写代码的说明和示例，请转到在自定义连接器中编写代码。

有关自定义代码的常见问题，请转到自定义代码常见问题。

  1. 在代码选项卡上，使用下列选项之一插入自定义代码：

    • 复制/粘贴
    • 选择上载按钮。

    如果您选择上载自定义代码，则只能使用扩展名为 .cs 或 .csx 的文件。

    “上载自定义代码”的屏幕截图。

    重要

    目前，我们仅支持在代码编辑器中突出显示语法。 请务必在本地测试您的代码。

  2. 粘贴或上载代码后，选择已禁用代码旁边的切换启用代码。 切换名称将更改为已启用代码。

    您可以随时启用或禁用您的代码。 如果切换是已禁用代码，您的代码将被删除。

  3. 通过在下拉菜单中选择一个选项，选择要应用于自定义代码的操作和触发器。 如果未选择任何操作，操作和触发器将应用于所有操作。

    “选择操作和触发器”的屏幕截图。

步骤 6：测试连接器

创建连接器后，请对其进行测试，以确保其正常工作。 测试当前仅在 Power Automate 和 Power Apps 中可用。

重要

在使用 API 密钥时，不建议您在创建连接器后立即对其进行测试。 连接器准备好连接到 API 可能需要几分钟。

  1. 在测试选项卡上，选择新建连接。

  2. 输入文本分析 API 中的 API 密钥，然后选择创建连接。

    备注

    对于需要持有者身份验证的 API，在 API 密钥之前添加持有者和一个空格。

  3. 返回到测试选项卡，执行下列操作之一：

    • （在 Power Automate 中）您将返回到测试选项卡。选择刷新图标确保连接信息完成更新。

      刷新连接的屏幕截图。

    • （在 Power Apps 中）您将会转到当前环境中的可用连接列表。 在左侧窗格中，选择数据 > 自定义连接器。 选择创建的连接器，然后返回到测试选项卡。

  4. 在测试选项卡上，为文本字段输入一个值（其他字段使用您之前设置的默认值），然后选择测试操作。

  5. 连接器调用 API，您可以查看响应，其中包括情绪分数。

    连接器响应的屏幕截图。

（对于 CLI 用户）最佳实践

  • 下载所有连接器，并使用 Git 或任何源代码管理系统保存文件。

  • 如果有不正确的更新，请使用源代码管理中的正确文件集重新运行更新命令，以重新部署连接器。

  • 在生产环境中部署之前，请在测试环境中测试自定义连接器和设置文件。

  • 请务必仔细检查环境和连接器 ID 是否正确。

后续步骤

创建自定义连接器并定义其行为后，您可以从以下位置使用连接器：

还可以在组织中共享连接器或认证连接器，使组织外部的人员也可以使用它。

提供反馈

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