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

Artigo
05/07/2024

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:

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

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.

Importante

O rastreamento de solicitações do 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 por tempo limitado usando a API REST de Gerenciamento de API e passando o token em uma solicitação para o gateway. Para obter detalhes, consulte Habilitar o rastreamento de uma API.
Tenha cuidado ao ativar o rastreamento, pois ele pode expor informações confidenciais nos dados de rastreamento. Certifique-se de que tem em vigor as medidas de segurança adequadas para proteger os dados de rastreio.

Rastrear uma chamada no portal

Entre no portal do Azure e navegue até sua instância de Gerenciamento de API.
Selecione APIs.
Selecione Demo Conference API na sua lista de APIs.
Selecione o separador Teste.
Selecione a operação GetSpeakers.
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.
Selecione Rastrear.

Revisar informações de rastreamento

Após a conclusão da chamada, vá para a guia Rastrear na resposta HTTP.
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

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

Habilite o rastreamento pelas etapas a seguir usando chamadas para a API REST de Gerenciamento de API.

Nota

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

Obtenha credenciais de rastreamento chamando a API de credenciais de depuração de lista. Passe o ID do gateway no URI ou use "gerenciado" para o gateway gerenciado da instância na nuvem. Por exemplo, para obter 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 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.
```
{
    "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 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 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 incluirá um Apim-Trace-Id cabeçalho cujo valor é a ID de rastreamento.
- 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 API errada, a resposta inclui um Apim-Debug-Authorization-WrongAPI cabeçalho com uma mensagem de erro.
Para recuperar o rastreamento, passe a ID de rastreamento obtida na etapa anterior para a API de rastreamento de lista para o gateway. Por exemplo, para recuperar o 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/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 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:

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

Avance para o tutorial seguinte:

Usar revisões

Partilhar via