Visão geral sobre a solução de problemas
Nesta página, você encontra informações gerais sobre solução de problemas do gateway de API.
Não é possível executar os comandos "gcloud api-gateway"
Para executar os comandos gcloud api-gateway ...
, é necessário atualizar a
Google Cloud CLI e ativar os serviços necessários do Google.
Consulte Como configurar o ambiente de desenvolvimento para saber mais.
O comando "gcloud api-gateway api-configs create" diz que a conta de serviço não existe.
Se você executar o comando gcloud api-gateway api-configs create ...
e receber
um erro no formulário:
ERROR: (gcloud.api-gateway.api-configs.create) FAILED_PRECONDITION: Service Account "projects/-/serviceAccounts/service_account_email" does not exist
Execute novamente o comando, mas desta vez inclua a opção --backend-auth-service-account
para especificar explicitamente o endereço de e-mail da conta de serviço a ser usada:
gcloud api-gateway api-configs create CONFIG_ID \ --api=API_ID --openapi-spec=API_DEFINITION \ --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
Verifique se você já atribuiu as permissões necessárias à conta de serviço, conforme descrito em Como configurar o ambiente para desenvolvedores.
Como determinar a origem das respostas de erro da API
Se as solicitações para a API implantada resultarem em um erro (códigos de status HTTP
400
a 599
), talvez não fique claro na
resposta se o erro se origina do gateway ou do back-end.
Para determinar isso:
Acesse a página "Análise de registros" e selecione seu projeto.
Filtre para o recurso de gateway relevante usando a seguinte consulta de registro:
resource.type="apigateway.googleapis.com/Gateway" resource.labels.gateway_id="GATEWAY_ID" resource.labels.location="GCP_REGION"
Em que:
- GATEWAY_ID especifica o nome do gateway.
- GCP_REGION é a Google Cloud região do gateway implantado.
Encontre a entrada de registro que corresponde à resposta de erro HTTP que você quer investigar. Por exemplo, filtre por
httpRequest.status
.Inspecione o conteúdo do campo
jsonPayload.responseDetails
.
Se o valor do campo jsonPayload.responseDetails
for
"via_upstream"
, a resposta de erro será originada do
back-end, e você precisará resolver o problema diretamente. Se for qualquer
outro valor, a resposta de erro é originada pelo gateway. Consulte as
seções a seguir deste documento para mais dicas de solução de problemas.
A solicitação da API retorna um erro HTTP 403
Se uma solicitação para uma API implantada retornar um erro HTTP 403
para o
cliente da API, significa que o URL solicitado é válido, mas o acesso é proibido por algum
motivo.
Uma API implantada tem as permissões associadas aos papéis concedidos à conta de serviço que você usou quando criou a configuração da API. Normalmente, o motivo do erro HTTP
403
é que a conta de serviço não tem as permissões
necessárias para acessar o serviço de back-end.
Se você definiu a API e o serviço de back-end no mesmo projeto do Google Cloud,
verifique se a conta de serviço tem o papel Editor
atribuído a ela ou o papel necessário para acessar o serviço de back-end. Por exemplo, se o serviço de back-end
for implementado usando as funções do Cloud Run, verifique se a conta de serviço
tem o papel Cloud Function Invoker
atribuído a ela.
A solicitação da API retorna um erro HTTP 401
ou 500
Se uma solicitação para uma API implantada retornar um erro HTTP 401
ou
500
para o cliente da API, poderá haver um problema ao usar a
conta de serviço usada ao criar a configuração da API para chamar o serviço de back-end.
Uma API implantada tem as permissões associadas aos papéis concedidos à conta de serviço que você usou ao criar a configuração da API. A conta de serviço é verificada para garantir que ela exista e possa ser usada pelo gateway da API quando a API for implantada.
Se a conta de serviço for excluída ou desativada após a implantação do gateway, talvez a seguinte sequência de eventos ocorra:
Imediatamente após a exclusão ou desativação da conta de serviço, você poderá ver respostas HTTP 401 nos registros do gateway. Se o campo
response_code_details
estiver definido como"via_upstream"
na entrada de registrojsonPayload
, isso indica que excluir ou desativar a conta de serviço é a causa do erro.Também é possível encontrar um erro HTTP
500
sem nenhuma entrada de registro correspondente nos registros do gateway de API. Se não houver solicitações para o gateway imediatamente após a exclusão ou desativação da conta de serviço, talvez você não veja as respostas HTTP 401, mas os erros HTTP500
sem os registros correspondentes do gateway de API são uma indicação de que a conta de serviço do gateway talvez não esteja mais ativa.
Solicitações de API com alta latência
Assim como o Cloud Run e as funções do Cloud Run, o API Gateway está sujeito à latência de "inicialização a frio". Se o gateway não receber tráfego por 15 a 20 minutos, as solicitações feitas para o gateway nos primeiros 10 a 15 segundos da inicialização a frio terão latência de 3 a 5 segundos.
Se o problema persistir após o período inicial de "aquecimento", verifique os registros de solicitação dos serviços de back-end que você configurou na API Config. Por exemplo, se o serviço de back-end for implementado usando funções do Cloud Run, verifique as entradas do Cloud Logging do registro de solicitação da função do Cloud associado.
Não é possível ver as informações de registro
Quando a API está respondendo corretamente, mas os registros não têm dados, isso significa que você não ativou todos os serviços do Google exigidos pelo gateway de API.
A API Gateway requer a ativação dos seguintes serviços do Google:
Nome | Nome |
---|---|
apigateway.googleapis.com |
API Gateway |
servicemanagement.googleapis.com |
Service Management API |
servicecontrol.googleapis.com |
API Service Control |
Para confirmar que os serviços obrigatórios estão ativados:
gcloud services list
Se você não encontrar os serviços necessários listados, ative-os:
gcloud services enable apigateway.googleapis.comgcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
Para mais informações sobre os serviços do gcloud
, consulte
serviços gcloud
.