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

APLICA-SE A: todas as camadas do Gerenciamento de API

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

Siga estas etapas para rastrear uma solicitação de API no console de teste no portal. Este exemplo assume que você importou uma API de amostra em um tutorial anterior. Você pode seguir etapas semelhantes com uma API diferente que você importou.

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

2. Selecione APIs>APIs.

3. Selecione a API Petstore da sua lista de APIs.

4. Selecione a guia Testar.

5. Selecione a operação Encontrar animal de estimação por ID.

6. No parâmetro de consulta petId, insira 1.

7. 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.

8. 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

As seguintes etapas de alto nível são necessárias para habilitar o rastreamento de uma solicitação para o Gerenciamento de API ao usar curl, um cliente REST como o Visual Studio Code com a extensão REST Client ou um aplicativo cliente. Atualmente, essas etapas devem ser seguidas usando a API REST do Gerenciamento de API:

1. Obter uma credencial de token para rastreamento.
2. Adicione o valor do token em um cabeçalho de solicitação Apim-Debug-Authorization para o gateway do Gerenciamento de API.
3. Obter uma ID de rastreamento no cabeçalho de resposta Apim-Trace-Id.
4. Recuperar o rastreamento correspondente à ID de rastreamento.

Etapas detalhadas seguem.

1. Obter uma credencial de token - Chame a API Listar credenciais de depuração do gateway do Gerenciamento de API. Na URI, insira "gerenciado" para o gateway gerenciado da instância na nuvem ou a ID do gateway para um gateway auto-hospedado. Por exemplo, para obter credenciais de rastreamento para o gateway gerenciado da instância, use uma solicitação 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. Por exemplo:

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

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

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

2. Adicione o valor do token em um cabeçalho de solicitação - Para habilitar o rastreamento de uma solicitação para o gateway do Gerenciamento de API, envie o valor do token em um Apim-Debug-Authorization cabeçalho. Por exemplo, para rastrear uma chamada para a API Petstore que você importou em um tutorial anterior, você pode usar uma solicitação semelhante à seguinte:

   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. Dependendo do token, a resposta conterá um dos seguintes cabeçalhos:

   • Se o token for válido, a resposta incluirá um cabeçalho Apim-Trace-Id cujo valor é a ID de rastreamento, semelhante ao seguinte:

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

   • 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 uma API diferente, a resposta incluirá um cabeçalho Apim-Debug-Authorization-WrongAPI com uma mensagem de erro.

4. Recuperar o rastreamento - Passe a ID de rastreamento obtido na etapa anterior para a API Listar rastreamento do gateway. Por exemplo, para recuperar o rastreamento para o gateway gerenciado, use uma solicitação 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": "0123456789abcdef...."
   }
   

   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: