你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

教程:使用请求跟踪调试 API

适用于:消耗 | 开发人员 | 基本 | 标准 | 高级

本教程介绍如何在 Azure API 管理中检查(跟踪)请求处理。 跟踪有助于调试 API 并排查 API 问题。

本教程介绍如何执行下列操作:

  • 在测试控制台中跟踪示例调用
  • 查看请求处理步骤
  • 为 API 启用跟踪

显示 API 检查器的屏幕截图。

注意

目前,基本 v2 层级和标准 v2 层级不支持跟踪 API 请求。

先决条件

重要

  • 无法再通过在请求中设置 Ocp-Apim-Trace 标头,并在响应中使用 Ocp-Apim-Trace-Location 标头的值检索跟踪来启用 API 管理请求跟踪
  • 为了提高安全性,现在可以通过以下方法在单个 API 级别启用跟踪:使用 API 管理 REST API 获取限时令牌,并在请求中将该令牌传递到网关。 有关详细信息,请参阅本教程的后面部分。
  • 启用跟踪时请务必小心,因为这可能会泄露跟踪数据中的敏感信息。 确保已采取适当的安全措施来保护跟踪数据。

在门户中跟踪调用

  1. 登录到 Azure 门户,并导航到 API Management 实例。

  2. 选择“API”。

  3. 在 API 列表中选择“演示会议 API”。

  4. 选择“测试”选项卡。

  5. 选择“GetSpeakers”操作。

  6. (可选)通过选择“眼睛”图标,检查请求中使用的 Ocp-Apim-Subscrition-Key 标头的值。

    提示

    可通过在门户中检索另一个订阅的密钥来替代 Ocp-Apim-Subscription-Key 的值。 选择“订阅”,然后打开另一个订阅的上下文菜单 (…)。 选择“显示/隐藏密钥”并复制其中一个密钥。 也可以按需再生成密钥。 然后,在测试控制台中,选择“+ 添加标头”以使用新密钥值添加 Ocp-Apim-Subscrition-Key 标头。

  7. 选择“跟踪”。

查看跟踪信息

  1. 调用结束后,转到“HTTP 响应”中的“跟踪”选项卡。

  2. 选择以下任何链接跳转到详细跟踪信息:入站、后端、出站、出错时。

    查看响应跟踪

    • 入站 - 显示从调用方收到的原始请求 API 管理和应用于该请求的策略。 例如,如果你在教程:转换和保护 API 中添加了策略,它们就会出现在此处。

    • 后端 - 显示 API 管理发送到 API 后端的请求以及收到的响应。

    • 出站 - 显示在将响应发送给调用方之前应用于该响应的策略。

    • 出错时 - 显示在处理请求期间发生的错误以及应用于错误的策略。

    提示

    每个步骤还显示了自 API 管理收到请求以来消逝的时间。

为 API 启用跟踪

当使用 curl、REST 客户端(例如具有 REST 客户端扩展的 Visual Studio Code)或客户端应用向 API 管理发出请求时,可以启用 API 跟踪。

使用对 API 管理 REST API 的调用,通过以下步骤启用跟踪。

注意

以下步骤需要 API 管理 REST API 版本 2023-05-01-preview 或更高版本。 你必须在 API 管理实例上获得“参与者”或更高角色才能调用 REST API。

  1. 通过调用列出调试凭据 API 来获取跟踪凭据。 传递 URI 中的网关 ID,或者对实例在云中的托管网关使用“托管”。 例如,若要获取托管网关的跟踪凭据,请使用类似于下面的调用:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
    

    在请求正文中,传递要跟踪的 API 的完整资源 ID,并将 purposes 指定为 tracing。 默认情况下,响应中返回的令牌凭据将在 1 小时后过期,但你可以在有效负载中指定其他值。

    {
        "credentialsExpireAfter": PT1H,
        "apiId": "<API resource ID>",
        "purposes": ["tracing"]
    }
    

    令牌凭据在响应中返回,如下所示:

    {
          "token": "aid=api-name&p=tracing&ex=......."
    }
    
  2. 若要为针对 API 管理网关的请求启用跟踪,请在 Apim-Debug-Authorization 标头中发送令牌值。 例如,若要跟踪对演示会议 API 的调用,请使用类似于下面的调用:

    curl -v GET https://apim-hello-world.azure-api.net/conference/speakers HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&p=tracing&ex=......."
    
  3. 根据令牌,响应包含不同的标头:

    • 如果令牌有效,响应将包含一个 Apim-Trace-Id 标头,其值为跟踪 ID。
    • 如果令牌已过期,响应将包含一个 Apim-Debug-Authorization-Expired 标头,其中包含有关到期日期的信息。
    • 如果为错误的 API 获取了令牌,响应将包含一个带有错误消息的 Apim-Debug-Authorization-WrongAPI 标头。
  4. 若要检索跟踪,请将上一步中获取的跟踪 ID 传递给网关的列出跟踪 API。 例如,若要检索托管网关的跟踪,请使用类似于下面的调用:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
    

    在请求正文中,传递在上一步中获取的跟踪 ID。

    {
        "traceId": "<trace ID>"
    }
    

    响应正文中将包含对网关的上一个 API 请求的跟踪数据。 该跟踪类似于通过在门户测试控制台中跟踪调用可以看到的跟踪。

有关自定义跟踪信息的详细信息,请参阅跟踪策略。

后续步骤

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

  • 跟踪示例调用
  • 查看请求处理步骤
  • 为 API 启用跟踪

转到下一教程: