通过

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

备注

本文是有关在 Azure 逻辑应用中创建和使用自定义连接器、Microsoft Power Automate 和 Microsoft Power Apps 以及 调用连接器作为 Microsoft Copilot Studio 中的工具的教程系列教程的一部分。 请务必阅读自定义连接器概述来了解整个流程。

若要创建自定义连接器，必须定义要连接到的 API，以便连接器了解 API 的作和数据结构。 在本文中，您将从头开始创建自定义连接器，而无需使用 OpenAPI 定义 格式来描述 Azure 认知服务文本分析 API 情感操作（本系列的示例）。 而是在自定义连接器向导中完全定义连接器。

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

备注

  • 从 Power Automate 或 Power Apps 开始，当前可以从头开始创建自定义连接器。 对于逻辑应用，必须至少从 OpenAPI 2.0 （以前称为 Swagger）格式的基本 OpenAPI 定义开始。 不支持采用 OpenAPI 3.0 格式的 OpenAPI 定义。

  • 文档、定义和说明的使用在 OpenAPI 规范中不断发展。 你可能会看到术语、定义和说明在本文中可以互换使用。

先决条件

启动自定义连接器向导

  1. 登录到 Power Apps 或 Power Automate。

  2. 在左侧窗格中选择解决方案。

  3. 编辑或创建自定义连接器的非托管解决方案。 了解如何创建解决方案。

  4. 选择“ 新建自定义连接器 ”下拉列表，然后选择 “从空白创建”。

  5. 输入 连接器名称，例如 SentimentDemo。 选择 “继续 ”打开连接器向导，可在其中完成 Power Automate 中的这五个部分：

    • 概况

    • 安全性

    • Definition

    • 代码（可选）

    • 测试

      Power Automate 中连接器向导的屏幕截图。

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

在常规部分中，您提供连接器信息，例如图标、说明、方案、主机和基础 URL。 采取以下步骤：

  1. 在图标框中选择上传连接器图标或上传，以上传连接器图标的 PNG 或 JPG。 请确保它小于 1MB。 还可以为图标指定背景色。

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

  3. 选择连接器的 URL 方案，HTTPs 或 HTTP。

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

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

  5. 更新 基本 URL，这是对特定服务的所有 API 调用的起点。

  6. 选择底部 的“安全性 ”，转到下一部分。

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

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

  1. 在 “安全 ”部分的“身份验证类型”下，从下拉列表中选择 API 密钥 。

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

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

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

  4. 选择底部 的定义 ，转到下一部分。

步骤 3：创建连接器定义

自定义连接器向导提供了许多用于描述连接器功能方式的选项，以及它在逻辑应用、流、应用和代理中的公开方式。 可以定义动作、触发器、引用和策略。 我们将在本部分中对 UI 加以说明并介绍几个选项，不过我们也鼓励您自己进行探索。

创建操作

首先要创建一个调用文本分析 API 情绪操作的操作。 在定义选项卡上，左侧窗格显示为连接器定义的任何操作、触发器（适用于逻辑应用、Power Automate 和 Copilot Studio）、引用和策略。

备注

此连接器中没有触发器。 要了解自定义连接器的触发器，请转到使用 webhook 作为 Azure Logic Apps 和 Power Automate 的触发器。

  1. 选择新建操作。

  2. 在常规区域中，为该操作添加摘要、描述和操作 ID。

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

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

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

  3. 在请求区域中选择从示例导入。

  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. 在响应区域中，选择添加默认响应。

  6. 指定响应正文，然后选择导入。 与请求正文类似，我们为您提供了此信息，但通常在 API 文档中提供。

    示例:

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

    验证区域显示在 API 定义中检测到的任何问题。

  7. 修复任何问题。 定义验证成功后，您应该会看到一个绿色复选标记。

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

更新定义

让我们修改一些设置，以便连接器在 Logic Apps、Power Automate、Power Apps 或 Copilot Studio 中使用时更加友好。

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

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

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

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

  4. 在参数区域中，选择语言>编辑，然后重复您用于 id 的操作，添加以下 language 值：

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

  5. 在参数区域中，选择文本>编辑，然后重复您用于 id 和 language 的操作，添加以下 text 值：

    参数 价值
    称谓 文本
    说明 用于分析情绪的文本
    默认值 None
    必需 是

  6. 在参数区域中，选择返回以返回主定义选项卡。

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

  8. 选择底部 的代码 ，转到下一部分。

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

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

备注

  • 此步骤是可选的。 您可以通过忽略此步骤然后转到步骤 5：测试连接器来完成创建连接器的无代码体验。

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

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

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

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

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

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

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

    “代码”部分中的“上传自定义代码”的屏幕截图。

    重要提示

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

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

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

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

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

步骤 5：测试连接器

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

重要提示

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

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

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

    备注

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

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

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

      刷新连接的屏幕截图。

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

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

    连接器调用 API。

  5. 查看响应，其中包括情感评分。

    连接器响应的屏幕截图。

CLI 用户的最佳实践

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

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

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

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

后续步骤

创建自定义连接器并定义其行为后，即可使用通过以下方式使用连接器：

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

提供反馈

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

  • Last updated on