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

Minhaz Kazi, Developer Advocate, Google Analytics, febrero de 2023

Si desarrollas aplicaciones con la API de datos de Google Analytics, 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 relevantes también permiten generar consultas de buen rendimiento a la API. Esto puede acelerar los informes y los paneles de tu aplicación y dar como resultado una experiencia del usuario más deseable. En este artículo, se analizan el sistema de cuotas y las prácticas recomendadas para implementar la API de datos de Google Analytics.

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

Como millones de desarrolladores y usuarios usan Google Analytics, la cuota de las solicitudes a la API evita que el sistema procese más datos de los que puede manejar, a la vez que se garantiza una distribución equitativa de los recursos del sistema. La API de datos para las propiedades Google Analytics 4 usa un sistema de buckets 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. Cualquier solicitud a la API verificará primero el bucket. Si no quedan tokens, la solicitud fallará. De lo contrario, la solicitud se ejecutará y consumirá uno o más tokens del bucket según la complejidad de la solicitud. Los tokens se vuelven a reabastecer en el bucket al máximo en intervalos fijos.

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

• En tiempo real (para runRealtimeReport)
• Embudo (para runFunnelReport)
• Core (para todos los demás métodos)

Y los métodos de la API de datos verificarán varios buckets en busca de tokens de cuota:

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

Estos cinco buckets se verifican cada vez que llega una solicitud a la API de datos para una propiedad. Si cualquiera de los buckets está vacío, la solicitud fallará de inmediato y mostrará el error 429. Si ninguno de los buckets está vacío, se consumirá un solo token desde el 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 desde cada uno de los primeros tres buckets una vez que se complete la ejecución. Las solicitudes simultáneas por propiedad también se reabastecerán un token en este momento.

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

Advertencia: No se recomienda a los desarrolladores fragmentar tokens de cuota en varios proyectos de API. Esto constituye un incumplimiento de las Condiciones del Servicio de las APIs de Google.

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

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

Debido a que el consumo de tokens para los primeros tres buckets depende de la complejidad de la solicitud, es difícil predecir el uso exacto del token antes de la ejecución de la solicitud. Por lo general, lo siguiente aumentará la complejidad de una solicitud, lo que dará como resultado el uso del token:

• Solicitud de más dimensiones
• Consulta un intervalo de tiempo más alto
• Incluir dimensiones con cardinalidad más alta
• Consulta una propiedad con un recuento de eventos más alto

Por lo tanto, la misma consulta para dos propiedades diferentes podría generar un uso de tokens completamente diferente, ya que la cardinalidad de las dimensiones podría variar o el volumen de tráfico podría ser diferente. Sin embargo, puedes esperar que las propiedades con niveles de tráfico y configuración similares tengan un uso de token similar. 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 habías usado la API de Reporting para Universal Analytics, notarás que la API de Reporting aplica la cuota a nivel de proyecto de aplicación o API. Sin embargo, en el caso de la API de datos, la aplicación se realiza a nivel de la propiedad de Google Analytics y del proyecto de la API.

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. Se mostrará el objeto PropertyQuota junto con la respuesta de la API. El objeto PropertyQuota contendrá las cantidades de consumo y el estado de la cuota restante de los cinco buckets. A continuación, se muestra un ejemplo de un cuerpo de solicitud y una 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 correcta a la API de datos, puedes esperar ver cuánta cuota consumió la solicitud y cuánta cuota le queda a la propiedad. También es posible mostrarle esta información al usuario a través de la interfaz de tu aplicación.

Nota: En la etapa actual de la API de datos, debes ejecutar de forma correcta una solicitud a la API para recuperar el objeto PropertyQuota. Si la propiedad ya agotó un bucket de tokens de cuota, tu solicitud fallará con un error 429 y la respuesta no contendrá el objeto PropertyQuota. Si esto te afecta y crees que tu aplicación se beneficiaría de tener una forma independiente de acceder a la información de la cuota, haz +1 en esta solicitud de función en la Herramienta de seguimiento de errores.

Administración de la cuota

Implementamos las prácticas recomendadas de administración de cuotas que se detallan a continuación para aprovechar al máximo la API de datos. 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

Existen dos maneras de reducir el uso de la cuota para tu aplicación:

• Envío de menos solicitudes a la API
• Cómo enviar 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á la usabilidad y la administración de cuotas de tu aplicación. Google Analytics almacenará en caché tus solicitudes a la API, pero las solicitudes repetidas generarán tokens de cuota. Si almacenas 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 datos para 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 la cantidad de tokens de cuota en comparación con 1 solicitud para un período de 10 días. Si tienes varias solicitudes que varían solo en una dimensión, considera combinarlas en una sola solicitud.
• Simplificar solicitudes: Limita tus solicitudes a la cantidad mínima de datos que requieren tu aplicación y el usuario. Una gran cantidad de filas, 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 días a 365 días puede consumir 3 veces la cuota de tokens). También puedes considerar usar dimensiones con menor cardinalidad siempre que sea posible (p.ej., solicita dateHour en lugar de dateHourMinute).
• Uso efectivo de limit: Cambiar limit en la solicitud a la API para reducir la cantidad de filas que se muestran no afecta significativamente los tokens de cuota consumidos. Por ejemplo, 5 solicitudes con límites de 10,000 filas pueden consumir tokens de cuota cinco veces en comparación con 1 solicitud con un límite de 50,000.
• Usa la categoría de método correcta: Como se mencionó antes, los límites de cuota se distribuyen en tres categorías de métodos. Usar el método correcto 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 principales, usa el método runFunnelReport para crear embudos.
• Actualiza la configuración predeterminada: Cuando creas o personalizas informes en tu plataforma, es posible que los usuarios no actualicen las opciones predeterminadas que presenta tu aplicación y solo las cambien durante el tiempo de ejecución. Si tu aplicación tiene un período predeterminado de 365 días y el usuario suele consultar el informe de 28 días, esto terminará con el consumo de más cuota de la requerida de forma periódica. Considera limitar los rangos y las selecciones en la configuración predeterminada y permitir que los usuarios seleccionen la configuración óptima para sus casos de uso. En algunos casos, también puedes limitar los valores predeterminados que pueden cambiar los usuarios.
• Solicitudes en cola y carga diferida: Ten en cuenta el límite de tokens de solicitudes simultáneas por propiedad. Tu aplicación no debería 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 del token de solicitudes simultáneas por propiedad de tu aplicación.

Administración de la experiencia del usuario y las expectativas

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

Los aumentos de cuota de la API que superen los límites predeterminados no están disponibles en la API de datos para Google Analytics 4. Google Analytics 360 proporciona límites más altos de cuotas 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 que pueden usar los usuarios es usar la herramienta BigQuery Export de Google Analytics. Eso les permitirá a los usuarios exportar datos a nivel de evento a BigQuery y ejecutar su propio análisis.

Si tienes más preguntas sobre las cuotas de las APIs de datos, ve a Discord de GA o consulta en Stack Overflow. Si tienes solicitudes de funciones específicas relacionadas con la API de datos, puedes publicarlas en nuestra herramienta de seguimiento de errores.