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

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

项目
03/08/2025

适用于：所有 API 管理层级

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

提示

API 团队可以在工作区中使用此功能。工作区提供对 API 及其自己的 API 运行时环境的隔离管理访问权限。

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

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

先决条件

了解 Azure API 管理术语。
请完成以下快速入门：创建一个 Azure API 管理实例。
完成以下教程：导入和发布第一个 API。

重要

API 管理不再支持用于跟踪或 Ocp-Apim-Trace 标头。
为了提高安全性，现在可以通过以下方法在单个 API 级别启用跟踪：使用 API 管理 REST API 获取限时令牌，并在请求中将该令牌传递到网关。有关详细信息，请参阅启用 API 跟踪。
启用跟踪时请务必小心，因为这可能会泄露跟踪数据中的敏感信息。确保已采取适当的安全措施来保护跟踪数据。

在门户中跟踪调用

按照以下步骤在门户的测试控制台中跟踪 API 请求。此示例假定你在上一个教程中导入了示例 API。可以使用导入的其他 API 执行类似的步骤。

登录到 Azure 门户，并导航到 API Management 实例。
选择“API”>“API”。
从 API 列表中选择“Petstore API”。
选择“测试”选项卡。
选择“按 ID 查找宠物”操作。
在 petId 查询参数中，输入“1”。
（可选）通过选择“眼睛”图标，检查请求中使用的 Ocp-Apim-Subscrition-Key 标头的值。

提示

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

查看跟踪信息

调用结束后，转到“HTTP 响应”中的“跟踪”选项卡。
选择以下任何链接跳转到详细跟踪信息：入站、后端、出站、出错时。
- 入站 - 显示从调用方收到的原始请求 API 管理和应用于该请求的策略。例如，如果你在教程：转换和保护 API 中添加了策略，它们就会出现在此处。
- 后端 - 显示 API 管理发送到 API 后端的请求以及收到的响应。
- 出站 - 显示在将响应发送给调用方之前应用于该响应的策略。
- 出错时 - 显示在处理请求期间发生的错误以及应用于错误的策略。
提示

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

为 API 启用跟踪

使用 curl、REST 客户端（如带 REST 客户端扩展的 Visual Studio Code）或客户端应用时，为了能够跟踪对 API 管理的请求，需要执行以下简要步骤。目前必须使用 API 管理 REST API 执行以下步骤：

获取用于跟踪的调试令牌。
将 Apim-Debug-Authorization 请求标头中的令牌值添加到 API 管理网关。
获取 Apim-Trace-Id 响应标头中的跟踪 ID。
检索与跟踪 ID 对应的跟踪。

详细步骤如下。

注意

这些步骤需要 API 管理 REST API 版本 2023-05-01-preview 或更高版本。你必须在 API 管理实例上获得“参与者”或更高角色才能调用 REST API。
有关向 REST API 进行身份验证的信息，请参阅 Azure REST API 参考。

获取调试令牌 - 调用 API 管理网关的列出调试凭据 API。在 URI 中，针对云中实例的托管网关输入“managed”，或者针对自承载网关输入网关 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": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
    "purposes": ["tracing"]
}
```
注意

只能从完整的资源 ID 拉取 apiId，而不能从门户中显示的名称拉取。

获取 apiId：
```
az apim api list --resource-group <resource-group> --service-name <service-name> -o table
```
调试令牌凭据在响应中返回，类似如下所示：
```
{
      "token": "aid=api-name&......."
}
```
在请求标头中添加令牌值 - 若要为针对 API 管理网关的请求启用跟踪，请在 Apim-Debug-Authorization 标头中发送令牌值。例如，若要跟踪对上一教程中导入的 Petstore API 的调用，可以使用如下所示的请求：
```
curl -v https://apim-hello-world.azure-api.net/pet/1 HTTP/1.1 \
    -H "Ocp-Apim-Subscription-Key: <subscription-key>" \
    -H "Apim-Debug-Authorization: aid=api-name&......."
```
评估响应 - 响应可以包含以下标头之一，具体取决于调试令牌的状态：
- 如果调试令牌有效，响应将包含一个 Apim-Trace-Id 标头，其值为跟踪 ID，如下所示：
```
Apim-Trace-Id: 0123456789abcdef....
```
- 如果调试令牌已过期，响应将包含一个 Apim-Debug-Authorization-Expired 标头，其中包含有关到期日期的信息。
- 如果获取了其他 API 的调试令牌，响应将包含一个带有错误消息的 Apim-Debug-Authorization-WrongAPI 标头。
检索跟踪 - 将上一步获取的跟踪 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": "0123456789abcdef...."
}
```
响应正文中将包含对网关的上一个 API 请求的跟踪数据。该跟踪类似于通过在门户测试控制台中跟踪调用可以看到的跟踪。

VS Code REST 客户端扩展的示例 `.http` 文件

若要帮助通过 Visual Studio Code REST 客户端扩展自动执行这些步骤，可以使用以下示例 .http 文件：

@subscriptionId = // Your subscription ID
@resourceGroup = // Your resource group
@apimName = // Your API Management service name
@clientId = // Client ID from an app registration for authentication
@clientSecret = // Client secret from app registration
@externalHost = // The host name of the App Gateway or the fully qualified gateway URL
@subscriptionKey = // API Management subscription key
@apiEndPoint = // API URL
@requestBody = // Data to send
@tenantId = // Tenant ID
 
POST https://login.microsoftonline.com/{{tenandId}}/oauth2/token
content-type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id={{clientId}}&client_secret={{clientSecret}}&resource=https%3A%2F%2Fmanagement.azure.com%2F
 
###
@authToken = {{login.response.body.$.access_token}}
###
# @name listDebugCredentials
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
Authorization: Bearer {{authToken}}
Content-Type: application/json
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/apis/{{apiId}}",
    "purposes": ["tracing"]
}
 
###
@debugToken = {{listDebugCredentials.response.body.$.token}}
 
###
# @name callApi
curl -k -H "Apim-Debug-Authorization: {{debugToken}}" -H 'Host: {{externalHost}}' -H 'Ocp-Apim-Subscription-Key: {{subscriptionKey}}' -H 'Content-Type: application/json' '{{apiEndPoint}}' -d '{{requestBody}}'
 
###
@traceId = {{callApi.response.headers.Apim-Trace-Id}}
 
###
# @name getTrace
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listTrace?api-version=2024-06-01-preview
Authorization: Bearer {{authToken}}
Content-Type: application/json
 
{
    "traceId": "{{traceId}}"
}

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

后续步骤

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

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

转到下一教程：

使用修订版

通过

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

先决条件

在门户中跟踪调用

查看跟踪信息

为 API 启用跟踪

VS Code REST 客户端扩展的示例 `.http` 文件

后续步骤

反馈

其他资源

通过

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

先决条件

在门户中跟踪调用

查看跟踪信息

为 API 启用跟踪

VS Code REST 客户端扩展的示例 .http 文件

后续步骤

反馈

其他资源

VS Code REST 客户端扩展的示例 `.http` 文件