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 “gcloud api-gateway”.

Para ejecutar los comandos gcloud api-gateway ..., debes haber actualizado la CLI de Google Cloud y habilitado los servicios de Google necesarios. Consulta Configura tu entorno de desarrollo para obtener más información.

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

Si ejecutas el comando gcloud api-gateway api-configs create ... y recibes un error del siguiente tipo, haz lo siguiente:

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 \
  --project=PROJECT_ID --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.

Determina 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 400 a 599), es posible que no quede claro en la respuesta si el error proviene de la puerta de enlace o de tu backend. Para determinarlo, sigue estos pasos:

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

    Ir al Explorador de registros

  2. Filtra el recurso de puerta de enlace relevante 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 el problema directamente. 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 muestra un error HTTP 403

Si una solicitud a una API implementada muestra 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 con 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 Editor o el rol necesario para acceder al servicio de backend. Por ejemplo, si el servicio de backend se implementa con funciones de Cloud Run, asegúrate de que la cuenta de servicio tenga asignado el rol Cloud Function Invoker.

La solicitud a la API muestra un error HTTP 401 o 500.

Si una solicitud a una API implementada muestra 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 con 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 que la puerta de enlace de la API pueda usarla 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 se produzca 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 la puerta de enlace. Si el campo response_code_details está configurado como "via_upstream" en el jsonPayload de la entrada de registro, esto indica que la eliminación o inhabilitación de la cuenta de servicio es la causa del error.

  2. También es posible que veas un error HTTP 500 sin ninguna entrada de registro correspondiente en los registros de la puerta de enlace de la API. 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 los registros de API Gateway correspondientes indican que es posible que la cuenta de servicio de la puerta de enlace ya no esté activa.

Solicitudes a la API con alta latencia

Al igual que Cloud Run y las funciones de Cloud Run, API Gateway está sujeto a 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 la puerta de enlace durante los primeros 10 a 15 segundos del inicio en frío tendrán entre 3 y 5 segundos de latencia.

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

No se puede ver la información del 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 API de Service Control

Para confirmar que los servicios obligatorios están habilitados, haz lo siguiente:

gcloud services list

Si no ves los servicios necesarios que se incluyeron en la lista, habilítalos:

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.