Руководство. Отладка API с помощью трассировки запросов
ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API
В этом учебнике описано, как проверить (выполнить трассировку) обработку запросов в службе Управления API. Трассировка помогает отлаживать и устранять неполадки с API.
В этом руководстве описано следующее:
- Трассировка примера вызова в тестовой консоли
- Просмотр этапа обработки запроса.
- Включение трассировки для API
Необходимые компоненты
- Ознакомьтесь с терминологией службы управления API в Azure.
- Выполните задачи в кратком руководстве по созданию экземпляра службы управления API Azure.
- Выполните следующее руководство. Импорт и публикация первого API.
Внимание
- Управление API трассировке запросов с помощью Заголовок Ocp-Apim-Trace в запросе и использование значения заголовка ответа Ocp-Apim-Trace-Location не рекомендуется.
- Чтобы повысить безопасность, теперь трассировку можно включить на уровне отдельного API, получив ограниченный по времени маркер с помощью REST API Управление API и передав маркер в запросе шлюзу. Дополнительные сведения см. в разделе "Включение трассировки API".
- Следите за включением трассировки, так как она может предоставлять конфиденциальную информацию в данных трассировки. Убедитесь, что у вас есть соответствующие меры безопасности для защиты данных трассировки.
Трассировка вызова на портале
Войдите на портал Azure и перейдите к своему экземпляру службы Управления API.
Выберите Интерфейсы API.
В списке API выберите Demo Conference API.
Откройте вкладку Тест.
Щелкните операцию GetSpeakers.
При необходимости проверьте значение заголовка Ocp-Apim-Subscription-Key, используемого в запросе, щелкнув значок глаза.
Совет
Вы можете переопределить значение Ocp-Apim-Subscription-Key, получив ключ для другой подписки на портале. Выберите Подписки и откройте контекстное меню (...) другой подписки. Выберите Показать или скрыть ключи и скопируйте один из ключей. При необходимости вы также можете повторно создать ключи. Затем в тестовой консоли выберите + Добавить заголовок, чтобы добавить заголовок Ocp-Apim-Subscription-Key с новым значением ключа.
Выберите Трассировка.
Просмотр сведений о трассировке
После завершения вызова перейдите на вкладку Трассировка в разделе HTTP-ответ.
Щелкните любую из следующих ссылок, чтобы перейти к подробным сведениям о трассировке: Входящие, Внутренние, Исходящие, При ошибке.
В разделе Входящие отображаются исходный запрос, полученный службой Управления API от вызывающего объекта, и примененные к запросу политики. Например, они отобразятся здесь, если вы добавили политики при работе со статьей Учебник. Преобразование и защита API.
В разделе Внутренние отображаются запросы, отправленные службой Управления API в серверную часть API, и полученный ответ.
В разделе Исходящие отображаются все политики, примененные к ответу перед отправкой обратно вызывающему объекту.
При ошибке — показывает ошибки, возникшие во время обработки запроса, и политики, примененные к ошибкам.
Совет
Для каждого шага также показано время, прошедшее с момента получения запроса службой управления API.
Включение трассировки для API
Вы можете включить трассировку для API при выполнении запросов на Управление API с помощью curl
клиента REST, например Visual Studio Code с расширением клиента REST или клиентского приложения.
Включите трассировку, выполнив следующие действия, используя вызовы к REST API Управление API.
Примечание.
Для выполнения следующих действий требуется Управление API REST API версии 2023-05-01-preview или более поздней версии. Для вызова REST API необходимо назначить участника или более высокую роль в экземпляре Управление 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 час, но можно указать другое значение в полезных данных.{ "credentialsExpireAfter": PT1H, "apiId": "<API resource ID>", "purposes": ["tracing"] }
Учетные данные маркера возвращаются в ответе, как показано ниже.
{ "token": "aid=api-name&p=tracing&ex=......." }
Чтобы включить трассировку запроса к шлюзу Управление 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=......."
В зависимости от маркера ответ содержит разные заголовки:
- Если маркер действителен, ответ содержит
Apim-Trace-Id
заголовок, значение которого является идентификатором трассировки. - Если срок действия маркера истек, ответ содержит
Apim-Debug-Authorization-Expired
заголовок со сведениями о дате окончания срока действия. - Если маркер был получен для неправильного API, ответ содержит
Apim-Debug-Authorization-WrongAPI
заголовок с сообщением об ошибке.
- Если маркер действителен, ответ содержит
Чтобы получить трассировку, передайте идентификатор трассировки, полученный на предыдущем шаге , в 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": "<trace ID>" }
Текст ответа содержит данные трассировки для предыдущего запроса API к шлюзу. Трассировка похожа на трассировку, которую можно увидеть, трассировка вызова в тестовой консоли портала.
Сведения о настройке сведений о трассировки см. в политике трассировки .
Следующие шаги
Из этого руководства вы узнали, как:
- Трассировка примера вызова.
- Просмотр этапа обработки запроса.
- Включение трассировки для API
Перейдите к следующему руководству: