Gestionar la cuota de la API Data de Google Analytics

Minhaz Kazi, Developers Advocate de Google Analytics, febrero del 2023

Si desarrollas aplicaciones con la API Data de Google Analytics, tendrás que saber cómo funcionan las cuotas y los límites de la API. Si tu aplicación está bien diseñada, es menos probable que los usuarios alcancen los límites de cuota. Algunas de las prácticas recomendadas también dan lugar a consultas de alto rendimiento a la API. De este modo, se pueden acelerar los informes y los paneles de control en la aplicación, lo que se traduce en una mejor experiencia de usuario. En este artículo se describe el sistema de cuotas y las prácticas recomendadas para implementar la API Data de Google Analytics.

Acerca del sistema de cuotas de la API Data de Google Analytics

Millones de desarrolladores y usuarios utilizan Google Analytics, y la cuota de solicitudes a la API evita que el sistema procese más datos de los que puede gestionar, a la vez que distribuye los recursos de forma equitativa. La API Data de las propiedades de Google Analytics 4 utiliza un sistema de segmentos de tokens para gestionar las cuotas de API. Para entender el concepto, imagina que hay un segmento que puede contener un número máximo de tokens. Con cada solicitud a la API, se comprueba primero el segmento. Si no quedan tokens, la solicitud no se completa. De lo contrario, la solicitud se ejecuta y consume uno o varios tokens del segmento, en función de la complejidad que tenga. Los tokens se reponen al nivel máximo en intervalos de tiempo fijos.

Según el método de la API de datos que uses, hay tres categorías de cuotas:

• En tiempo real (para runRealtimeReport)
• Embudo (para runFunnelReport)
• Principal (para el resto de los métodos)

Además, los métodos de la API Data comprueban los tokens de la cuota en diferentes segmentos:

1. Por propiedad y día
2. Por propiedad y hora
3. Por proyecto, propiedad y hora
4. Solicitudes simultáneas por propiedad
5. Errores del servidor por proyecto, propiedad y hora

Estos cinco segmentos se comprueban cada vez que se recibe una solicitud a la API Data de una propiedad. Si cualquiera de los segmentos está vacío, la solicitud devolverá inmediatamente un error 429. Si ninguno de los segmentos está vacío, se consumirá un solo token del segmento de solicitudes simultáneas por propiedad y se ejecutará la solicitud a la API. Según la complejidad de la solicitud, se consumirá una cantidad determinada de tokens de cada uno de los tres primeros segmentos cuando se complete la ejecución. En ese momento, también se repondrá un token en el segmento de solicitudes simultáneas por propiedad.

La cuota por proyecto, propiedad y hora evita que el agotamiento de cuotas en relación con uno o varios usuarios afecte a otros usuarios de tu aplicación. En ese caso, proyecto se refiere al proyecto de GCP de la aplicación. La cuota por propiedad y hora suele ser cuatro veces superior a la cuota por proyecto, propiedad y hora. Por lo tanto, para los usuarios finales, hay que acceder a una propiedad desde al menos cuatro proyectos diferentes antes de que se pueda agotar la cuota por propiedad y hora. Cuando se aplican cuotas tanto a nivel de proyecto como de propiedad, los problemas de cuota se limitan a una sola propiedad y no afectan a otras propiedades a las que acceda tu aplicación.

Advertencia: No es recomendable que los desarrolladores fragmenten los tokens de cuota en varios proyectos de API. Este comportamiento infringe los Términos del Servicio de las APIs de Google.

La cuota de errores del servidor hace referencia a las respuestas de la API con códigos 500 o 503. Si tu aplicación genera demasiados errores al acceder a una propiedad, se agotará la cuota de errores del servidor por proyecto, propiedad y hora.

Todos los tokens de la cuota se reponen por completo en los intervalos indicados. Consulta información actualizada sobre las cuotas de la API Data de Google Analytics. Por ejemplo, los métodos principales obtienen 1250 tokens de cuota en el segmento por proyecto, propiedad y hora. Si suponemos que una solicitud media de tu aplicación consume 10 tokens de cuota, tu aplicación podrá hacer 125 solicitudes principales por hora en una propiedad estándar y 10 veces más (1250 solicitudes principales) en cualquier propiedad de Analytics 360. Una de las ventajas de las propiedades de Analytics 360 es que el límite de tokens de cuota es más alto.

