教程：使用 Visual Studio Code 的 Azure API 管理扩展来导入和管理 API

本教程将介绍如何使用 Visual Studio Code 的 API 管理扩展来实现 API 管理中的常见操作。 使用熟悉的 Visual Studio Code 环境导入、更新、测试和管理 API。

你将学习如何执行以下操作：

有关 API 管理功能的详细介绍，请使用 Azure 门户参阅“API 管理”教程。

先决条件

• 理解 Azure API 管理的术语。
• 确保已安装 Visual Studio Code 以及 Visual Studio Code 的 Azure API 管理扩展最新版。
• 创建 API 管理实例。

导入 API

以下示例将 JSON 格式的 OpenAPI 规范导入 API 管理。 Microsoft 提供本示例中使用的后端 API，并将其托管在 Azure 上 (https://conferenceapi.chinacloudsites.cn)。

1. 在 Visual Studio Code 中，选择“活动栏”中的 Azure 图标。
2. 在“资源管理器”窗格中，展开你创建的 API 管理实例。
3. 右键单击 API，然后选择“从 OpenAPI 链接导入” 。
4. 出现提示时，输入以下值：

   1. JSON 格式的内容的“OpenAPI 链接”。 对于本示例： https://conferenceapi.chinacloudsites.cn?format=json 。

      此文件指定用于实现示例 API 的后端服务，在本例中为 https://conferenceapi.chinacloudsites.cn。 API 管理将请求转发到此 Web 服务。

   2. 在 API 管理实例中唯一的 API 名称，如 demo-conference-api。 此名称只能包含字母、数字和连字符。 第一个字符和最后一个字符必须必须为字母数字字符。 将在调用 API 的路径中使用此名称。

成功导入 API 后，它将显示在“资源管理器”窗格中，可用的 API 操作显示在“操作”节点下。

编辑 API

可在 Visual Studio Code 中编辑 API。 例如，在编辑器窗口中编辑 API 的“资源管理器 JSON”说明，以删除用于访问 API 的 http 协议。

若要编辑 OpenAPI 格式，请在“资源管理器”窗格中右键单击 API 名称，然后选择“编辑 OpenAPI”。 进行所需的更改，然后选择“文件”>“保存” 。

将策略应用到 API

API 管理提供可为 API 配置的策略。 策略是语句的集合。 这些语句在 API 的请求或响应中按顺序运行。 策略可以是全局的（适用于 API 管理实例中的所有 API），也可以将策略范围限定为某个特定产品、API 或 API 操作。

本部分介绍如何将常见的出站策略应用于转换 API 响应的 API。 此示例中的策略将更改响应标头并隐藏响应正文中显示的原始后端 URL。

1. 在“资源管理器”窗格中，在你导入的 demo-conference-api 下选择“策略”。 策略文件将在编辑器窗口中打开。 此文件将为 API 中的所有操作配置策略。

2. 使用以下 <outbound> 元素中的内容更新文件：

   [...]
   <outbound>
       <set-header name="Custom" exists-action="override">
           <value>"My custom value"</value>
       </set-header>
       <set-header name="X-Powered-By" exists-action="delete" />
       <redirect-content-urls />
       <base />
   </outbound>
   [...]
   

   • 第一个 set-header 策略添加自定义响应标头，用于演示。
   • 第二个 set-header 策略删除 X-Powered-By 标头（如果存在）。 此标头可能披露 API 后端使用的应用程序框架，发布者通常会将其删除。
   • redirect-content-urls 策略重写（屏蔽）响应正文中的链接，使其通过 API 管理网关指向等效的链接。

3. 保存文件。 如果出现提示，请选择“上传”将文件上传到云中。

测试 API

若要测试 API，请获取订阅密钥，然后向 API 管理网关发出请求。

获取订阅密钥

若要测试导入的 API 以及应用的策略，需要 API 管理实例的订阅密钥。

1. 在“资源管理器”窗格中，右键单击 API 管理实例的名称。

2. 选择“复制订阅密钥”。 此密钥用于在创建 API 管理实例时创建的内置“所有访问权限”订阅。

   

   注意

   “所有访问权限”订阅允许访问 API 管理实例中的每个 API，并且只能由授权用户使用。 切勿将其用于例程 API 访问，也不要在客户端应用中嵌入“所有访问权限”密钥。

测试 API 操作

1. 在“资源管理器”窗格中，展开你导入的 demo-conference-api 下的“操作”节点。
2. 选择一个操作，如“GetSpeakers”，然后右键单击该操作并选择“测试操作”。
3. 在编辑器窗口中的 Ocp-Apim-Subscription-Key 旁边，将 {{SubscriptionKey}} 替换为你复制的订阅密钥。
4. 在 Ocp-Apim-Trace 的旁边，输入 false。 此设置将禁用请求跟踪。
5. 选择“发送请求”。

如果请求成功，后端以“200 正常”和某些数据做出响应。

请注意响应中的以下详细信息：

• 会将 Custom 标头添加到响应中。
• 响应中不会出现 X-Powered-By 标头。
• API 后端的 URL 将重定向到 API 管理网关，在本例中为 https://apim-hello-world.azure-api.cn/demo-conference-api。

跟踪请求处理

（可选）可以获取详细的请求跟踪信息，以帮助调试和排查 API 问题。

若要跟踪请求处理，首先请为用于调试 API 的订阅启用“允许跟踪”设置。 有关使用门户启用此设置的步骤，请参阅验证允许跟踪设置。 为了尽量防止意外泄露敏感信息，仅允许跟踪 1 小时。

允许对订阅进行跟踪后，执行以下步骤：

1. 在“资源管理器”窗格中，展开你导入的 demo-conference-api 下的“操作”节点。
2. 选择一个操作，如“GetSpeakers”，然后右键单击该操作并选择“测试操作”。
3. 在编辑器窗口中的“Ocp-Apim-Subscription-Key”旁边，将 {{SubscriptionKey}} 替换为你要使用的订阅密钥。
4. 在 Ocp-Apim-Trace 的旁边，输入 true。 此设置将启用针对此请求的跟踪。
5. 选择“发送请求”。

请求成功后，后端响应将包含 Ocp-APIM-Trace-Location 标头。

选择“Ocp-APIM-Trace-Location”旁边的链接以查看入站、后端和出站跟踪信息。 跟踪信息有助于确定在提出请求后出现问题的地方。

清理资源

当不再需要 API 管理实例和资源组时，请通过单击右键并选择“在门户中打开”来删除 API 管理服务及其资源组，从而删除该实例和资源组。

另外，你还可以选择“删除 API 管理”，以仅删除 API 管理实例（此操作不会删除其资源组）。

相关内容

本教程介绍了适用于 Visual Studio Code 的 API 管理扩展的几个功能。 可使用这些功能导入和管理 API。 你已了解如何执行以下操作：

API 管理扩展提供了用于处理 API 的更多功能。 例如调试策略（在开发人员服务层中可用），或创建和管理命名值。