Esta página foi traduzida pela API Cloud Translation.

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.

Acessar o Explorador de registros
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 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.

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