教程:使用 Visual Studio Code 的 API 管理扩展来导入和管理 APITutorial: Use the API Management Extension for Visual Studio Code to import and manage APIs

本教程将介绍如何使用 Visual Studio Code 的 API 管理扩展来实现 API 管理中的常见操作。In this tutorial, you learn how to use the API Management Extension for Visual Studio Code for common operations in API Management. 使用熟悉的 Visual Studio Code 环境导入、更新、测试和管理 API。Use the familiar Visual Studio Code environment to import, update, test, and manage APIs.

你将学习如何执行以下操作:You learn how to:

  • 将 API 导入 API 管理Import an API into API Management
  • 编辑 APIEdit the API
  • 应用 API 管理策略Apply API Management policies
  • 测试 APITest the API

API 管理扩展中的 API

有关其他 API 管理功能的介绍,请使用 Azure 门户参阅“API 管理”教程。For an introduction to additional API Management features, see the API Management tutorials using the Azure portal.

先决条件Prerequisites

导入 APIImport an API

以下示例将 JSON 格式的 OpenAPI 规范导入 API 管理。The following example imports an OpenAPI Specification in JSON format into API Management. Microsoft 提供本示例中使用的后端 API,并将其托管在 Azure 上 (https://conferenceapi.chinacloudsites.cn?format=json)。Microsoft provides the backend API used in this example, and hosts it on Azure at https://conferenceapi.chinacloudsites.cn?format=json.

  1. 在 Visual Studio Code 中,选择“活动栏”中的 Azure 图标。In Visual Studio Code, select the Azure icon from the Activity Bar.
  2. 在“资源管理器”窗格中,展开你创建的 API 管理实例。In the Explorer pane, expand the API Management instance you created.
  3. 右键单击 API,然后选择“从 OpenAPI 链接导入” 。Right-click APIs, and select Import from OpenAPI Link.
  4. 出现提示时,输入以下值:When prompted, enter the following values:
    1. JSON 格式的内容的“OpenAPI 链接”。An OpenAPI link for content in JSON format. 对于本示例: https://conferenceapi.chinacloudsites.cn?format=jsonFor this example: https://conferenceapi.chinacloudsites.cn?format=json. 此 URL 是实现示例 API 的服务。This URL is the service that implements the example API. API 管理将请求转发到此地址。API Management forwards requests to this address.
    2. 在 API 管理实例中唯一的 API 名称,如 demo-conference-api。An API name, such as demo-conference-api, that is unique in the API Management instance. 此名称只能包含字母、数字和连字符。This name can contain only letters, number, and hyphens. 第一个字符和最后一个字符必须必须为字母数字字符。The first and last characters must be alphanumeric. 将在调用 API 的路径中使用此名称。This name is used in the path to call the API.

成功导入 API 后,它将显示在“资源管理器”窗格中,可用的 API 操作显示在“操作”节点下。After the API is imported successfully, it appears in the Explorer pane, and available API operations appear under the Operations node.

资源管理器窗格中导入的 API

编辑 APIEdit the API

可在 Visual Studio Code 中编辑 API。You can edit the API in Visual Studio Code. 例如,在编辑器窗口中编辑 API 的“资源管理器 JSON”说明,以删除用于访问 API 的 http 协议。For example, edit the Resource Manager JSON description of the API in the editor window to remove the http protocol used to access the API. 然后选择“文件” > “保存” 。Then select File > Save.

编辑 JSON 说明

若要编辑 OpenAPI 格式,请在“资源管理器”窗格中右键单击 API 名称,然后选择“编辑 OpenAPI”。To edit the OpenAPI format, right-click the API name in the Explorer pane and select Edit OpenAPI. 进行所需的更改,然后选择“文件” > “保存” 。Make your changes, and then select File > Save.

将策略应用到 APIApply policies to the API

API 管理提供可为 API 配置的策略API Management provides policies you can configure for your APIs. 策略是一组语句,在请求或 API 的响应时按顺序执行。Policies are a collection of statements that are executed sequentially on the request or response of an API. 策略可以是全局的(适用于 API 管理实例中的所有 API),也可以将策略范围限定为特定 API 或 API 操作。Policies can be global, which apply to all APIs in your API Management instance, or they can be scoped to a specific API or API operation.

本部分介绍如何将一些常见的出站策略应用于转换 API 响应的 API。This section shows how to apply some common outbound policies to your API that transform the API response. 此示例中的策略将更改响应标头并隐藏响应正文中显示的原始后端 URL。The policies in this example change response headers and hide original backend URLs that appear in the response body.

  1. 在“资源管理器”窗格中,在你导入的 demo-conference-api 下选择“策略”。In the Explorer pane, select Policy under the demo-conference-api that you imported. 策略文件将在编辑器窗口中打开。The policy file opens in the editor window. 此文件将为 API 中的所有操作配置策略。This file configures policies for all operations in the API.

  2. 使用以下 <outbound> 元素中的内容更新文件:Update the file with the following content in the <outbound> element:

    [...]
    <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 策略添加自定义响应标头,用于演示。The first set-header policy adds a custom response header for demonstration purposes.
    • 第二个 set-header 策略删除 X-Powered-By 标头(如果存在)。The second set-header policy deletes the X-Powered-By header, if it exists. 此标头可能披露 API 后端使用的应用程序框架,发布者通常会将其删除。This header can reveal the application framework used in the API backend, and publishers often remove it.
    • redirect-content-urls 策略重写(屏蔽)响应正文中的链接,使其通过 API 管理网关指向等效的链接。The redirect-content-urls policy rewrites (masks) links in the response body so that they point to the equivalent links via the API Management gateway.
  3. 保存文件。Save the file. 如果出现提示,请选择“上传”将文件上传到云中。If you are prompted, select Upload to upload the file to the cloud.

测试 APITest the API

获取订阅密钥Get the subscription key

若要测试导入的 API 以及应用的策略,需要 API 管理实例的订阅密钥。To test the imported API you imported and the policies that are applied, you need a subscription key for your API Management instance.

  1. 在“资源管理器”窗格中,右键单击 API 管理实例的名称。In the Explorer pane, right-click the name of your API Management instance.

  2. 选择“复制订阅密钥”。Select Copy Subscription Key.

    复制订阅密钥

测试 API 操作Test an API operation

  1. 在“资源管理器”窗格中,展开你导入的 demo-conference-api 下的“操作”节点。In the Explorer pane, expand the Operations node under the demo-conference-api that you imported.
  2. 选择一个操作,如“GetSpeakers”,然后右键单击该操作并选择“测试操作”。Select an operation such as GetSpeakers, and then right-click the operation and select Test Operation.
  3. 在编辑器窗口中的 Ocp-Apim-Subscription-Key 旁边,将 {{SubscriptionKey}} 替换为你复制的订阅密钥。In the editor window, next to Ocp-Apim-Subscription-Key, replace {{SubscriptionKey}} with the subscription key that you copied.
  4. 选择“发送请求”。 Select Send request.

从 Visual Studio Code 发送 API 请求

如果请求成功,后端以“200 正常”和某些数据做出响应。When the request succeeds, the backend responds with 200 OK and some data.

API 测试操作

请注意响应中的以下详细信息:Notice the following details in the response:

  • 会将 Custom 标头添加到响应中。The Custom header is added to the response.
  • 响应中不会出现 X-Powered-By 标头。The X-Powered-By header doesn't appear in the response.
  • API 后端的 URL 将重定向到 API 管理网关,在本例中为 https://apim-hello-world.azure-api.cn/demo-conference-apiURLs to the API backend are redirected to the API Management gateway, in this case https://apim-hello-world.azure-api.cn/demo-conference-api.

跟踪 API 操作Trace the API operation

若要获取详细跟踪信息以帮助调试 API 操作,请选择“Ocp-APIM-Trace-Location”旁边显示的链接。For detailed tracing information to help you debug the API operation, select the link that appears next to Ocp-APIM-Trace-Location.

位于该位置的 JSON 文件包含入站、后端和出站跟踪信息,因此你可以确定发出请求后哪些地方出现了问题。The JSON file at that location contains Inbound, Backend, and Outbound trace information so you can determine where any problems occur after the request is made.

提示

测试 API 操作时,API 管理扩展允许进行可选的策略调试(在开发人员服务层中可用)。When you test API operations, the API Management Extension allows optional policy debugging (available in the Developer service tier).

清理资源Clean up resources

当不再需要 API 管理实例和资源组时,请通过单击右键并选择“在门户中打开”来删除 API 管理服务及其资源组,从而删除该实例和资源组。When no longer needed, remove the API Management instance by right-clicking and selecting Open in Portal to delete the API Management service and its resource group.

另外,你还可以选择“删除 API 管理”,以仅删除 API 管理实例(此操作不会删除其资源组)。Alternately, you can select Delete API Management to only delete the API Management instance (this operation doesn't delete its resource group).

从 VS Code 中删除 API 管理实例

后续步骤Next steps

本教程介绍了 Visual Studio Code 的 API 管理扩展的多项功能,可用于导入和管理 API。This tutorial introduced several features of the API Management Extension for Visual Studio Code that you can use to import and manage APIs. 你已了解如何执行以下操作:You learned how to:

  • 将 API 导入 API 管理Import an API into API Management
  • 编辑 APIEdit the API
  • 应用 API 管理策略Apply API Management policies
  • 测试 APITest the API

API 管理扩展提供了用于处理 API 的额外功能。The API Management Extension provides additional features to work with your APIs. 例如调试策略(在开发人员服务层中可用),或创建和管理命名值For example, debug polices (available in the Developer service tier), or create and manage named values.