Descripción general de la solución de problemas

En esta página, se proporciona información general sobre la solución de problemas para API Gateway.

No se pueden ejecutar los comandos de "gcloud api-gateway"

Para ejecutar los comandos de gcloud api-gateway ..., debes actualizar Google Cloud CLI y habilitar los servicios de Google necesarios. Para obtener más información, consulta Configura tu entorno de desarrollo.

El comando "gcloud api-gateway api-configs create" indica que la cuenta de servicio no existe

Si ejecutas el comando gcloud api-gateway api-configs create ... y recibes un error con el siguiente formato:

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

Vuelve a ejecutar el comando, pero esta vez incluye la opción --backend-auth-service-account para especificar de forma explícita la dirección de correo electrónico de la cuenta de servicio que se usará:

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

Asegúrate de haber asignado los permisos necesarios a la cuenta de servicio, como se describe en Cómo configurar tu entorno de desarrollo.

Cómo determinar la fuente de las respuestas de error de la API

Si las solicitudes a tu API implementada generan un error (códigos de estado HTTP del 400 al 599), es posible que no quede claro en la respuesta si el error se origina en la puerta de enlace o en tu backend. Para determinarlo, haz lo siguiente:

  1. Ve a la página Explorador de registros y selecciona tu proyecto.

    Ve al Explorador de registros

  2. Filtra el recurso de puerta de enlace pertinente con la siguiente consulta de registro:

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"

    Aquí:

    • GATEWAY_ID especifica el nombre de la puerta de enlace.
    • GCP_REGION es la Google Cloud región de la puerta de enlace implementada.

  3. Busca la entrada de registro que coincida con la respuesta de error HTTP que deseas investigar. Por ejemplo, filtra por httpRequest.status.

  4. Inspecciona el contenido del campo jsonPayload.responseDetails.

Si el valor del campo jsonPayload.responseDetails es "via_upstream", la respuesta de error proviene de tu backend y deberás solucionar los problemas directamente en él. Si es cualquier otro valor, la respuesta de error proviene de la puerta de enlace. Consulta las siguientes secciones de este documento para obtener más sugerencias de solución de problemas.

La solicitud a la API devuelve un error HTTP 403

Si una solicitud a una API implementada devuelve un error HTTP 403 al cliente de la API, significa que la URL solicitada es válida, pero el acceso está prohibido por algún motivo.

Una API implementada tiene los permisos asociados a los roles otorgados a la cuenta de servicio que usaste cuando creaste la configuración de la API. Por lo general, el motivo del error HTTP 403 es que la cuenta de servicio no tiene los permisos necesarios para acceder al servicio de backend.

Si definiste la API y el servicio de backend en el mismo proyecto de Google Cloud, asegúrate de que la cuenta de servicio tenga asignado el rol de Editor o el rol necesario para acceder al servicio de backend. Por ejemplo, si el servicio de backend se implementa con Cloud Run Functions, asegúrate de que la cuenta de servicio tenga asignado el rol Cloud Function Invoker.

La solicitud a la API devuelve un error HTTP 401 o 500

Si una solicitud a una API implementada devuelve un error HTTP 401 o 500 al cliente de la API, es posible que haya un problema con el uso de la cuenta de servicio que se usó cuando creaste la configuración de la API para llamar a tu servicio de backend.

Una API implementada tiene los permisos asociados a los roles otorgados a la cuenta de servicio que usaste cuando creaste la configuración de la API. Se verifica la cuenta de servicio para asegurarse de que exista y de que la puerta de enlace de API la pueda usar cuando se implemente la API.

Si la cuenta de servicio se borra o inhabilita después de que se implementa la puerta de enlace, es posible que ocurra la siguiente secuencia de eventos:

  1. Inmediatamente después de que se borre o inhabilite la cuenta de servicio, es posible que veas respuestas HTTP 401 en los registros de tu puerta de enlace. Si el campo jsonPayload.responseDetails está configurado como "via_upstream" en el jsonPayload de la entrada de registro, esto indica que la causa del error es la eliminación o inhabilitación de la cuenta de servicio.

  2. También es posible que veas un error HTTP 500 sin ninguna entrada de registro correspondiente en los registros de API Gateway. Si no hay solicitudes a tu puerta de enlace inmediatamente después de que se borre o inhabilite la cuenta de servicio, es posible que no veas las respuestas HTTP 401, pero los errores HTTP 500 sin registros correspondientes de API Gateway son una indicación de que la cuenta de servicio de la puerta de enlace ya no está activa.

Si el backend de la solicitud fallida es otra API de Google Cloud (como bigquery.googleapis.com), verás respuestas HTTP 401 en los registros de tu puerta de enlace con el campo jsonPayload.responseDetails establecido en "via_upstream". Esto se debe a que API Gateway se autentica en los backends con un token de ID, mientras que otras APIs de Google Cloud requieren un token de acceso.

Solicitudes a la API con latencia alta

Al igual que Cloud Run y Cloud Run Functions, API Gateway está sujeto a la latencia de "inicio en frío". Si tu puerta de enlace no recibió tráfico durante 15 a 20 minutos, las solicitudes que se realicen a tu puerta de enlace durante los primeros 10 a 15 segundos del inicio en frío experimentarán una latencia de 3 a 5 segundos.

Si el problema persiste después del período inicial de "calentamiento", consulta los registros de solicitudes de los servicios de backend que configuraste en tu configuración de API. Por ejemplo, si el servicio de backend se implementa con Cloud Run Functions, consulta las entradas de Cloud Logging del registro de solicitudes de Cloud Function asociado.

No se puede ver la información de registro

Si tu API responde correctamente, pero los registros no contienen datos, por lo general, eso significa que no habilitaste todos los servicios de Google que requiere API Gateway.

API Gateway requiere que habilites los siguientes servicios de Google:

Nombre Título
apigateway.googleapis.com API de API Gateway
servicemanagement.googleapis.com API de Administración de servicios
servicecontrol.googleapis.com Service Control API

Usa los siguientes comandos para habilitar estos servicios: 

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Para obtener más información sobre los servicios de gcloud, consulta Servicios de gcloud.