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

Artigo
05/08/2024

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:

Rastrear uma chamada de exemplo no console de teste
Examinar as etapas de processamento de solicitações
Habilitar o rastreamento para uma API

Observação

Atualmente, não há suporte para rastreamento de solicitações de API nas camadas Básico v2 e Standard v2.

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.

Importante

O rastreamento da solicitação de Gerenciamento de API usando o cabeçalho Ocp-Apim-Trace em uma solicitação e usando o valor do cabeçalho de resposta Ocp-Apim-Trace-Location está sendo preterido.
Para melhorar a segurança, o rastreamento agora pode ser habilitado no nível de uma API individual, obtendo um token limitado usando a API REST de Gerenciamento de API e passando o token em uma solicitação para o gateway. Para obter detalhes, confira Habilitar o rastreamento de uma API.
Tome cuidado ao habilitar o rastreamento, pois ele pode expor informações confidenciais nos dados de rastreamento. Verifique se você tem as medidas de segurança apropriadas em vigor para proteger os dados de rastreamento.

Rastrear uma chamada no portal

Entre no portal do Azure e navegue até a sua instância do Gerenciamento de API.
Selecione APIs.
Selecione API de Conferência de Demonstração em sua lista de APIs.
Selecione a guia Testar.
Selecione a operação GetSpeakers.
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.
Selecione Rastreamento.

Examinar as informações de rastreamento

Depois que a chamada for concluída, acesse a guia Rastreamento na resposta HTTP.
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.

Observação

As etapas a seguir exigem a API REST do Gerenciamento de API versão 2023-05-01-preview ou posterior. Você deve receber a função Colaborador ou superior na instância do Gerenciamento de API para chamar a API REST.

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=......."
}
```
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=......."
```
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.
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:

Rastrear um exemplo de chamada
Examinar as etapas de processamento de solicitações
Habilitar o rastreamento para uma API

Prosseguir para o próximo tutorial:

Usar revisões

Compartilhar via