从 OpenAPI 定义创建自定义连接器

项目
04/19/2024

备注

本主题是有关在 Azure 逻辑应用、Microsoft Power Automate 和 Microsoft Power Apps 中创建与使用自定义连接器的系列教程的一部分。请务必阅读自定义连接器概述来了解整个流程。

若要创建自定义连接器，必须描述要连接到的 API，使连接器可识别此 API 的操作和数据结构。在本主题中，您将使用描述认知服务文本分析情绪 API（我们在此系列的示例）的 OpenAPI 定义创建自定义连接器。

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

先决条件

描述示例 API 的 OpenAPI 定义。创建自定义连接器时，OpenAPI 定义必须小于 1 MB。 OpenAPI 定义需要采用 OpenAPI 2.0（以前称为 Swagger）格式。

如果有多个安全定义，自定义连接器将选择最高的安全定义。自定义连接器创建不支持 OAuth 安全定义中的客户端凭据（例如，应用程序和密码）。
认知服务文本分析 API 的 API 密钥。
以下订阅之一：
- Azure，如果您使用的是逻辑应用
- Power Automate
- Power Apps
如果使用的是逻辑应用，请先创建 Azure 逻辑应用自定义连接器。

导入 OpenAPI 定义

您现在已准备好使用您下载的 OpenAPI 定义。所有必需的信息都包含在定义中，您可以在使用自定义连接器向导时查看和更新这些信息。

首先为逻辑应用或 Power Automate 和 Power Apps 导入 OpenAPI 定义。

备注

OpenAPI 定义需要采用 OpenAPI 2.0（以前称为 Swagger）格式。不支持 OpenAPI 3.0 格式的 OpenAPI 定义。

为逻辑应用导入 OpenAPI 定义

转到 Azure 门户，打开前面在创建 Azure 逻辑应用自定义连接器中创建的逻辑应用连接器。
在连接器的菜单中，选择逻辑应用连接器，然后选择编辑。
在常规下，选择上载 OpenAPI 文件，然后转到您创建的 OpenAPI 定义。

备注

本教程着重介绍 REST API，但是您也可以为逻辑应用使用 SOAP API。

为 Power Automate 和 Power Apps 导入 OpenAPI 定义

登录到 Power Apps 或 Power Automate。
在左侧窗格中，选择数据 > 自定义连接器。
选择新建自定义连接器，然后选择导入 OpenAPI 文件。
为自定义连接器输入名称，转到您下载或创建的 OpenAPI 定义，然后选择继续。

参数价值

自定义连接器标题 SentimentDemo

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

查看常规详细信息

从现在起，我们将演示 Power Automate UI，但在三个技术中执行的步骤都大致相同。我们将指出各个不同之处。在本主题的这一部分中，我们将主要回顾 UI 并向您展示值与 OpenAPI 文件的各个部分如何对应。

在向导顶部，请确保名称设置为 SentimentDemo，然后选择创建连接器。
在常规页上，查看从 OpenAPI 定义导入的信息，包括 API 主机和 API 的基础 URL。连接器使用 API 主机和基 URL 来确定如何调用 API。

备注

有关连接到本地 API 的详细信息，请转到使用数据网关连接到本地 API。

OpenAPI 定义的以下部分包含此 UI 页面的信息：
```
  "info": {
    "version": "1.0.0",
    "title": "SentimentDemo",
    "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
  },
  "host": "westus.api.cognitive.microsoft.com",
  "basePath": "/",
  "schemes": [
    "https"
  ]
```

查看身份验证类型

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

在安全性页上，查看 API 密钥的身份验证信息。

API 密钥参数。

当有人第一次使用自定义连接器进行连接时，将显示此标签；您可以选择编辑更改此值。参数名称和位置必须与 API 预期的值（在本例中为 Ocp-Apim-Subscription-Key 和 Header）匹配。

OpenAPI 定义的以下部分包含此 UI 页面的信息：

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

查看连接器定义

