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

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

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

先决条件

• 认知服务文本分析 API 的 API 密钥

• 以下订阅之一：

  • Power Automate
  • Power Apps

启动自定义连接器向导

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 情绪操作的操作。 在定义选项卡中，左侧窗格会显示为该连接器定义的任何操作、触发器（针对 Logic Apps，Power Automate 和 Copilot Studio）以及引用。

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
   说明	提交的每个文档的标识符
   Default value	1
   必需	是

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

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

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

   参数	价值
   称谓	文本
   Description	用于分析情绪的文本
   Default value	None
   必需	可以

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

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

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

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

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

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

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

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

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

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

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

   

   重要提示

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

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

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

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

   

步骤 5：测试连接器

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

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

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

   备注

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

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

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

     

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

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

   连接器调用 API。

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

   

CLI 用户的最佳实践

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

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

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

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

后续步骤

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

• Power Automate
• Power Apps
• 逻辑应用程序
• Copilot Studio

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

• 共享连接器
• 认证连接器

提供反馈

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