Vista geral da resolução de problemas

Esta página fornece informações gerais de resolução de problemas para o API Gateway.

Não é possível executar comandos "gcloud api-gateway"

Para executar os comandos gcloud api-gateway ..., tem de ter atualizado a CLI Google Cloud e ativado os serviços Google necessários. Para mais informações, consulte o artigo Configurar o ambiente de desenvolvimento.

O comando "gcloud api-gateway api-configs create" indica que a conta de serviço não existe

Se executar o comando gcloud api-gateway api-configs create ... e receber um erro no seguinte formato:

ERROR: (gcloud.api-gateway.api-configs.create) FAILED_PRECONDITION:
Service Account "projects/-/serviceAccounts/service_account_email" does not exist

Volte a executar o comando, mas desta vez inclua a opção --backend-auth-service-account para especificar explicitamente o endereço de email da conta de serviço a usar:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

Certifique-se de que já atribuiu as autorizações necessárias à conta de serviço, conforme descrito no artigo Configurar o ambiente de desenvolvimento.

Determinar a origem das respostas de erro da API

Se os pedidos à sua API implementada resultarem num erro (códigos de estado HTTP 400 a 599), pode não ser claro a partir da própria resposta se o erro tem origem no gateway ou no seu back-end. Para determinar isto:

Aceda à página do Explorador de registos e selecione o seu projeto.

Aceda ao Explorador de registos
Filtre para o recurso de gateway relevante através da seguinte consulta de registo:
```
resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"
```
Onde:
- GATEWAY_ID especifica o nome da gateway.
- GCP_REGION é a Google Cloud região da entrada implementada.
Encontre a entrada de registo correspondente à resposta de erro HTTP que 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 tem origem no seu backend e tem de resolver o problema do backend diretamente. Se for qualquer outro valor, a resposta de erro tem origem no gateway. Consulte as secções seguintes deste documento para ver mais sugestões de resolução de problemas.

O pedido de API devolve um erro HTTP 403

Se um pedido a uma API implementada devolver um erro HTTP 403 ao cliente da API, significa que o URL pedido é válido, mas o acesso está proibido por algum motivo.

Uma API implementada tem as autorizações associadas às funções concedidas à conta de serviço que 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 autorizações necessárias para aceder ao serviço de back-end.

Se definiu a API e o serviço de back-end no mesmo projeto do Google Cloud, certifique-se de que a conta de serviço tem a função Editor atribuída, ou a função necessária para aceder ao serviço de back-end. Por exemplo, se o serviço de back-end for implementado através de funções do Cloud Run, certifique-se de que a conta de serviço tem a função Cloud Function Invoker atribuída.

O pedido de API devolve um erro HTTP `401` ou `500`

Se um pedido a uma API implementada devolver um erro HTTP 401 ou 500 ao cliente da API, pode haver um problema ao usar a conta de serviço usada quando criou a configuração da API para chamar o serviço de back-end.

Uma API implementada tem as autorizações associadas às funções concedidas à conta de serviço que usou quando criou a configuração da API. A conta de serviço é verificada para garantir que existe e que pode ser usada pelo gateway de APIs quando a API é implementada.

Se a conta de serviço for eliminada ou desativada após a implementação da gateway, pode ocorrer a seguinte sequência de eventos:

Imediatamente após a eliminação ou desativação da conta de serviço, pode ver respostas HTTP 401 nos registos do gateway. Se o campo jsonPayload.responseDetails estiver definido como "via_upstream" na entrada do registo jsonPayload, isto indica que a eliminação ou a desativação da conta de serviço é a causa do erro.
Também pode ver um erro HTTP 500 sem qualquer entrada de registo correspondente nos registos do API Gateway. Se não existirem pedidos para a sua entrada imediatamente após a eliminação ou desativação da conta de serviço, pode não ver as respostas HTTP 401, mas os erros HTTP 500 sem registos da entrada da API correspondentes são uma indicação de que a conta de serviço da entrada pode já não estar ativa.

Se o back-end do pedido com falha for outra Google Cloud API (como a bigquery.googleapis.com), verá respostas HTTP 401 nos registos da gateway com o campo jsonPayload.responseDetails definido como "via_upstream". Isto deve-se ao facto de o API Gateway fazer a autenticação nos back-ends com um token de ID, enquanto outras Google Cloud APIs requerem um token de acesso.

Pedidos de API com latência elevada

Tal como o Cloud Run e as funções do Cloud Run, o API Gateway está sujeito à latência de "cold start". Se o gateway não receber tráfego durante 15 a 20 minutos, os pedidos feitos ao gateway nos primeiros 10 a 15 segundos do arranque a frio vão sofrer uma latência de 3 a 5 segundos.

Se o problema persistir após o período de "aquecimento" inicial, verifique os registos de pedidos dos serviços de back-end que configurou na configuração da API. Por exemplo, se o serviço de back-end for implementado através de funções do Cloud Run, verifique as entradas do Cloud Logging do registo de pedidos da função da nuvem associada.

Não é possível ver informações do registo

Se a sua API estiver a responder corretamente, mas os registos não contiverem dados, significa normalmente que não ativou todos os serviços Google exigidos pelo API Gateway.

O API Gateway requer que ative os seguintes serviços Google:

Nome	Título
`apigateway.googleapis.com`	API do API Gateway
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

Use os seguintes comandos para ativar estes 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 o artigo Serviços gcloud.