Como el consumo de tokens de los tres primeros segmentos depende de la complejidad de la solicitud, es difícil predecir el uso exacto de tokens antes de que esta se ejecute. Lo siguiente suele hacer que aumente la complejidad de una solicitud y que, por tanto, se usen más tokens:

• Solicitar más dimensiones
• Consultar un intervalo de tiempo mayor
• Incluir dimensiones con mayor cardinalidad
• Consultar una propiedad con un número de eventos mayor

Por lo tanto, la misma consulta de dos propiedades diferentes podría provocar un uso de tokens completamente diferente, ya que la cardinalidad de las dimensiones puede variar o el volumen de tráfico puede ser diferente. Sin embargo, puede que las propiedades con niveles de tráfico y configuraciones similares tengan un uso de tokens parecido. Puedes usar esta suposición para predecir el uso de tokens del cliente durante las fases de planificación y diseño de la aplicación.

Nota: Si ya has utilizado la API Reporting para Universal Analytics, habrás visto que aplica la cuota a nivel de aplicación o de proyecto de API. Sin embargo, en el caso de la API Data, la implementación es a nivel de propiedad de Google Analytics y a nivel de proyecto de API.

Monitorizar el uso de la cuota

Para monitorizar el uso de la cuota y transmitir esa información a tus usuarios finales, puedes añadir "returnPropertyQuota": true al cuerpo de la solicitud a la API. Esto devolverá el objeto PropertyQuota junto con la respuesta de la API. El objeto PropertyQuota contendrá el consumo y el estado de la cuota restante en cada uno de los cinco segmentos. A continuación se muestra un ejemplo de cuerpo de la solicitud y de respuesta:

Solicitud

{
  "dimensions": [
    {
      "name": "medium"
    }
  ],
  "metrics": [
    {
      "name": "activeUsers"
    }
  ],
  "dateRanges": [
    {
      "startDate": "yesterday",
      "endDate": "yesterday"
    }
  ],
  "returnPropertyQuota": true
}

Respuesta

{
  "dimensionHeaders": [
    {
      "name": "medium"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  ...
  
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 24997
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 4997
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 1247
    }
  },
  
  "kind": "analyticsData#runReport",
  ...
}

Por lo tanto, después de cada solicitud a la API Data que se ejecute correctamente, podrás ver cuánta cuota ha consumido y cuánto queda para la propiedad. También se puede mostrar esta información al usuario a través de la interfaz de tu aplicación.

Nota: En la fase actual de la API Data, tienes que ejecutar correctamente una solicitud a la API para recuperar el objeto PropertyQuota. Si la propiedad ya ha agotado un segmento de token de la cuota, no se ejecutará y se mostrará un error 429, que no contendrá el objeto PropertyQuota. Si te afecta esto y crees que tu aplicación se puede beneficiar de usar una forma independiente de acceder a la información sobre cuotas, haz +1 en esta solicitud de función en la herramienta de seguimiento de incidencias.

Gestión de la cuota

Para sacar el máximo partido a la API Data, sigue las prácticas recomendadas para la gestión de cuotas que se detallan a continuación. Además, si pasas a usar propiedades de 360, podría aumentar la cantidad de datos a los que accedes a través de la API.

Prácticas recomendadas

En general, hay dos formas de reducir el uso de la cuota en tu aplicación:

• Enviar menos solicitudes a la API
• Enviar solicitudes a la API menos complejas

Teniendo en cuenta estos dos principios, estas son las prácticas que puedes implementar:

