Cómo administrar la cuota para la API de datos de Google Analytics

Minhaz Kazi, asesor para desarrolladores, Google Analytics – febrero de 2023

Si desarrollas aplicaciones con la [API de Google Analytics Data], debes comprender 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 pertinentes también generan consultas eficientes a la API. Esto puede acelerar los informes y los paneles en tu aplicación, y generar una experiencia del usuario más deseable. En este artículo, se analiza el sistema de cuotas y las prácticas recomendadas para implementar la API de Google Analytics Data.

Información sobre el sistema de cuotas de la API de Google Analytics Data

Como Google Analytics es utilizado por millones de desarrolladores y usuarios, la cuota de solicitudes a la API protege el sistema para que no procese más datos de los que puede manejar y garantiza una distribución equitativa de los recursos del sistema. La API de datos para las propiedades Google Analytics 4 utiliza un sistema de bucket de tokens para administrar las cuotas de la API. Para comprender el concepto, imagina que hay un bucket que puede contener una cantidad máxima de tokens. Todas las solicitudes a la API primero verificarán el bucket. Si no quedan tokens, la solicitud fallará. De lo contrario, se ejecutará la solicitud y se consumirán uno o más tokens del bucket según la complejidad de la solicitud. Los tokens se reponen en el bucket hasta el máximo en intervalos de tiempo fijos.

Según el método de la API de Data que uses, existen tres categorías de cuotas independientes:

Además, los métodos de la API de datos verificarán varios segmentos para los [tokens de cuota][Google Analytics Data API Quotas]:

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

Estos cinco segmentos se verifican cada vez que se recibe una solicitud a la API de Data para una propiedad. Si alguno de los buckets está vacío, la solicitud fallará de inmediato con un error 429. Si ninguno de los buckets está vacío, se consumirá un solo token del bucket Solicitudes simultáneas por propiedad y, luego, se ejecutará la solicitud a la API. Según la complejidad de la solicitud, se consumirá una cierta cantidad de tokens de cada uno de los tres primeros buckets una vez que se complete la ejecución. En ese momento, también se repondrá un token para la métrica Solicitudes simultáneas por propiedad.

La cuota Por proyecto, por propiedad y por hora garantiza que el agotamiento de la cuota para uno o más usuarios no afectará a otros usuarios de tu aplicación. Aquí, project hace referencia a tu proyecto de GCP de la aplicación. La cuota de Por propiedad por hora suele ser cuatro veces mayor que la cuota de Por proyecto por propiedad por hora. Por lo tanto, para los usuarios finales, se debe acceder a una propiedad desde al menos cuatro proyectos diferentes antes de que se pueda agotar la cuota de Por propiedad por hora. La aplicación de la cuota a nivel del proyecto y de la propiedad garantiza que los problemas de cuota se limiten a una sola propiedad y no afecten a otras propiedades a las que accede tu aplicación.

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 cuando accede a una propiedad, agotará la cuota de Errores del servidor por proyecto, por propiedad y por hora.

Todos los tokens de cuota se restablecen hasta el límite en los intervalos indicados. Consulta [Cuotas de la API de Google Analytics Data] para obtener información actualizada sobre las cuotas. Por ejemplo, los métodos principales obtienen 1,250 tokens de cuota en el bucket Por proyecto, por propiedad y por hora. Si suponemos que una solicitud promedio de tu aplicación consume 10 tokens de cuota, tu aplicación podrá realizar 125 solicitudes de Core por hora para una propiedad estándar y 10 veces esa cantidad (1,250 solicitudes de Core) para cualquier propiedad de Analytics 360. El límite de tokens de cuota más alto es uno de los principales beneficios de las propiedades de Analytics 360.

Dado que el consumo de tokens para los primeros tres segmentos depende de la complejidad de la solicitud, es difícil predecir el uso exacto de tokens antes de la ejecución de la solicitud. Las siguientes acciones suelen aumentar la complejidad de una solicitud y, por lo tanto, generan el uso de tokens:

  • Cómo solicitar más dimensiones
  • Consultar un período más largo
  • Incluir dimensiones con mayor cardinalidad
  • Consultar una propiedad con un recuento de eventos más alto

Por lo tanto, la misma búsqueda para dos propiedades diferentes puede generar 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, puedes esperar que las propiedades con niveles de tráfico y configuración similares tengan un uso de tokens similar. Puedes usar esta suposición para predecir el uso de tokens de los clientes durante las fases de planificación y diseño de la aplicación.

Supervisa el uso de la cuota

Para supervisar el uso de la cuota y transmitir esa información al usuario final, puedes agregar "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á los importes de consumo y el estado de la cuota restante para los cinco buckets. A continuación, se muestran un ejemplo de cuerpo de solicitud y 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 exitosa a la API de datos, puedes ver cuánta cuota consumió la solicitud y cuánta cuota queda para la propiedad. También es posible mostrar esta información al usuario a través de la interfaz de tu aplicación.

Administración de la cuota

Te recomendamos que implementes las prácticas recomendadas de administración de cuotas que se detallan a continuación para aprovechar al máximo la API de Data. Además, actualizar tus propiedades a 360 puede aumentar la cantidad de datos a los que se accede a través de la API.

Prácticas recomendadas