自定义连接器向导的定义页面为您提供了很多选项，用于定义连接器如何工作以及它在逻辑应用、流和应用中的公开方式。我们将在本节中对 UI 加以说明并介绍几个选项，不过我们也鼓励您自己进行探索。有关如何在此 UI 中从头开始定义对象的信息，请转到创建连接器定义。

以下区域显示针对连接器定义的所有操作、触发器（适用于逻辑应用和 Power Automate）和引用。在这种情况下，将显示 OpenAPI 定义中的 DetectSentiment 操作。此连接器中没有任何触发器，但您可以在对 Azure 逻辑应用和 Power Automate 使用 Webhook 中了解自定义连接器的触发器。
常规区域显示有关当前所选操作或触发器的信息。可在此处编辑这些信息，包括逻辑应用或流中操作和参数的可见性属性：
- 无：通常在逻辑应用或流中显示
- 高级：在其他菜单下隐藏
- 内部：向用户隐藏
- 重要：始终先向用户显示
请求区域根据 OpenAPI 定义中包括的 HTTP 请求显示信息。在本例中，您会看到 HTTP 谓词为 POST，URL 为 /text/analytics/v2.0/sentiment（API 的完整 URL 为 <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>）。很快您会在正文参数中看得更清楚。

OpenAPI 定义的以下部分包含 UI 的常规和请求区域的信息：
```
"paths": {
  "/text/analytics/v2.0/sentiment": {
    "post": {
      "summary": "Returns a numeric score representing the sentiment detected",
      "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
      "operationId": "DetectSentiment"
```
响应区域根据 OpenAPI 定义中包括的 HTTP 响应显示信息。在本例中，只针对 200（成功响应）定义了一个响应，但您可以定义更多响应。

OpenAPI 定义的以下部分包含一些与响应相关的信息：
```
"score": {
 "type": "number",
 "format": "float",
 "description": "score",
 "x-ms-summary": "score"
},
"id": {
 "type": "string",
 "description": "id",
 "x-ms-summary": "id"
}
```
此部分演示由连接器返回的两个值：id 和 score。其中包括它们的数据类型和字段 x-ms-summary，它是一个 OpenAPI 扩展。有关此扩展和其他扩展的更多信息，请转到扩展自定义连接器的 OpenAPI 定义。
验证区域显示在 API 定义中检测到的任何问题。在保存连接器之前，请务必检查此区域。

更新定义

下载的 OpenAPI 定义是一个不错的基本示例，但您可能需要执行很多更新来处理定义，使连接器变得更友好，方便用户在逻辑应用、流或应用中使用。我们将向您演示如何对定义进行更改。

在请求区域中，选择正文，然后选择编辑。
在参数区域中，现在可以看到 API 预期的三个参数：ID、Language 和 Text。选择 ID，然后选择编辑。
在架构属性区域中更新参数的说明，然后选择返回。

参数值

说明您提交的每个文档的数字标识符
在参数区域中，选择返回以返回到主定义页。
在向导的右上角，选择更新连接器。

参数	值
说明	您提交的每个文档的数字标识符

下载更新的 OpenAPI 文件

您可以从 OpenAPI 文件中或从头开始（在 Power Automate 和 Power Apps 中）创建自定义连接器。不管以何种方式创建连接器，都可以下载服务在内部使用的 OpenAPI 定义。

在逻辑应用中，可从自定义连接器下载。
在 Power Automate 或 Power Apps 中，从自定义连接器列表下载。

测试连接器

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

重要

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

在测试页上，选择新建连接。
输入文本分析 API 中的 API 密钥，然后选择创建连接。
返回到测试页，执行下列操作之一：
- 在 Power Automate 中，将会返回到测试页。选择刷新图标，以确保更新连接信息。
- 在 Power Apps 中，将会转到当前环境中的可用连接列表。选择右上角的齿轮图标，然后选择自定义连接器。选择创建的连接器，然后返回到测试页。
在测试页上的文本字段中输入一个值（其他字段使用前面设置的默认值），然后选择测试操作。
连接器调用 API，您可以查看响应，其中包括情绪分数。