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 de gcloud api-gateway ..., debes haber actualizado Google Cloud CLI 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 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 Configura tu entorno de desarrollo.

Determina el origen 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, sigue estos pasos:

  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 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 región de Google Cloud para la puerta de enlace implementada.

  3. Busca la entrada de registro que coincida con la respuesta de error de HTTP que quieres 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 se origina en tu backend y deberás solucionar los problemas directamente en él. Si es cualquier otro valor, la respuesta de error se origina en 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 de HTTP 403 al cliente de 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 de 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 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 API, es posible que haya un problema con 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 de 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 implementar la puerta de enlace, puede ocurrir 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 jsonPayload.responseDetails se establece en "via_upstream" en el jsonPayload de la entrada de registro, esto indica que borrar o inhabilitar la cuenta de servicio es la causa del error.

  2. También es posible que veas un error de 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 borra o inhabilita la cuenta de servicio, es posible que no veas las respuestas HTTP 401, pero los errores HTTP 500 sin los registros de la puerta de enlace de la API correspondientes indican que la cuenta de servicio de la puerta de enlace ya no está activa.

Si el backend de la solicitud con errores es otra API de Google Cloud (como bigquery.googleapis.com), verás respuestas HTTP 401 en los registros de la 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.

La solicitud a la API devuelve un error HTTP 500 para un método con aplicación de cuota

Si recibes el siguiente error, la puerta de enlace no pudo asignar la cuota para tu solicitud:

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

Este error suele ocurrir cuando llamas a un método que tiene una cuota configurada, pero las métricas de cuota ya no existen para la API. En una puerta de enlace de gRPC, se muestra el mismo error que el código de estado de gRPC Internal.

Confirma la causa en los registros de la puerta de enlace

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

    Ve al Explorador de registros

  2. Ejecuta la siguiente consulta de registro:

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
jsonPayload.responseDetails="service_control_quota_error"
httpRequest.status=500

    En el ejemplo anterior, GATEWAY_ID especifica el nombre de la puerta de enlace.

    La consulta filtra por el código de estado y por jsonPayload.responseDetails, ya que API Gateway usa el mismo valor responseDetails para cada rechazo de cuota. Una solicitud que superó legítimamente su cuota produce el mismo valor con un httpRequest.status de 429.

  3. Inspecciona los campos jsonPayload.apiConfig y jsonPayload.apiMethod de cualquier entrada coincidente. Identifican la configuración de la API y el método cuya configuración de cuota no es válida.

Por qué una configuración de API puede tener una configuración de cuota no válida

Las métricas y los límites de cuota se definen en una configuración de API, pero API Gateway los aplica a toda la API. Cada vez que creas una configuración de API, las métricas y los límites que declara reemplazan los que se declararon en las configuraciones de API anteriores de la API. Solo se aplican los valores de la configuración de la API creada más recientemente.

En cambio, las métricas que consume cada método se definen en la configuración de la API que entrega la puerta de enlace. Si una puerta de enlace ejecuta una configuración de API más antigua, le pide a Control de servicios que asigne una cuota de asignación en función de una métrica que existe en su propia configuración, pero que podría no existir en la API. Si la métrica no existe, la llamada de asignación falla y la puerta de enlace rechaza la solicitud.

Por ejemplo, la siguiente secuencia deja la primera puerta de enlace rota:

  1. Creas la configuración de la API config-v1, que declara la métrica quota-metric-v1, y la implementas en gateway-1.
  2. Creas la configuración de API config-v2 para la misma API, que declara la métrica quota-metric-v2, y la implementas en gateway-2.

gateway-2 funciona, pero las solicitudes a los métodos de gateway-1 que aplican cuotas comienzan a fallar, porque quota-metric-v1 ya no está definido para la API.

