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

适用于：所有 API 管理层级

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

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

先决条件

• 了解 Azure API 管理术语。
• 请完成以下快速入门：创建一个 Azure API 管理实例。
• 完成以下教程：导入和发布第一个 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 的调用，通过以下步骤启用跟踪。

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

   POST https://management.chinacloudapi.cn/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.cn/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.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
   

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

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

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

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

后续步骤

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

转到下一教程：