Esta página foi traduzida pela API Cloud Translation.

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 \
  --project=PROJECT_ID --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 esta opção:

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 back-end e tem de resolver o problema do back-end 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 da 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 do 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 da 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 nenhuma 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 a 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 do 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 de latência elevada

Tal como o Cloud Run e as funções do Cloud Run, o API Gateway está sujeito à latência de "início a frio". Se o seu gateway não tiver recebido tráfego durante 15 a 20 minutos, os pedidos feitos ao seu gateway nos primeiros 10 a 15 segundos do arranque a frio vão ter 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

Para confirmar que os serviços necessários estão ativados:

gcloud services list

Se não vir 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 gcloud, consulte os serviços gcloud.