• Almacenamiento en caché: si implementas una capa de almacenamiento en caché, la aplicación tendrá tanto más usabilidad como mejor gestión de la cuota. Google Analytics almacenará en caché tus solicitudes a la API, pero las solicitudes repetidas seguirán consumiendo tokens de cuota. Al almacenar en caché la respuesta de la API, puedes reducir significativamente el número de solicitudes repetidas. Por ejemplo, los datos intradía de las propiedades estándar pueden tardar 4 horas o más en caducar. Consulta el artículo sobre actualización de datos de Google Analytics.
• Fusión de solicitudes: intenta combinar varias solicitudes a la API en una sola. Por ejemplo, 5 solicitudes de datos en un periodo de 2 días podrían triplicar los tokens de cuota en comparación con 1 solicitud de 10 días. Si tienes varias solicitudes en las que solo varía una dimensión, te recomendamos que las combines en una sola.
• Solicitudes más simples: limita las solicitudes a la cantidad mínima de datos que necesitan tu aplicación y el usuario. Consumirás más tokens de cuota si hay un gran número de filas o columnas, o bien criterios de filtro complejos. Los periodos más largos suelen consumir más (por ejemplo, cambiar un periodo de 28 días por 365 días puede consumir 3 veces más tokens de cuota). También puedes usar dimensiones con menor cardinalidad siempre que sea posible (por ejemplo, solicita dateHour en lugar de dateHourMinute).
• Uso eficaz de limit: cambiar el limit en la solicitud a la API para reducir el número de filas que devuelve no influye significativamente en los tokens de cuota que se consumen. Por ejemplo, 5 solicitudes con límites de 10.000 filas pueden consumir 5 veces más cuota que 1 solicitud con un límite de 50.000.
• Elección del método adecuado: como se mencionaba anteriormente, los límites de cuota se dividen en tres categorías de métodos. Usar el método adecuado en cada caso práctico te permite ahorrar cuota en otras categorías. Por ejemplo, en lugar de crear tu propio embudo en tu aplicación con datos de los métodos principales, usa el método runFunnelReport para crear embudos.
• Cambios en la configuración predeterminada: al generar o personalizar informes en tu plataforma, puede que los usuarios no actualicen las opciones predeterminadas de tu aplicación y que solo las cambien en el tiempo de ejecución. Si tu aplicación tiene un periodo predeterminado de 365 días y el usuario suele consultar el informe de 28 días, acabará consumiendo más cuota de la necesaria de forma habitual. Recomendamos limitar los intervalos y las selecciones en la configuración predeterminada y dejar que los usuarios elijan los ajustes óptimos para sus casos prácticos. En algunos casos, también puedes limitar las opciones predeterminadas que pueden cambiar los usuarios.
• Solicitudes en cola y carga en diferido: ten en cuenta el límite de tokens para solicitudes simultáneas por propiedad. Tu aplicación no debe enviar demasiadas solicitudes a la vez. Si tiene una gran cantidad de elementos de interfaz de usuario que generan un número elevado de solicitudes a la API, puedes paginar la interfaz, cargar en diferido y poner en cola las solicitudes con un tiempo de espera exponencial para los reintentos. Usa el método returnPropertyQuota para monitorizar de forma eficaz el uso de tokens de tu aplicación en solicitudes simultáneas por propiedad.

Gestionar la experiencia y las expectativas de los usuarios

• Habla con los usuarios antes de que envíen consultas que puedan consumir muchos tokens. Por ejemplo, las consultas con varias dimensiones de alta cardinalidad o con un intervalo de tiempo amplio podrían consumir un gran número de tokens. Mostrar advertencias y una solicitud de confirmación en esas consultas puede evitar que los usuarios hagan cambios innecesarios en los informes y así limitar el ámbito de sus consultas.
• En el caso de las soluciones de generación de informes personalizados, explica a los usuarios el uso de las consultas que hace cada elemento de los informes. Por ejemplo, puedes proporcionar una vista de depuración que incluya los tokens de cuota que consume cada elemento de los informes.
• Explica el tipo específico de error de cuota y qué deben hacer los usuarios.
• Como las propiedades de Google Analytics 360 tienen un límite de cuota entre 5 y 10 veces superior al de las propiedades estándar, aportan más flexibilidad.

No se pueden aumentar los límites de cuota predeterminados de la API Data de Google Analytics 4. Google Analytics 360 ofrece unos límites de cuota más altos para las propiedades de Google Analytics 4. Si tus usuarios siguen alcanzando los límites de cuota tras haber implementado las prácticas recomendadas, pueden cambiarse a propiedades de 360. Otra opción para los usuarios es usar la BigQuery Export de Google Analytics. De esta forma, podrán exportar datos a nivel de evento a BigQuery y hacer su propio análisis.

Si tienes alguna duda sobre las cuotas de la API Data, ve al grupo de GA de Discord o haz una pregunta en Stack Overflow. Si tienes solicitudes de funciones específicas para la API Data, puedes publicarlas en nuestra herramienta de seguimiento de incidencias.