Tutorial: Depure suas APIs usando o rastreamento de solicitação

APLICA-SE A: Consumo | Desenvolvedor | Básico | Standard | Premium

Este tutorial descreve como inspecionar (rastrear) o processamento de solicitações no Gerenciamento de API do Azure. O rastreamento ajuda você a depurar e solucionar problemas de sua API.

Neste tutorial, você aprenderá a:

Pré-requisitos

• Conheça a terminologia do Gerenciamento de API do Azure.
• Conclua o seguinte guia de início rápido: Criar uma instância do Gerenciamento de API do Azure.
• Conclua o seguinte tutorial: Importar e publicar sua primeira API.

Rastrear uma chamada no portal

1. Entre no portal do Azure e navegue até a sua instância do Gerenciamento de API.

2. Selecione APIs.

3. Selecione API de Conferência de Demonstração em sua lista de APIs.

4. Selecione a guia Testar.

5. Selecione a operação GetSpeakers.

6. Opcionalmente, verifique o valor do cabeçalho Ocp-Apim-Subscription-Key usado na solicitação selecionando o ícone "olho".

   Dica

   Você pode substituir o valor de Ocp-Apim-Subscription-Key recuperando uma chave para outra assinatura no portal. Selecione Assinaturas e abra o menu de contexto (...) da sua assinatura. Selecione Mostrar/ocultar chaves e copie uma das chaves. Regenere também as chaves, se necessário. Em seguida, no console de teste, selecione + Adicionar cabeçalho para adicionar um cabeçalho Ocp-Apim-Subscription-Key com o novo valor de chave.

7. Selecione Rastreamento.

Examinar as informações de rastreamento

1. Depois que a chamada for concluída, acesse a guia Rastreamento na resposta HTTP.

2. Selecione um dos seguintes links para ir para as informações detalhadas de rastreamento: Entrada, Back-end, Saída e Erro.

   

   • Entrada: mostra a solicitação original recebida pelo Gerenciamento de API do chamador e as políticas aplicadas à solicitação. Por exemplo, se você adicionou políticas no Tutorial: Transformar e proteger sua API, elas aparecerão aqui.

   • Back-end: mostra as solicitações enviadas pelo Gerenciamento de API ao back-end de API e a resposta recebida.

   • Saída: mostra as políticas aplicadas à resposta antes do novo envio ao chamador.

   • Erro – Mostra os erros que ocorreram durante o processamento da solicitação e as políticas aplicadas aos erros.

   Dica

   Cada etapa também mostra o tempo decorrido desde quando a solicitação foi recebida pelo Gerenciamento de API.

Habilitar o rastreamento para uma API

Você pode habilitar o rastreamento de uma API ao fazer solicitações para o Gerenciamento de API usando curl, um cliente REST, como o Visual Studio Code com a extensão REST Client, ou um aplicativo cliente.

Habilite o rastreamento seguindo as etapas a seguir usando chamadas para a API REST do Gerenciamento de API.

1. Obtenha as credenciais de rastreamento chamando a API List debug credentials. Passe a ID do gateway no URI ou use "gerenciado" para o gateway gerenciado da instância na nuvem. Por exemplo, para obter as credenciais de rastreamento para o gateway gerenciado, use uma chamada semelhante à seguinte:

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

   No corpo da solicitação, passe a ID do recurso completa da API que você deseja rastrear e especifique purposes como tracing. Por padrão, a credencial de token retornada na resposta expira após 1 hora, mas você pode especificar um valor diferente no conteúdo.

   {
       "credentialsExpireAfter": PT1H,
       "apiId": "<API resource ID>",
       "purposes": ["tracing"]
   }
   

   A credencial de token é retornada na resposta, semelhante à seguinte:

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

2. Para habilitar o rastreamento de uma solicitação para o gateway do Gerenciamento de API, envie o valor do token em um cabeçalho Apim-Debug-Authorization. Por exemplo, para rastrear uma chamada para a API de conferência de demonstração, use uma chamada semelhante à seguinte:

   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. Dependendo do token, a resposta contém cabeçalhos diferentes:

   • Se o token for válido, a resposta inclui um cabeçalho Apim-Trace-Id cujo valor é a ID de rastreamento.
   • Se o token tiver expirado, a resposta incluirá um cabeçalho Apim-Debug-Authorization-Expired com informações sobre a data de validade.
   • Se o token foi obtido para a API errada, a resposta inclui um cabeçalho Apim-Debug-Authorization-WrongAPI com uma mensagem de erro.

4. Para recuperar o rastreamento, passe a ID de rastreamento obtida na etapa anterior para a API List trace para o gateway. Por exemplo, para recuperar o rastreamento do gateway gerenciado, use uma chamada semelhante à seguinte:

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

   No corpo da solicitação, passe a ID de rastreamento obtida na etapa anterior.

   {
       "traceId": "<trace ID>"
   }
   

   O corpo da resposta contém os dados de rastreamento da solicitação de API anterior para o gateway. O rastreamento é semelhante ao rastreamento que você pode ver rastreando uma chamada no console de teste do portal.

Para saber como personalizar informações de rastreamento, consulte a política de rastreamento.

Próximas etapas

Neste tutorial, você aprendeu a:

Prosseguir para o próximo tutorial: