Поделиться через

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

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

Подробные действия.

Примечание.

  • Для этих действий требуется Управление API REST 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 час, но можно указать другое значение в полезных данных. Например:

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

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

    {
      "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 к шлюзу. Трассировка похожа на трассировку, которую можно увидеть, трассировка вызова в тестовой консоли портала.

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

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

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

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

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

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