教程：导入和发布第一个 API

适用于：所有 API 管理层级

本教程介绍如何将 JSON 格式的 OpenAPI 规范后端 API 导入 Azure API 管理。 在此示例中，请导入开源的 Petstore API。

将后端 API 导入 API 管理时，API 管理 API 将成为后端 API 的外观。 可以在 API 管理中根据需求自定义外观，而无需更改后端 API。 有关详细信息，请参阅转换和保护 API。

在本教程中，你将了解如何执行以下操作：

导入后，可以在 Azure 门户中管理 API。

先决条件

• 理解 Azure API 管理的术语。
• 创建一个 Azure API 管理实例。

转到你的 API 管理实例

1. 在 Azure 门户中，搜索并选择 API 管理服务：

   

2. 在 API 管理服务 页上，选择 API 管理实例：

   

导入和发布后端 API

本部分演示如何导入和发布 OpenAPI 规范后端 API。

1. 在 API 管理实例的左侧导航中，在 API 下选择 API。

2. 选择“OpenAPI”磁贴。

3. 在“基于 OpenAPI 规范创建”窗口中，选择“完全” 。

4. 输入下表中的值。

   可以在创建 API 期间设置 API 值，或者以后转到“设置”选项卡进行设置。

   

   设置	值	说明
   OpenAPI 规范	https://petstore3.swagger.io/api/v3/openapi.json -或- https://petstore.swagger.io/v2/swagger.json	指定实现 API 的后端服务以及 API 支持的操作。 后端服务 URL 稍后会显示为 API 的“设置”页上的“Web 服务 URL”。 导入后，可以在规范中添加、编辑、重命名或删除操作。
   在操作模板中包含查询参数	已选择（默认）	指定是否将规范中需要的查询参数作为 API 管理中的模板参数导入。
   显示名称	输入 OpenAPI 规范 URL 后，API 管理将根据 JSON 填写此字段。	显示在开发人员门户中的名称。
   名称	输入 OpenAPI 规范 URL 后，API 管理将根据 JSON 填写此字段。	API 的唯一名称。
   说明	输入 OpenAPI 规范 URL 后，API 管理将根据 JSON 填写此字段。	API 的可选说明。
   URL 方案	HTTPS	哪些协议可以访问 API。
   API URL 后缀	petstore	追加到 API 管理服务基 URL 的后缀。 API 管理根据其后缀来区分和路由 API，因此对于给定发布者的每个 API，后缀必须是唯一的。 详细了解 API 管理如何路由请求。
   标记		用于组织搜索、分组或筛选 API 的标记。
   产品	不受限制	一个或多个 API 的关联。 在某些层中，API 管理实例附带两个示例产品：“入门”和“无限制”。 请在开发人员门户中将 API 与某个产品相关联，以发布 API。 可在一个产品中包含多个 API，并通过开发人员门户将产品订阅提供给开发人员。 若要将此 API 添加到另一个产品，请键入或选择产品名称。 重复此步骤以将 API 添加到多个产品。 以后也可以从“设置”页将 API 添加到产品。 有关产品的详细信息，请参阅创建和发布产品。
   网关	托管	公开此 API 的 API 网关。 此字段仅在“开发人员”和“高级”层服务中提供。 “托管”指示内置于 API 管理服务中并由 Microsoft 托管在 Azure 中的网关。 自承载网关仅在“高级”和“开发人员”服务层中提供。 可以将这些网关部署在本地或其他云中。 如果未选择任何网关，则 API 不可用，API 请求不会成功。
   对此 API 进行版本控制？	选择或取消选择	有关详细信息，请参阅发布 API 的多个版本。

5. 选择“创建”以创建 API。

如果在导入 API 定义时遇到问题，请参阅已知问题列表和限制。

查看和修改 API 设置

导入 API 后，可以在 Azure 门户中查看和修改其设置和作。

1. 在 API 管理实例的左侧导航中，在 API 下选择 API。

2. 选择导入的 API（例如 Swagger Petstore）。

3. 选择“ 设计 ”选项卡以查看和修改 OpenAPI 规范中的 API作，包括：

   • 操作详细信息，如 URL、方法和说明
   • 请求和响应定义
   • 修改请求和响应的策略

4. 选择 “设置” 选项卡以查看和修改 API 配置详细信息，包括：

   • 显示名称、名称和说明
   • Web 服务 URL（后端服务）、URL 方案和 API URL 后缀
   • 产品、标记和版本控制
   • 更高级的设置，例如订阅要求、安全性和监视

完成 API 管理教程时，可以详细了解如何配置 API 设置。 可以随时更新这些设置以自定义 API 配置。

在 Azure 门户中测试新的 API

可直接从 Azure 门户调用 API 操作，这样就可以方便地查看和测试操作。 在门户的测试控制台中，默认情况下，使用内置全访问订阅中的密钥调用 API。 还可以使用范围限定为某种产品的订阅密钥来测试 API 调用。

1. 在 API 管理实例的左侧导航中，选择 API API>>Swagger Petstore。

2. 选择“测试”选项卡，然后选择“按状态查找宠物”。 该页将显示查询参数的状态。 选择其中一个可用的值，例如“挂起”。 你还可以在此处添加查询参数和标头。

   在“HTTP 请求”部分中，系统会自动填充 Ocp-Apim-Subscription-Key 标头，可以通过选择“眼睛”图标来显示此标头。

3. 选择“发送”。

   

   后端以“200 正常”和某些数据做出响应。

API 管理如何路由请求

API 管理充当 API 客户端和后端服务之间的网关。 当客户端向 API 管理管理的 API 发出请求时，路由将遵循以下模式：

客户端请求 URL：
[API Management gateway URL] + [API URL suffix] + [Operation endpoint]

API 管理使用此模式将请求转发到后端服务：

后端服务 URL：
[Web service URL] + [Operation endpoint]

下表介绍了本教程中使用的 Petstore API 示例上下文中的每个路由参数：

示例：按状态查找宠物

使用本教程中导入的 Petstore API：

1. 客户端调用 API 管理：
   https://apim-hello-world.azure-api.net/petstore/pet/findByStatus?status=pending

   • API 管理网关 URL： https://apim-hello-world.azure-api.net
   • API URL 后缀：petstore
   • 操作终结点：/pet/findByStatus

2. API 管理路由到后端：
   https://petstore3.swagger.io/api/v3/pet/findByStatus?status=pending

   • Web 服务 URL：https://petstore3.swagger.io/api/v3
   • 作终结点： /pet/findByStatus （与 API 管理定义中相同）

后续步骤

在本教程中，你了解了如何执行以下操作：

转到下一教程，了解如何创建和发布产品：