Tutorial: Depurar suas APIs usando o rastreamento de solicitações

APLICA-SE A: Todas as camadas de 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, irá aprender a:

Pré-requisitos

• Conhecer a terminologia da Gestão de API do Azure.
• Conclua o guia de início rápido seguinte: Criar uma instância da Gestão de API do Azure.
• Conclua o seguinte tutorial: Importe e publique 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 pressupõe que você importou uma API de exemplo em um tutorial anterior. Você pode seguir etapas semelhantes com uma API diferente que importou.

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

2. Selecione APIs>APIs.

3. Selecione Petstore API na sua lista de APIs.

4. Selecione o separador Teste.

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

6. No parâmetro petId Query, digite 1.

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

   Gorjeta

   Você pode substituir o valor de Ocp-Apim-Subscription-Key recuperando uma chave para outra assinatura no portal. Selecione Subscrições e abra o menu de contexto (...) para outra subscrição. Selecione Mostrar/ocultar chaves e copie uma das chaves. Você também pode regenerar 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 Rastrear.

Revisar informações de rastreamento

1. Após a conclusão da chamada, vá para a guia Rastrear na resposta HTTP.

2. Selecione qualquer um dos links a seguir para ir para informações detalhadas de rastreamento: Entrada, Back-end, Saída, Erro Ativado.

   

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

   • Back-end - Mostra as solicitações que o Gerenciamento de API enviou para o back-end da API e a resposta recebida.

   • Saída - Mostra as políticas aplicadas à resposta antes de enviar de volta ao chamador.

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

   Gorjeta

   Cada passo mostra também o tempo decorrido desde que o pedido é recebido através da Gestão de API.

Habilitar o rastreamento para uma API

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

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

Seguem-se passos detalhados.

1. Obter uma credencial de token - Chame a API de credenciais de depuração de lista do gateway de gerenciamento de API. No URI, digite "gerenciado" para o gateway gerenciado da instância na nuvem ou o 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 de 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 na carga útil. 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. Adicionar o valor do token em um cabeçalho de solicitação - Para habilitar o rastreamento de uma solicitação para o gateway de 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 contém um dos seguintes cabeçalhos:

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

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

   • Se o token tiver expirado, a resposta incluirá um Apim-Debug-Authorization-Expired cabeçalho com informações sobre a data de validade.

   • Se o token foi obtido para uma API diferente, a resposta inclui um Apim-Debug-Authorization-WrongAPI cabeçalho com uma mensagem de erro.

4. Recuperar o rastreamento - Passe a ID de rastreamento obtida na etapa anterior para a API de rastreamento de lista 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 para a 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 obter informações sobre como personalizar informações de rastreamento, consulte a política de rastreamento .

Próximos passos

Neste tutorial, ficou a saber como:

Avance para o tutorial seguinte: