Руководство. Отладка API с помощью трассировки запросов

ПРИМЕНИМО К: все уровни API Management

В этом руководстве описывается, как проверить или отслеживать обработку запросов в Azure API Management. Трассировка помогает вам отлаживать и устранять неполадки с API.

В этом руководстве описано следующее:

Предварительные условия

• Сведения о терминологии Azure API Management.
• Выполните следующее краткое руководство: Создайте экземпляр Azure API Management.
• Выполните следующее руководство. Импорт и публикация первого API.

Отслеживание вызова в портале Azure

Выполните следующие действия, чтобы отследить запрос API в тестовой консоли на портале. В этом примере предполагается, что вы импортировали пример API в предыдущем руководстве. Вы можете выполнить аналогичные действия с помощью другого API, который вы импортировали.

1. Войдите на портал Azure и перейдите к экземпляру службы управления API.

2. Выберите API-интерфейсы>.

3. Выберите API Petstore из списка API.

4. Откройте вкладку Тест.

5. Выберите операцию "Найти животного по идентификатору".

6. В параметре petId Query введите 1.

7. При необходимости проверьте значение заголовка Ocp-Apim-Subscription-Key, используемого в запросе, выбрав значок "глаз".

   Совет

   Можно переопределить значение Ocp-Apim-Subscription-Key, извлекая ключ для другой подписки на портале Azure. Выберите Подписки и откройте контекстное меню (...) для другой подписки. Выберите Показать или скрыть ключи и скопируйте один из ключей. При необходимости вы также можете повторно создать ключи. Затем в тестовой консоли выберите + Добавить заголовок, чтобы добавить заголовок Ocp-Apim-Subscription-Key с новым значением ключа.

8. Выберите Трейс.

Просмотр информации о трассировке

1. После завершения вызова перейдите на вкладку Отслеживание в разделе HTTP-ответ.

2. Выберите любую из следующих ссылок, чтобы перейти к подробным сведениям трассировки: входящий, бэкенд сервер, исходящий, При ошибке.

   

   • Входящий трафик. Отображает исходный запрос API Management, полученный от клиента, и политики, примененные к запросу. Например, если вы добавили политики в учебнике: преобразование и защита API, они отображаются здесь.
   • Серверная часть. Отображает запросы, отправленные API Management в серверную часть API, и полученные ответы.
   • Исходящий трафик. Показывает политики, примененные к ответу перед отправкой обратно вызывающей стороне.
   • При ошибке. Отображает ошибки, возникшие во время обработки запроса, и политики, примененные к ошибкам.

   Совет

   Каждый шаг также показывает истекшее время с момента, как API Management получил запрос.

Включение трассировки для API

Для включения трассировки запроса к управлению API при использовании curl, клиента REST, например Visual Studio Code с расширением клиента REST или клиентского приложения, необходимо выполнить следующие действия. В настоящее время эти действия необходимо выполнить с помощью REST API API Management/c0>:

1. Получите токен отладки для отслеживания.
2. Добавьте значение токена в заголовок запроса Apim-Debug-Authorization в шлюз API Management.
3. Получите идентификатор трассировки в заголовке ответа Apim-Trace-Id.
4. Получите трассировку, соответствующую идентификатору трассировки.

Следуют подробные шаги.

1. Получите маркер отладки. Вызовите API List debug credentials шлюза управления API. В URI введите значение управляемый для управляемого шлюза экземпляра в облаке или идентификатор шлюза для самостоятельно размещённого шлюза. Например, чтобы получить трассировочные учетные данные для управляемого экземпляром шлюза, используйте запрос, аналогичный следующему примеру:

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

   В тексте запроса передайте полный идентификатор ресурса API, который требуется трассировать. Укажите purposes как tracing. По умолчанию учетный токен, возвращаемый в ответе, истекает через 1 час. В данных нагрузки можно указать другое значение. Срок действия ограничен не более 1 часа. Рассмотрим пример.

   {
       "credentialsExpireAfter": "PT1H",
       "apiId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}",
       "purposes": ["tracing"]
   }
   

   Примечание.

   apiId можно извлечь только из полного идентификатора ресурса, а не имени, отображаемого на портале Azure.

   Получить apiId:

   az apim api list --resource-group <resource-group> --service-name <service-name> -o table
   

   Учетные данные отладки возвращаются в ответе, как показано в следующем примере:

   {
         "token": "aid=api-name&......."
   }
   

2. Добавьте значение маркера в заголовок запроса. Чтобы включить трассировку для запроса к шлюзу API Management, отправьте значение токена в заголовке Apim-Debug-Authorization. Например, для трассировки вызова API Petstore, импортированного в предыдущем руководстве, можно использовать запрос, аналогичный следующему примеру:

   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&......."
   

3. Оцените ответ. Ответ может содержать один из следующих заголовков в зависимости от состояния маркера отладки:

   Заголовок ответа	Explanation
   Apim-Trace-Id	Действительный токен отладки. Значением является идентификатор трассировки, например: Apim-Trace-Id: 0123456789abcdef....
   Apim-Debug-Authorization-Expired	Срок действия токена истек. Заголовок содержит сведения о дате окончания срока действия.
   Apim-Debug-Authorization-WrongAPI	Маркер, полученный для другого API. Заголовок содержит сообщение об ошибке.

4. Получите трассировку. Передайте идентификатор трассировки, полученный на предыдущем шаге, в API шлюза List trace. Например, чтобы получить трассировку для управляемого шлюза, используйте запрос, аналогичный следующему примеру:

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

   В тексте запроса передайте идентификатор трассировки, полученный на предыдущем шаге.

   {
       "traceId": "0123456789abcdef...."
   }
   

   Текст ответа содержит данные трассировки для предыдущего запроса API к шлюзу. Трассировка похожа на ту, которую можно увидеть, отслеживая вызов на тестовой консоли портала.

Пример http-файла для расширения REST Client VS Code

Чтобы автоматизировать эти действия с расширением Visual Studio Code REST Client, можно использовать следующий пример .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
@apiId = // Api Id for which trace log is to be generated.

# @name login 
POST https://login.microsoftonline.com/{{tenantId}}/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
POST {{apiEndPoint}} HTTP/1.1
Host: {{externalHost}}
Apim-Debug-Authorization: {{debugToken}}
Ocp-Apim-Subscription-Key: {{subscriptionKey}}
Content-Type: application/json

{{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}}"
}

Для получения информации о настройке трассировки см. политику трассировки.

Сводка

Из этого руководства вы узнали, как:

Следующий шаг

Перейдите к следующему уроку.