Los siguientes cambios pueden causar errores en cualquier puerta de enlace que aún esté implementada con una configuración de API anterior:

  • Cambiar el nombre de una métrica o quitarla
  • Cambiar la métrica a la que se aplica un límite de cuota
  • Cambiar la métrica nombrada en los costos de cuota por método (x-google-quota para documentos de OpenAPI o quota.metric_rules para parámetros de configuración del servicio de gRPC).

Cambiar solo el valor de un límite no genera errores. Sin embargo, debido a que los límites también se aplican a nivel de API, el valor nuevo se aplica en cada puerta de enlace de esa API, incluidas las puertas de enlace implementadas con una configuración de API anterior.

Compara las configuraciones de cuota implementadas

  1. Enumera tus puertas de enlace y la configuración de la API que entrega cada una:

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

  2. Enumera los parámetros de configuración de la API afectada, primero los creados más recientemente:

    gcloud api-gateway api-configs list --api=API_ID \
 --format="table(name.basename(),createTime:sort=1:reverse)"

    La primera entrada es la configuración de la API cuyas métricas y límites de cuota se aplican a toda la API. Ordena con la marca --format como se muestra: este comando no admite la marca --sort-by y no devuelve las configuraciones de la API en un orden predecible.

  3. Muestra la definición de la API a partir de la que se creó una configuración de API:

    gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID \
 --view=FULL --format="value(openapiDocuments[0].document.contents)" \
 | tr '_-' '/+' | base64 --decode

    El comando tr es obligatorio porque el campo contents está codificado en base64url, que base64 --decode no puede leer directamente.

    Para una API de gRPC, la configuración de la cuota se encuentra en la configuración del servicio, no en un documento de OpenAPI, por lo que debes reemplazar openapiDocuments[0].document.contents por managedServiceConfigs[0].contents.

  4. Ejecuta el comando del paso 3 para la configuración de la API que se encuentra en la parte superior de la lista del paso 2 y, luego, para cada uno de los otros parámetros de configuración de la API que se muestran en el paso 1 como implementados en una puerta de enlace.

  5. Compara los resultados. Cada métrica que una configuración de API anterior cobra por sus métodos también debe definirse en la configuración de API creada más recientemente. Si falta una métrica en esa configuración, fallarán las puertas de enlace que entregan la configuración de la API anterior.

Restablece una configuración de cuota válida

Audita tus métricas y límites de cuota para asegurarte de que sean coherentes en todas las configuraciones activas. Para ello, realiza una de las siguientes acciones:

  • Actualiza cada puerta de enlace de la API para usar la configuración de API creada más recientemente, como se describe en Actualiza una puerta de enlace.
  • Crea una configuración de API nueva que declare cada métrica que usen las configuraciones de API que aún se implementan y mantén las puertas de enlace existentes en sus configuraciones de API actuales.

Para evitar errores de asignación, mantén la coherencia de los nombres de las métricas en los parámetros de configuración de la API. Cuando cambies una cuota, cambia el valor del límite en lugar del nombre de la métrica.

Solicitudes a la API con alta latencia

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 realizadas a tu puerta de enlace dentro de los primeros 10 a 15 segundos del inicio en frío experimentarán de 3 a 5 segundos de latencia.

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

No se puede ver la información de los registros

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 Cloud :

Nombre Nombre del servicio
API de API Gateway apigateway.googleapis.com
API de Service Management servicemanagement.googleapis.com
API de Service Control servicecontrol.googleapis.com

Para habilitar los servicios obligatorios, sigue estos pasos:

Consola de Google Cloud

  1. En la consola de Google Cloud , ve a la página APIs y servicios > Biblioteca de APIs.

    Ir a la biblioteca de la API

  2. En la página Biblioteca de APIs, ingresa el nombre de la API requerida en la barra de búsqueda.
  3. En los resultados de la búsqueda, selecciona la página de la API.
  4. En la página de la API, haz clic en Habilitar.
  5. Repite estos pasos para cada uno de los servicios que se indican en la tabla anterior.

Google Cloud CLI

Usa los siguientes comandos para habilitar los 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.