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 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.

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 400 a 599), es posible que la respuesta en sí no indique 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.

    Ir 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 se origina en tu backend y deberás solucionar los problemas del backend directamente. 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 muestra un error HTTP 403

Si una solicitud a una API implementada muestra un error 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 las funciones otorgadas 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 asignada la función Editor o la función necesaria 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 asignada la función 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 API, es posible que haya un problema con el uso de la cuenta de servicio que usaste cuando creaste la configuración de la API para llamar a tu servicio de backend.

Una API implementada tiene los permisos asociados con las funciones otorgadas 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 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, puede ocurrir la siguiente secuencia de eventos:

  1. Inmediatamente después de que se borra o inhabilita 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 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 registros de puerta de enlace de API correspondientes 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 con errores es otra Google Cloud API (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 Google Cloud APIs requieren un token de acceso.

La solicitud a la API muestra un error HTTP 500 para un método con cuota aplicada

Si recibes el siguiente error, significa que la puerta de enlace no pudo asignar 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, la misma falla se muestra como 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.

    Ir 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

    Aquí GATEWAY_ID especifica el nombre de la puerta de enlace.

    La consulta filtra el código de estado y jsonPayload.responseDetails porque API Gateway usa el mismo responseDetails valor 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

Defines las métricas y los límites de cuota 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 a los que declaran las configuraciones de API anteriores de la API. Solo se aplican los valores de la configuración de API creada más recientemente.

Por el contrario, 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 anterior, le solicita a Control de servicios que asigne cuota a 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 dañada:

  1. Creas la configuración de 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 con cuota aplicada de gateway-1 comienzan a fallar porque quota-metric-v1 ya no está definida 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 o quitar una métrica
  • Cambiar a qué métrica se aplica un límite de cuota
  • Cambiar la métrica con nombre en los costos de cuota por método (x-google-quota para documentos de OpenAPI o quota.metric_rules para configuraciones de servicio de gRPC)

Cambiar solo el valor de un límite no causa errores. Sin embargo, debido a que los límites también se aplican a nivel de API, el valor nuevo se aplica en todas las puertas 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. Haz una lista de tus puertas de enlace y la configuración de API que entrega cada una:

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

  2. Haz una lista de las configuraciones de API de la API afectada, primero las creadas 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 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 muestra las configuraciones de API en un orden predecible.

  3. Muestra la definición de API a partir de la cual 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

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

    Para una API de gRPC, la configuración de cuota está en la configuración del servicio en lugar de 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 API que aparece en la parte superior de la lista del paso 2 y, luego, para cada una de las otras configuraciones de API que el paso 1 muestra como aún implementadas en una puerta de enlace.

  5. Compara los resultados. Cada métrica que una configuración de API anterior cobra a 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 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 usan las configuraciones de API que aún están implementadas 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 las configuraciones de API de una 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á sujeta 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 "activación", verifica 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 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 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 Google Cloud servicios:

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:

Google Cloud Consola de

  1. En la Google Cloud consola de, 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 enumeran 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 gcloud servicios.