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

APLICA-SE A: Todos os níveis de API Management

Este tutorial descreve como inspecionar, ou trace, o processamento de pedidos em Azure API Management. O rastreamento ajuda você a depurar e solucionar problemas de sua API.

Neste tutorial, irá aprender a:

Pré-requisitos

• Aprenda a terminologia Azure API Management.
• Complete a seguinte introdução rápida: Criar uma instância do Azure API Management.
• Conclua o seguinte tutorial: Importe e publique sua primeira API.

Rastrear uma chamada no portal do Azure

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. Inicia sessão no Azure portal e navega até à tua instância API Management.

2. Selecione APIs>APIs.

3. Selecione Petstore API na sua lista de APIs.

4. Selecione a guia Teste .

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

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

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

   Gorjeta

   Pode sobrescrever o valor de Ocp-Apim-Subscription-Key obtendo uma chave para outra subscrição no portal do Azure. 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 seguintes links para saltar para informações detalhadas de rastreamento: Entrada, Backend, Saída, Em Erro.

   

   • A caminho. Mostra o pedido original que a API Management recebeu do chamador e as políticas aplicadas ao pedido. Por exemplo, se você adicionou políticas em Tutorial: Transformar e proteger sua API, elas aparecerão aqui.
   • Backend. Mostra os pedidos que a API Management enviou para o backend da API e a resposta que recebeu.
   • De saída. Mostra as políticas aplicadas à resposta antes de enviar de volta ao chamador.
   • Em caso de erro. Mostra os erros que ocorreram durante o processamento do pedido e as políticas aplicadas a esses erros.

   Gorjeta

   Cada passo também mostra o tempo decorrido desde que a API Management recebeu o pedido.

Habilitar o rastreamento para uma API

São necessários os seguintes passos de alto nível para permitir o rastreamento de um pedido a API Management ao usar curl, um cliente REST como Visual Studio Code com a extensão REST Client, ou uma aplicação cliente. Atualmente, estes passos devem ser seguidos usando a API REST API Management:

1. Obtenha um token de depuração para rastreio.
2. Adicione o valor do token num cabeçalho de pedido Apim-Debug-Authorization para o Gateway do API Management.
3. Obtenha uma ID de rastreamento no cabeçalho da Apim-Trace-Id resposta.
4. Recupere o rastreamento correspondente ao identificador de rastreamento.

Seguem-se passos detalhados.

1. Obtenha um token de depuração. Chame a API List debug credentials do gateway API Management. No URI, insira gerido para o gateway gerido 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 gerido da instância, use um pedido semelhante ao seguinte exemplo:

   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 do pedido, passe o ID completo do recurso da API que pretende rastrear. Especifique purposes como tracing. Por padrão, a credencial do token devolvida na resposta expira após 1 hora. Pode especificar um valor diferente na carga útil. O prazo de validade é limitado a um máximo de 1 hora. Por exemplo:

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

   Nota

   O apiId só pode ser retirado do ID completo do recurso, não do nome apresentado na Azure portal.

   Obter apiId:

   az apim api list --resource-group <resource-group> --service-name <service-name> -o table
   

   A credencial de depuração é retornada na resposta, semelhante ao seguinte exemplo:

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

2. Adicione o valor do token num cabeçalho de pedido. Para permitir o rastreamento de um pedido para o gateway API Management, envie o valor do token num cabeçalho Apim-Debug-Authorization. Por exemplo, para rastrear uma chamada para a API Petstore que importou num tutorial anterior, pode usar um pedido semelhante ao seguinte exemplo:

   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. Avalia a resposta. A resposta pode conter um dos seguintes cabeçalhos, dependendo do estado do token de depuração:

   Cabeçalho em resposta	Explanation
   Apim-Trace-Id	Token de depuração válido. O valor é o ID do traço, tais como: Apim-Trace-Id: 0123456789abcdef....
   Apim-Debug-Authorization-Expired	O token expirou. O cabeçalho inclui informações sobre a data de validade.
   Apim-Debug-Authorization-WrongAPI	Token obtido para uma API diferente. O cabeçalho inclui uma mensagem de erro.

4. Recuperar o traço. Passe o ID de rastreio obtido no passo anterior para a API List trace do gateway. Por exemplo, para recuperar o rastreio do gateway gerido, use um pedido semelhante ao seguinte exemplo:

   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 rastreio da solicitação de API anterior do gateway. O rastreamento é semelhante ao rastreamento que você pode ver rastreando uma chamada no console de teste do portal.

Ficheiro http de exemplo para a extensão do cliente VS Code REST

Para ajudar a automatizar estes passos com a extensão Visual Studio Code REST Client, pode usar o seguinte exemplo .http file:

@subscriptionId = // Your subscription ID
@resourceGroup = // Your resource group
@apimName = // Your API Management service name
@clientId = // Client ID from an app registration for authentication
@clientSecret = // Client secret from app registration
@externalHost = // The host name of the App Gateway or the fully qualified gateway URL
@subscriptionKey = // API Management subscription key
@apiEndPoint = // API URL
@requestBody = // Data to send
@tenantId = // Tenant ID
@apiId = // Api Id for which trace log is to be generated.

# @name login 
POST https://login.microsoftonline.com/{{tenantId}}/oauth2/token
content-type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id={{clientId}}&client_secret={{clientSecret}}&resource=https%3A%2F%2Fmanagement.azure.com%2F
 
###
@authToken = {{login.response.body.$.access_token}}
###
# @name listDebugCredentials
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
Authorization: Bearer {{authToken}}

Content-Type: application/json
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/apis/{{apiId}}",
    "purposes": ["tracing"]
}
 
###
@debugToken = {{listDebugCredentials.response.body.$.token}}
 
###
# @name callApi
POST {{apiEndPoint}} HTTP/1.1
Host: {{externalHost}}
Apim-Debug-Authorization: {{debugToken}}
Ocp-Apim-Subscription-Key: {{subscriptionKey}}
Content-Type: application/json

{{requestBody}}
 
###
@traceId = {{callApi.response.headers.Apim-Trace-Id}}
 
###
# @name getTrace
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listTrace?api-version=2024-06-01-preview
Authorization: Bearer {{authToken}}
Content-Type: application/json
 
{
    "traceId": "{{traceId}}"
}

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

Resumo

Neste tutorial, ficou a saber como:

Próximo passo

Avance para o tutorial seguinte: