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.

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. Por exemplo, se o serviço de back-end for implementado usando o Cloud Functions, verifique se a conta de serviço tem o papel Cloud Function Invoker atribuído a ele.

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:

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

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

Solicitações de API de alta latência

Assim como o Cloud Run e o Cloud Functions, o gateway de API está sujeito à latência de "inicialização a frio". Se o gateway não tiver recebido 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 de 3 a 5 segundos de latência.

Se o problema persistir após o período de aquecimento inicial, verifique os registros de solicitação dos serviço de back-end configurados na configuração da API. Por exemplo, se o serviço de back-end for implementado usando o Cloud Functions, verifique as entradas do Cloud Logging do registro de solicitação associado do função do Cloud.

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