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

ОБЛАСТЬ ПРИМЕНЕНИЯ: Потребление | Разработчик | Базовый | Стандартный | Премиум

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

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

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

Примечание.

В настоящее время трассировка запросов API не поддерживается на уровнях "Базовый" версии 2 и "Стандартный" версии 2.

Необходимые компоненты

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

Внимание

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

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

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

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

3. В списке API выберите Demo Conference API.

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

5. Щелкните операцию GetSpeakers.

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

   Совет

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

7. Выберите Трассировка.

Просмотр сведений о трассировке

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

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

   

   • В разделе Входящие отображаются исходный запрос, полученный службой Управления 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.

1. Получение учетных данных трассировки путем вызова 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=......."
   }
   

2. Чтобы включить трассировку запроса к шлюзу Управление 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=......."
   

3. В зависимости от маркера ответ содержит разные заголовки:

   • Если маркер действителен, ответ содержит Apim-Trace-Id заголовок, значение которого является идентификатором трассировки.
   • Если срок действия маркера истек, ответ содержит 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": "<trace ID>"
   }
   

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

Сведения о настройке сведений о трассировки см. в политике трассировки .

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

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

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

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

Использование редакций