Partilhar via

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

  • Artigo

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

Captura de tela mostrando o inspetor da API.

Pré-requisitos

Importante

  • O Gerenciamento de API não suporta mais assinaturas para rastreamento ou o 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 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

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.

    Rastrear respostas de revisão

    • 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.

Nota

  • Essas etapas 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.
  • Para obter informações sobre como autenticar na API REST, consulte Referência da API REST do Azure.

  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:

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

Avance para o tutorial seguinte:

Usar revisões