API Gateway:Troubleshoot issues that occur during API debugging

Ler informações de erro nos cabeçalhos de resposta

O API Gateway retorna uma resposta para cada requisição recebida. Cabeçalhos com o prefixo X-Ca contêm informações de diagnóstico fornecidas pelo API Gateway. Os três cabeçalhos mais úteis para solução de problemas são:

• X-Ca-Error-Code: código do erro. Presente apenas quando o API Gateway rejeita a requisição.

• X-Ca-Request-Id: ID exclusivo da requisição. O API Gateway gera e retorna esse ID para todas as requisições. Registre-o tanto no cliente quanto no serviço de backend, pois ele é essencial para rastreamento e solução de problemas.

• X-Ca-Error-Message: mensagem de erro. Retornada junto com X-Ca-Error-Code quando há falha na requisição.

Consultar detalhes da chamada por X-Ca-Request-Id

Use X-Ca-Error-Code e X-Ca-Error-Message para identificar a causa inicial da falha. Três cenários são possíveis:

Erros reportados pelo API Gateway

Se X-Ca-Error-Code não estiver vazio, o API Gateway rejeitou a requisição. O código de erro é uma string de seis caracteres. Consulte X-Ca-Error-Message para obter uma breve descrição da causa. Para a lista completa de códigos de erro, consulte Códigos de erro.

Erros reportados pelo serviço de backend

Quando o código de status HTTP não for 200 e X-Ca-Error-Code estiver vazio, o API Gateway encaminhou a requisição com sucesso, mas o serviço de backend retornou uma resposta diferente de 200. Verifique a lógica do seu serviço de backend. Se você adquiriu a API no Alibaba Cloud Marketplace, entre em contato com o provedor do serviço.

Requisição bem-sucedida

Se o código de status HTTP for 200, o API Gateway encaminhou a requisição e o serviço de backend retornou uma resposta de sucesso.

Para uma investigação mais detalhada, use X-Ca-Request-Id para consultar logs detalhados da requisição no Simple Log Service e visualizar os resultados no console do API Gateway. Também é possível compartilhar esse ID com o suporte técnico.

Para pesquisar uma requisição no console:

1. Faça login no console do API Gateway.

2. No painel de navegação à esquerda, clique em Call APIs > Troubleshooting. Insira a Region of the API Gateway e o X-Ca-Request-Id e clique em Query.

Obter logs de rastreamento

Após enviar uma requisição na página de depuração de API, visualize o log de rastreamento correspondente. Esse log captura todo o ciclo de vida da requisição: a requisição que o API Gateway recebe do cliente, as etapas de processamento interno do API Gateway, a requisição enviada ao serviço de backend, a resposta do backend e a resposta final retornada ao cliente.

Se estiver usando uma conta de usuário RAM ou uma função assumida, selecione Record Trace log antes de enviar a requisição. A conta também precisa ter a permissão apigateway:AcquireGatewayToken concedida pela conta raiz para a instância onde a API está localizada. Para mais informações sobre concessão de permissões, consulte Usar o RAM para gerenciar APIs.

O exemplo a seguir mostra a declaração de política que concede essa permissão:

{
 "Version": "1",
 "Statement": [
 {
 "Effect": "ALLOW",
 "Action": "apigateway:AcquireGatewayToken",
 "Resource": "acs:apigateway:{#regionId}:{#accountId}:instance/{#InstanceId}"
 }
 ]
}
# The {#} symbol indicates a variable that you must replace with an actual value.

Analisar erros usando a aba Diagnostics

Na seção Call information da aba Diagnostics, inspecione os logs de qualquer chamada. Dois campos de latência permitem identificar imediatamente se a falha teve origem no API Gateway ou no serviço de backend:

• TotalLatency: tempo total decorrido desde o recebimento da requisição do cliente pelo API Gateway até o envio da resposta completa de volta ao cliente.

• ServiceLatency: intervalo entre o envio da requisição ao serviço de backend pelo API Gateway e o recebimento da resposta completa.

Se ServiceLatency for 0, o API Gateway interceptou a requisição e ela nunca chegou ao serviço de backend. Quando ServiceLatency for maior que 0, a requisição alcançou o serviço de backend.

O log também registra timestamps de I/O para cada etapa do caminho da requisição:

Para mais detalhes sobre os campos de log, consulte Usar o Simple Log Service para gerenciar logs de chamadas de API.