En términos generales, existen dos formas de reducir el uso de la cuota de tu aplicación:

  • Envía menos solicitudes a la API
  • Envía solicitudes a la API menos complejas

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

  • Almacenamiento en caché: Implementar una capa de almacenamiento en caché beneficiará tanto la usabilidad como la administración de cuotas de tu aplicación. Google Analytics almacenará en caché tus solicitudes a la API, pero las solicitudes repetidas seguirán generando tokens de cuota. Al almacenar en caché la respuesta de la API, puedes reducir drásticamente la cantidad de solicitudes repetidas. Por ejemplo, los datos intradía de las propiedades estándar pueden tener un tiempo de vencimiento de la caché de 4 horas o más. Consulta Actualización de los datos en Google Analytics.
  • Combinación de solicitudes: Intenta combinar varias solicitudes a la API en una sola. Por ejemplo, 5 solicitudes de datos en un período de 2 días podrían usar 3 veces más tokens de cuota que 1 solicitud en un período de 10 días. Si tienes varias solicitudes que solo varían en una sola dimensión, considera combinarlas en una sola solicitud.
  • Simplifica las solicitudes: Limita tus solicitudes a la cantidad mínima de datos que requieren tu aplicación y el usuario. Una gran cantidad de filas o columnas, o criterios de filtro complejos consumirán más tokens de cuota. Los períodos más largos suelen ser más costosos (p.ej., cambiar el período de 28 a 365 días puede consumir 3 veces los tokens de cuota). También puedes considerar usar dimensiones con menor cardinalidad siempre que sea posible (p.ej., solicita dateHour en lugar de dateHourMinute).
  • Uso eficaz de limit: Cambiar limit en la solicitud de API para reducir la cantidad de filas devueltas no afecta de manera significativa los tokens de cuota consumidos. Por ejemplo, 5 solicitudes con límites de 10,000 filas pueden consumir cinco veces más tokens de cuota que 1 solicitud con un límite de 50,000.
  • Usa la categoría de método correcta: Como se mencionó anteriormente, los límites de cuota se distribuyen en tres categorías de métodos. Usar el método adecuado para el caso de uso correcto puede 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 de Core, usa el método runFunnelReport para crear embudos.
  • Actualiza la configuración predeterminada: Cuando los usuarios crean o personalizan informes en tu plataforma, es posible que no actualicen las opciones predeterminadas que presenta tu aplicación y solo las cambien en el tiempo de ejecución. Si tu aplicación tiene un intervalo de fechas predeterminado de 365 días y el usuario suele consultar el informe de 28 días, esto terminará consumiendo más cuota de la necesaria de forma regular. Considera limitar los rangos y las selecciones en la configuración predeterminada, y permite que los usuarios seleccionen la configuración óptima para sus casos de uso. En algunos casos, también puedes limitar los valores predeterminados que los usuarios pueden cambiar.
  • Solicitudes en cola y carga diferida: Ten en cuenta el límite de tokens de solicitudes simultáneas por propiedad. Tu aplicación no debe enviar demasiadas solicitudes al mismo tiempo. Si tu aplicación tiene una gran cantidad de elementos de la IU que generan una cantidad significativa de solicitudes a la API, considera paginar la IU, cargar de forma diferida y poner en cola las solicitudes con retirada exponencial para los reintentos. Usa el método returnPropertyQuota para supervisar de forma agresiva el uso de tokens de solicitudes simultáneas por propiedad de tu aplicación.

Administración de la experiencia y las expectativas del usuario

  • Proporciona comentarios a los usuarios antes de que ejecuten consultas con un posible uso elevado de tokens. Por ejemplo, las consultas con varias dimensiones de alta cardinalidad o con un período extenso podrían usar una gran cantidad de tokens. Proporcionar una advertencia y un mensaje de confirmación para esas búsquedas puede evitar que los usuarios realicen cambios innecesarios en los informes y ayudarlos a limitar el alcance de sus búsquedas.
  • En el caso de las soluciones de informes personalizados, proporciona una forma para que los usuarios comprendan el uso de las búsquedas de cada elemento en su informe. Por ejemplo, puedes proporcionar una vista de depuración que muestre el uso de tokens de cuota para cada elemento del informe.
  • Proporciona comentarios sobre el tipo específico de error de cuota y prescribe la acción del usuario.
  • Dado que las propiedades de Google Analytics 360 tienen un límite de cuota entre 5 y 10 veces mayor que las propiedades estándares, obtienes más flexibilidad con las propiedades de Google Analytics 360.

Los aumentos de cuotas de la API por encima de los límites predeterminados no están disponibles para la API de datos de Google Analytics 4. Google Analytics 360 ofrece límites de cuotas más altos para las propiedades Google Analytics 4. Si tus usuarios alcanzan los límites de cuota incluso después de implementar las prácticas recomendadas, deberían considerar actualizar sus propiedades a 360. Otra opción para los usuarios es utilizar la exportación de BigQuery de Google Analytics. Esto permitirá que los usuarios exporten datos a nivel del evento a BigQuery y ejecuten sus propios análisis.

Si tienes más preguntas sobre las cuotas de la API de Data, visita GA Discord o hazlas en Stack Overflow. Si tienes solicitudes de funciones específicas sobre la API de Data, puedes publicarlas en nuestra herramienta de seguimiento de errores.