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 \
  --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 própria resposta se o erro se originou no gateway ou no back-end. Para determinar isso:

Acesse a página "Análise de registros" e selecione seu projeto.

Acessar a Análise de registros
Filtre 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 vai ter origem no seu back-end, e você precisará resolver o problema diretamente nele. Se for qualquer outro valor, a resposta de erro vai vir do 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 o Cloud Run functions, 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 quando criou 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 jsonPayload.responseDetails estiver definido como "via_upstream" na entrada de registro jsonPayload, isso indica que excluir ou desativar a conta de serviço é a causa do erro.
Também é possível ver 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 depois que a conta de serviço for excluída ou desativada, talvez você não veja as respostas HTTP 401, mas os erros HTTP 500 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.

Se o back-end da solicitação com falha for outra API Google Cloud (como bigquery.googleapis.com), você vai encontrar respostas HTTP 401 nos registros do gateway com o campo jsonPayload.responseDetails definido como "via_upstream". Isso acontece porque o gateway de API faz a autenticação em back-ends com um token de ID, enquanto outras APIs Google Cloud exigem um token de acesso.

Solicitações de API de alta latência

Assim como o Cloud Run e o Cloud Run functions, 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 a ele nos primeiros 10 a 15 segundos da inicialização a frio terão uma 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ço de back-end que você configurou na configuração da API. 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 associada.

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

Use os comandos a seguir para ativar esses serviços:

gcloud services enable apigateway.googleapis.com
gcloud 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.