O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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 do Google necessários. 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 seu ambiente de desenvolvimento.

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 seja possível determinar pela resposta se o erro se origina do gateway ou do back-end. Para determinar isso:

Acesse a página de 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 se origina do back-end, e você precisará solucionar problemas diretamente no back-end. Se for qualquer outro valor, a resposta de erro se origina do gateway. Consulte as seções a seguir deste documento para mais dicas de solução de problemas.

A solicitação de 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 de 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 Google Cloud API (como bigquery.googleapis.com), você verá respostas HTTP 401 nos registros do gateway com o campo jsonPayload.responseDetails definido como "via_upstream". Isso ocorre porque o gateway de API autentica back-ends com um token de ID enquanto outras Google Cloud APIs exigem um token de acesso.

A solicitação de API retorna um erro HTTP 500 para um método com cota aplicada

Se você receber o erro a seguir, o gateway não poderá alocar cota para sua solicitação:

HTTP/2 500
{"code":500,"message":"Failed to call Service Control Quota."}

Esse erro geralmente ocorre quando você chama um método que tem uma cota configurada, mas as métricas de cota não existem mais para a API. Em um gateway gRPC, a mesma falha é retornada como o código de status gRPC Internal.

Confirmar a causa nos registros do gateway

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

Acessar a Análise de registros
Execute a seguinte consulta de registro:
```
resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
jsonPayload.responseDetails="service_control_quota_error"
httpRequest.status=500
```
Em que GATEWAY_ID especifica o nome do gateway.

A consulta filtra o código de status e jsonPayload.responseDetails porque o gateway de API usa o mesmo responseDetails valor para cada rejeição de cota. Uma solicitação que excedeu legitimamente a cota produz o mesmo valor com um httpRequest.status de 429.
Inspecione os campos jsonPayload.apiConfig e jsonPayload.apiMethod de qualquer entrada correspondente. Eles identificam a configuração da API e o método cuja configuração de cota é inválida.

Por que uma configuração de API pode ter uma configuração de cota inválida

Você define métricas e limites de cota em uma configuração de API, mas o gateway de API os aplica a toda a API. Cada vez que você cria uma configuração de API, as métricas e os limites declarados substituem aqueles declarados pelas configurações de API anteriores da API. Somente os valores da configuração de API criada mais recentemente são aplicados.

Por outro lado, as métricas consumidas por cada método são definidas na configuração de API que o gateway veicula. Se um gateway executar uma configuração de API mais antiga, ele vai pedir ao Service Control para alocar cota em relação a uma métrica que existe na própria configuração, mas que pode não existir na API. Se a métrica não existir, a chamada de alocação falhará, e o gateway vai rejeitar a solicitação.

Por exemplo, a sequência a seguir deixa o primeiro gateway quebrado:

Você cria a configuração de API config-v1, que declara a métrica quota-metric-v1, e a implanta em gateway-1.
Você cria a configuração de API config-v2 para a mesma API, que declara a métrica quota-metric-v2, e a implanta em gateway-2.

gateway-2 funciona, mas as solicitações para os métodos com cota aplicada de gateway-1 começam a falhar, porque quota-metric-v1 não está mais definida para a API.

As mudanças a seguir podem causar erros em qualquer gateway que ainda esteja implantado com uma configuração de API anterior:

Renomear ou remover uma métrica.
Mudar a métrica a que um limite de cota se aplica.
Mudar a métrica nomeada nos custos de cota por método (x-google-quota para documentos OpenAPI ou quota.metric_rules para configurações de serviço gRPC).

Mudar apenas o valor de um limite não causa erros. No entanto, como os limites também são aplicados no nível da API, o novo valor é aplicado a todos os gateways dessa API, incluindo gateways implantados com uma configuração de API anterior.

Comparar as configurações de cota implantadas

Liste seus gateways e a configuração de API que cada um veicula:

gcloud api-gateway gateways list \
 --format="table(name.basename(),apiConfig)"

Liste as configurações de API da API afetada, com a mais recente criada primeiro:
```
gcloud api-gateway api-configs list --api=API_ID \
 --format="table(name.basename(),createTime:sort=1:reverse)"
```
A primeira entrada é a configuração de API cujas métricas e limites de cota são aplicados a toda a API. Classifique com a flag --format, conforme mostrado: esse comando não oferece suporte à flag --sort-by e não retorna configurações de API em uma ordem previsível.
Mostre a definição de API de que uma configuração de API foi criada:
```
gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID \
 --view=FULL --format="value(openapiDocuments[0].document.contents)" \
 | tr '_-' '/+' | base64 --decode
```
O comando tr é necessário porque o contents campo é codificado em base64url, que base64 --decode não pode ler diretamente.

Para uma API gRPC, a configuração de cota está na configuração de serviço, e não em um documento OpenAPI. Portanto, substitua openapiDocuments[0].document.contents por managedServiceConfigs[0].contents.
Execute o comando na etapa 3 para a configuração de API na parte de cima da lista da etapa 2 e, em seguida, para cada uma das outras configurações de API que a etapa 1 mostra como ainda implantadas em um gateway.
Compare os resultados. Cada métrica que uma configuração de API mais antiga cobra dos métodos também precisa ser definida na configuração de API criada mais recentemente. Se uma métrica estiver ausente dessa configuração, os gateways que veiculam a configuração de API mais antiga vão falhar.

Restaurar uma configuração de cota válida

Audite as métricas e os limites de cota para garantir que eles sejam consistentes em todas as configurações ativas. Para fazer isso, realize uma das seguintes ações:

Atualize todos os gateways da API para usar a configuração de API criada mais recentemente, conforme descrito em Atualizar um gateway.
Crie uma nova configuração de API que declare todas as métricas usadas pelas configurações de API que ainda estão implantadas e mantenha os gateways atuais nas configurações de API atuais.

Para evitar erros de alocação, mantenha os nomes das métricas consistentes nas configurações de API de uma API. Ao mudar uma cota, altere o valor do limite, e não o nome da métrica.

Solicitações de API de alta latência

Assim como o Cloud Run e o Cloud Run functions, o gateway de API 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 ao gateway nos primeiros 10 a 15 segundos da inicialização a frio vão apresentar 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 configurados na configuração da API. Por exemplo, se o serviço de back-end for implementado usando as funções do Cloud Run, verifique as entradas do Cloud Logging do registro de solicitações 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 Google Cloud serviços:

Nome	Nome do serviço
API Gateway API	`apigateway.googleapis.com`
Service Management API	`servicemanagement.googleapis.com`
API Service Control	`servicecontrol.googleapis.com`

Para ativar os serviços necessários:

Google Cloud Console do

No Google Cloud console do, acesse a página APIs e serviços > Biblioteca de APIs.

Acessar a biblioteca de APIs
Na página Biblioteca de APIs, digite o nome da API necessária na barra de pesquisa.
Nos resultados da pesquisa, selecione a página da API.
Na página da API, clique em Ativar.
Repita essas etapas para cada um dos serviços listados na tabela anterior.

Google Cloud CLI

Use os comandos a seguir para ativar os 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 gcloud, consulte gcloud serviços.