Semántica de la entrega de eventos
Esta página describe y define cómo Currents gestiona los datos de eventos de archivos planos que enviamos a los socios de almacenamiento de almacén de datos.
Currents para almacenamiento de datos es una transmisión continua de datos desde nuestra plataforma a un contenedor de almacenamiento en una de las conexiones de nuestros socios de almacén de datos. Currents escribe archivos Avro en tu contenedor de almacenamiento en umbrales regulares, lo que te permite procesar y analizar los datos de eventos con tu propio conjunto de herramientas de inteligencia empresarial (BI).
Este contenido solo se aplica a los datos de eventos de archivos planos que enviamos a los socios de almacenamiento de almacén de datos (Google Cloud Storage, Amazon S3 y Microsoft Azure Blob Storage).
Para el contenido que se aplica a otros socios, consulta nuestra lista de socios disponibles y revisa sus respectivas páginas.
Eventos de prueba
Cuando configures una integración de Currents, haz clic en Enviar eventos de prueba para verificar la conexión con tu contenedor de almacenamiento. Estos eventos de prueba validan que tu integración puede recibir y procesar datos correctamente.
Formato de datos de los eventos de prueba: Los eventos de prueba contienen valores de marcador de posición que coinciden con los tipos de datos correctos de cada campo, pero no contienen datos realistas ni precisos. Por ejemplo, un campo timezone puede contener una cadena similar a un UUID en lugar de un identificador de zona horaria válido (como “America/Chicago”), y otros campos como campaign_name e ip_pool también pueden contener valores de marcador de posición en lugar de datos reales.
Este es el comportamiento esperado. Los eventos de prueba sirven principalmente para probar la conexión y la configuración de la integración, no para validar la precisión de los datos. Para ver eventos reales con datos precisos, utiliza una integración de Currents de prueba para enviar datos de eventos reales a través de tu canalización.
Entrega al menos una vez
Como sistema de alto rendimiento, Currents ofrece una entrega de eventos “al menos una vez”, lo que significa que, ocasionalmente, pueden escribirse eventos duplicados en tu contenedor de almacenamiento. Esto puede ocurrir cuando los eventos se vuelven a procesar desde nuestra cola por cualquier motivo.
Si tus casos de uso requieren una entrega “exactamente una vez”, puedes utilizar el campo de identificador único que se envía con cada evento (id) para eliminar los eventos duplicados. Como el archivo deja de estar bajo nuestro control una vez que se escribe en tu contenedor de almacenamiento, no tenemos forma de garantizar la eliminación de duplicados por nuestra parte.
Marcas de tiempo
Todas las marcas de tiempo que exporta Currents se envían en la zona horaria UTC. En algunos eventos en los que está disponible, también se incluye un campo de zona horaria, que entrega la zona horaria local del usuario en el momento del evento con el formato de la Autoridad de Números Asignados de Internet (IANA).
Latencia
Los eventos enviados a Braze mediante el SDK o la API pueden incluir una marca de tiempo del pasado. El ejemplo más notable es cuando los datos del SDK se ponen en cola, por ejemplo, cuando no hay conectividad móvil. En ese caso, la marca de tiempo del evento reflejará el momento en que se generó el evento. Esto significa que un porcentaje de los eventos parecerá tener una latencia alta.
Los SDK de Braze para Android, Swift y Web almacenan los eventos no enviados en el dispositivo y vuelven a intentar enviarlos cuando el dispositivo se reconecta, sin ningún límite de tiempo. En el caso del SDK Web, los eventos en cola solo están limitados por el almacenamiento del navegador (unos 5 MB).
No hay un plazo máximo para los eventos que llegan con retraso. Currents está diseñado para exportar todos los eventos que recibe, independientemente de la antigüedad de su marca de tiempo. Un evento que llega con retraso se escribe en la partición date= correspondiente a la hora en que se puso en cola para su procesamiento en Braze, y conserva su marca de tiempo original en el campo time. Braze no rellena retroactivamente los eventos tardíos en particiones anteriores.
Como los eventos tardíos llegan a las particiones actuales, Braze recomienda procesar los archivos a medida que se escriben en tu contenedor de almacenamiento, en lugar de volver a escanear particiones date= anteriores con una ventana retrospectiva. Para eliminar duplicados, usa el campo id del evento como se describe en Entrega al menos una vez.
Formato Apache Avro
Las integraciones de almacenamiento de datos de Braze Currents generan datos en formato .avro. Elegimos Apache Avro porque es un formato de datos flexible que admite de forma nativa la evolución de esquemas y es compatible con una gran variedad de productos de datos:
- Casi todos los principales almacenes de datos admiten Avro.
- Si quieres dejar tus datos en S3, Avro comprime mejor que CSV y JSON, así que pagas menos por el almacenamiento y puedes usar menos CPU para analizar los datos.
- Avro requiere esquemas al escribir o leer datos. Los esquemas pueden evolucionar con el tiempo para admitir nuevos campos sin que nada se rompa.
Currents creará un archivo para cada tipo de evento con el siguiente formato:
<your-bucket-prefix>/dataexport.<cluster-identifier>.<connection-type-identifier>.integration.<integration-id>/event_type=<event-type>/date=<date>/version=<currents_version>/<environment>/dataexport.<cluster-identifier>.<connection-type-identifier>.integration.<integration-id>+<partition>+<offset>.avro
¿No puedes ver el código por la barra de desplazamiento? Aprende a solucionarlo en la página de inicio de la Guía del usuario de Braze.
Por ejemplo, la ruta de un evento de envío push puede tener este aspecto:
currents-export/dataexport.prod-01.S3.integration.69cadaaed2d51b7c75b1a3e5/event_type=users.messages.pushnotification.Send/date=2025-04-01-17/version=6/us-01/dataexport.prod-01.S3.integration.69cadaaed2d51b7c75b1a3e5+0+123456.avro
El segmento de ruta version es un valor entero simple de la versión de Currents, como version=6.
El segmento de ruta version indica que el esquema de los archivos ha cambiado. Úsalo solo como indicador, no como una columna de datos que consultes.
Algunas herramientas leen los segmentos de ruta key=value de estilo Hive, como version=6, como columnas de partición (por ejemplo, las tablas externas de BigQuery con particiones de Hive). Cuando cargas archivos de esta forma, la clave de partición version puede entrar en conflicto con campos de eventos que también se llaman version, como el campo version de los eventos users.messages.inappmessage.Abort.
Para evitar este conflicto, configura tu canalización para que no trate el segmento de ruta version como una columna. Puedes ignorar el valor del campo version de los mensajes dentro de la aplicación. Es un campo heredado que distinguía los mensajes dentro de la aplicación heredados, que ya no se usan, de los mensajes dentro de la aplicación desencadenados.
| Segmento del nombre de archivo | Definición |
|---|---|
<your-bucket-prefix> |
El prefijo establecido para esta integración de Currents. |
<cluster-identifier> |
Para uso interno de Braze. Será una cadena como “prod-01”, “prod-02”, “prod-03” o “prod-04”. Todos los archivos tendrán el mismo identificador de clúster. |
<connection-type-identifier> |
El identificador del tipo de conexión. Las opciones son “S3”, “AzureBlob” o “GCS”. |
<integration-id> |
El ID único de esta integración de Currents. Braze establece este ID cuando creas la integración y no cambia cuando editas la configuración de la integración (como las transformaciones de campos). |
<event-type> |
El tipo de evento del archivo. |
<date> |
La hora a la que los eventos se ponen en cola en nuestro sistema para su procesamiento, en la zona horaria UTC. Con el formato AAAA-MM-DD-HH. |
version=<currents_version> |
La versión de Currents para la ruta de la canalización. Este valor es un entero simple, como 6. |
<environment> |
Para uso interno de Braze. |
<partition> |
Para uso interno de Braze. Entero. |
<offset> |
Para uso interno de Braze. Entero. Ten en cuenta que los distintos archivos enviados en la misma hora tendrán un parámetro <offset> diferente. |
Las convenciones de nomenclatura de archivos pueden cambiar. Braze recomienda buscar todas las claves de tu contenedor que tengan el prefijo <your-bucket-prefix>.
Umbral de escritura de Avro
En circunstancias normales, Braze escribirá archivos de datos en tu contenedor de almacenamiento cada 5 minutos o cada 15 000 eventos, lo que ocurra primero. Con cargas elevadas, es posible que escribamos archivos de datos más grandes, con hasta 100 000 eventos por archivo.
Currents está diseñado para almacenar internamente en búfer grandes ráfagas de eventos, como los eventos de un mensaje enviado a millones de usuarios. No necesitas planificar capacidad adicional de escritura ni de E/S en tu contenedor de almacenamiento para estas ráfagas.
Currents nunca escribirá archivos vacíos.
Cambios en el esquema de Avro
De vez en cuando, Braze puede realizar cambios en el esquema de Avro cuando se añaden, modifican o eliminan campos. Para nuestros propósitos, hay dos tipos de cambios: los que provocan rupturas y los que no. Todos los cambios de esquema se agrupan en versiones de Currents, y cada versión hace avanzar el segmento version=<currents_version> de la ruta de almacenamiento (por ejemplo, de version=6 a version=7). Los eventos de Currents escritos en Azure Blob Storage, Google Cloud Storage y Amazon S3 usan el siguiente formato de ruta:
<your-bucket-prefix>/<currents-integration-id>/event_type=<event-type>/date=<date>/version=<currents_version>/<environment>/<avro-file>
Cambios que no provocan rupturas
Cuando se añade un campo al esquema de Avro, lo consideramos un cambio que no provoca rupturas. Los campos añadidos siempre serán campos “opcionales” de Avro (por ejemplo, con un valor predeterminado de null), por lo que “coincidirán” con los esquemas anteriores según la especificación de resolución de esquemas de Avro. Estas adiciones no deberían afectar a los procesos existentes de extracción, transformación y carga (ETL), ya que el campo simplemente se ignorará hasta que lo añadas a tu proceso ETL.
Te recomendamos que tu configuración de ETL indique de forma explícita los campos que procesa para evitar interrumpir el flujo cuando se añadan campos nuevos.
Cambios que provocan rupturas
Cuando se elimina o modifica un campo en el esquema de Avro, lo consideramos un cambio que provoca rupturas. Estos cambios pueden requerir modificaciones en los procesos ETL existentes, ya que es posible que los campos que estaban en uso dejen de registrarse como se esperaba.
Todos los cambios que provocan rupturas se comunicarán antes de su lanzamiento.
Para ver el historial completo de cambios por versión, consulta el Registro de cambios de Currents.