Compartilhar via

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.

Dica

As equipes de API podem usar esse recurso nos workspaces. Os workspaces fornecem acesso administrativo isolado às APIs e aos respectivos ambientes de runtime de API.

Neste tutorial, você aprenderá a:

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

Captura de tela mostrando a inspeção da API.

Pré-requisitos

Importante

  • O Gerenciamento de API não dá mais suporte a assinaturas para rastreamento ou ao cabeçalho Ocp-Apim-Trace.
  • Para melhorar a segurança da API, o rastreamento agora pode ser habilitado no nível de uma API individual obtendo um token com limite de tempo usando a API REST do 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

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 ConsultapetId, 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 (...) de outra 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 Trace.

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.

    Examinar o rastreamento de resposta

    • Inbound: mostra a solicitação original recebida pelo Gerenciamento de API do solicitante 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 de enviar de volta ao chamador.

    • Ao ocorrer um 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 um token de depuração 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.

Observação

  • Essas etapas exigem a versão prévia de 01/05/2023 ou posterior da API REST do Gerenciamento de API. Você deve ter atribuída a função de Colaborador ou superior na instância de Gerenciamento de API para chamar a API REST.
  • Para obter informações sobre como autenticar na API REST, confira Referência da API REST do Azure.

  1. Obter um token de depuração – Chame a API Lista de credenciais de depuração do gateway de Gerenciamento de API. No 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 é possível especificar um valor diferente no payload. Observe que o tempo de expiração é 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"]
}

    Observação

    O apiId só pode ser extraído da ID de recurso completa, não do nome exibido no 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 à 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. Avaliar a resposta: a resposta pode conter um dos seguintes cabeçalhos, dependendo do estado do token de depuração:

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

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

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

    • Se o token de depuração 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 obter o rastreamento do gateway gerenciado, use a seguinte solicitação:

    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 traço é semelhante ao que você pode ver ao rastrear uma chamada no console de teste do portal.

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

Para ajudar a automatizar estas etapas com a extensão Cliente REST do Visual Studio Code, você pode usar o seguinte arquivo de exemplo .http :

@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
 
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
curl -k -H "Apim-Debug-Authorization: {{debugToken}}" -H 'Host: {{externalHost}}' -H 'Ocp-Apim-Subscription-Key: {{subscriptionKey}}' -H 'Content-Type: application/json' '{{apiEndPoint}}' -d '{{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 saber como personalizar informações de rastreamento, consulte a política de rastreamento.

Próximas etapas

Neste tutorial, você aprendeu a:

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

Prosseguir para o próximo tutorial:

Usar revisões

  • Last updated on