Бөлісу құралы:

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

ПРИМЕНЯЕТСЯ К: все уровни управления API

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

Совет

Команды API могут использовать эту функцию в рабочих областях. Рабочие области предоставляют изолированный административный доступ к API и собственные среды выполнения API.

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

  • Отслеживание примера вызова в тестовой консоли
  • Просмотр этапов обработки запросов.
  • Включение трассировки для API

Снимок экрана: инспектор API.

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

Внимание

  • Управление API больше не поддерживает подписки для трассировки или заголовок Ocp-Apim-Trace.
  • Для повышения безопасности API можно теперь включить трассировку на уровне отдельного API путем получения маркера с ограниченным сроком действия с помощью REST API управления API и передачи маркера в запросе к шлюзу. Дополнительные сведения см. в разделе "Включение трассировки API".
  • Будьте осторожны при включении трассировки, так как она может разглашать конфиденциальную информацию в данных трассировки. Убедитесь, что у вас есть соответствующие меры безопасности для защиты данных трассировки.

Трассировка звонка в портале

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

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

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

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

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

    Просмотр трассировки ответа

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

    • В разделе Внутренние отображаются запросы, отправленные службой Управления API в серверную часть API, и полученный ответ.

    • В разделе Исходящие отображаются все политики, примененные к ответу перед отправкой обратно вызывающей стороне.

    • При ошибке — показывает ошибки, возникшие во время обработки запроса, и политики, примененные к ошибкам.

    Совет

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

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

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

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

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

Примечание.

  • Для выполнения этих шагов требуется версия REST API управления API 2023-05-01-preview или более поздняя. Чтобы вызвать REST API, вы должны иметь роль Участник или выше в экземпляре управления API.
  • Сведения о проверке подлинности в REST API см. в справочнике по REST API Azure.

  1. Получение токена отладки — вызов API Список учетных данных для отладки в шлюзе управления 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 можно извлечь только из него, а не из имени, отображаемого на портале.

    Получить apiId:

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

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

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

  2. Добавьте значение маркера в заголовок запроса. Чтобы включить трассировку запроса к шлюзу Управление API, отправьте значение маркера в заголовке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. Оцените ответ. Ответ может содержать один из следующих заголовков в зависимости от состояния маркера отладки:

    • Если маркер отладки действителен, ответ включает заголовок Apim-Trace-Id, значение которого является идентификатором трассировки, например:

      Apim-Trace-Id: 0123456789abcdef....

    • Если срок действия маркера отладки истек, ответ содержит Apim-Debug-Authorization-Expired заголовок со сведениями о дате окончания срока действия.

    • Если маркер отладки был получен для другого API, ответ содержит Apim-Debug-Authorization-WrongAPI заголовок с сообщением об ошибке.

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

    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 для расширения VS Code REST Client

Чтобы автоматизировать эти шаги с помощью расширения 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}}"
}

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

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

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

  • Отслеживание примера вызова в тестовой консоли
  • Просмотр этапов обработки запросов.
  • Включение трассировки для API

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

Использовать изменения

  • Last updated on