Integraciones de almacenamiento de archivos

Esta página explica cómo configurar la ingesta de datos en la nube y sincronizar los datos relevantes de S3 con Braze.

Esta página muestra los pasos de sincronización y fuente que actualmente se encuentran en acceso anticipado (EA). Para los pasos de la experiencia de disponibilidad general, despliega Experiencia de disponibilidad general a continuación.

Cómo funciona

Puedes utilizar Cloud Data Ingestion (CDI) para S3 para integrar directamente uno o varios contenedores de S3 de tu cuenta de AWS con Braze. Cuando se publican nuevos archivos en S3, se envía un mensaje a SQS, y la ingesta de datos en la nube de Braze recoge esos nuevos archivos.

La ingesta de datos en la nube admite lo siguiente:

• Archivos JSON
• Archivos CSV
• Archivos Parquet
• Datos de atributos, eventos personalizados, eventos de compra, eliminación de usuarios y catálogos

Requisitos previos

La integración requiere los siguientes recursos:

• Contenedor de S3 para almacenamiento de datos
• Cola SQS para notificaciones de nuevos archivos
• Rol IAM para el acceso de Braze

Definiciones de AWS

En primer lugar, definamos los términos utilizados en esta tarea.

Configuración de la ingesta de datos en la nube en AWS

Paso 1: Crear un contenedor de origen

Crea un contenedor de S3 de uso general con la configuración predeterminada en tu cuenta de AWS. Los contenedores de S3 se pueden reutilizar en todas las sincronizaciones, siempre y cuando la carpeta sea única.

La configuración predeterminada es:

• ACL deshabilitadas
• Bloquear todo acceso público
• Deshabilitar el versionado de contenedores
• Cifrado SSE-S3
  • SSE-S3 es el único tipo de cifrado del lado del servidor compatible. No se admite el cifrado de Amazon KMS.

Toma nota de la región en la que has creado el contenedor, ya que en el siguiente paso crearás una cola SQS en la misma región.

Paso 2: Crear cola SQS

Crea una cola SQS para controlar cuándo se añaden objetos al contenedor que has creado. Utiliza por ahora los ajustes de configuración predeterminados.

Una cola SQS debe ser única a nivel global (por ejemplo, solo se puede utilizar una para una sincronización CDI y no se puede reutilizar en otro espacio de trabajo).

Toma nota del ARN y la URL de la cola SQS, ya que los necesitarás con frecuencia durante esta configuración.

Paso 3: Establecer la política de acceso

Para configurar la política de acceso, selecciona Advanced options.

Añade la siguiente declaración a la política de acceso de la cola, teniendo cuidado de sustituir YOUR-BUCKET-NAME-HERE por el nombre de tu contenedor, YOUR-SQS-ARN por el ARN de tu cola SQS y YOUR-AWS-ACCOUNT-ID por el ID de tu cuenta de AWS:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "Sid": "braze-cdi-s3-sqs-publish",
  "Effect": "Allow",
  "Principal": {
    "Service": "s3.amazonaws.com"
  },
  "Action": "SQS:SendMessage",
  "Resource": "YOUR-SQS-ARN",
  "Condition": {
    "StringEquals": {
      "aws:SourceAccount": "YOUR-AWS-ACCOUNT-ID"
    },
    "ArnLike": {
      "aws:SourceArn": "arn:aws:s3:::YOUR-BUCKET-NAME-HERE"
    }
  }
} 

Paso 4: Añadir una notificación de evento al contenedor de S3

1. En el contenedor creado en el paso 1, ve a Properties > Event notifications.
2. Asigna un nombre a la configuración. Opcionalmente, especifica un prefijo o sufijo de destino si solo deseas que Braze ingeste un subconjunto de archivos.
3. En Destination, selecciona SQS queue y proporciona el ARN de la cola SQS que creaste en el paso 2.

Paso 5: Crear una política IAM

Crea una política IAM para permitir que Braze interactúe con tu contenedor de origen. Para comenzar, inicia sesión en la consola de administración de AWS como administrador de cuenta.

1. Ve a la sección IAM de la consola de AWS, selecciona Policies en la barra de navegación y, a continuación, selecciona Create Policy.
   
   
   
   

2. Abre la pestaña JSON e introduce el siguiente fragmento de código en la sección Policy Document, teniendo cuidado de sustituir YOUR-BUCKET-NAME-HERE por el nombre de tu contenedor y YOUR-SQS-ARN-HERE por el nombre de tu cola SQS:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE"]
        },
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE/*"]
        },
        {
            "Effect": "Allow",
            "Action": [
                "sqs:DeleteMessage",
                "sqs:GetQueueUrl",
                "sqs:ReceiveMessage",
                "sqs:GetQueueAttributes"
            ],
            "Resource": "YOUR-SQS-ARN-HERE"
        }
    ]
}

3. Selecciona Review Policy cuando hayas terminado.

4. Asigna un nombre y una descripción a la política y, a continuación, selecciona Create Policy.

Paso 6: Crear un rol IAM

Para completar la configuración en AWS, crea un rol IAM y adjúntale la política IAM del paso 5.

1. Dentro de la misma sección IAM de la consola donde creaste la política IAM, ve a Roles > Create Role.

2. En AWS, selecciona Another AWS Account como tipo de selector de entidad de confianza. Proporciona tu ID de cuenta de Braze. Selecciona la casilla de verificación Require external ID.
3. En Braze, ve a Data Settings > Cloud Data Ingestion > Sources, selecciona Add data source y selecciona Amazon S3 en la sección de fuentes de archivos.
4. Copia el Braze Account ID generado automáticamente.

6. En AWS, pega el ID de la cuenta y selecciona Next.

7. Adjunta al rol la política creada en el paso 5. Busca la política en la barra de búsqueda y selecciona la marca de verificación junto a la política para adjuntarla. Selecciona Next cuando hayas terminado.

Asigna un nombre y una descripción al rol y selecciona Create Role.

8. Toma nota del ARN del rol que has creado y del ID externo que has generado, ya que los necesitarás para crear la integración de Cloud Data Ingestion.

Configuración de la ingesta de datos en la nube en Braze

1. Primero, crea una nueva fuente en el panel de Braze. Ve a Data Settings > Cloud Data Ingestion > Sources, selecciona Add data source y luego selecciona Amazon S3.
2. Elige un nombre para tu fuente e introduce la información del proceso de configuración de AWS para crear una nueva fuente. Especifica lo siguiente:

• ARN del rol
• ID externo
• Nombre de contenedor
• Región

3. Selecciona Test connection para confirmar que Braze puede acceder a tu contenedor. Después de una prueba exitosa, selecciona Connect to Source. Si la conexión falla, aparecerá un mensaje de error para ayudarte a solucionar el problema.

4. A continuación, crea una nueva sincronización. Ve a Data Settings > Cloud Data Ingestion > Syncs y selecciona Create data sync.

5. Elige un nombre para tu sincronización. Luego, selecciona cualquier fuente S3 activa e introduce tu tabla de origen para la sincronización. Selecciona un tipo de datos y selecciona Test Connection.

1. Introduce la información restante del proceso de configuración de AWS. Especifica lo siguiente:
   • URL de SQS (debe ser única para cada nueva integración)
   • Ruta de la carpeta (opcional, debe ser única en todas las sincronizaciones de un espacio de trabajo)
2. Selecciona un tipo de datos y selecciona Test Connection para confirmar que Braze puede listar los archivos disponibles para ingestar (no los datos dentro de esos archivos). Una vez exitoso, selecciona Next: Notifications.
3. Añade correo(s) electrónico(s) de contacto para recibir notificaciones si la sincronización se interrumpe por problemas de acceso o permisos. Opcionalmente, activa las notificaciones de errores a nivel de usuario y de sincronizaciones correctas.
4. Crea la sincronización.

Formatos de archivo necesarios

La ingesta de datos en la nube admite archivos JSON, CSV y Parquet. Las columnas requeridas dependen del tipo de datos:

• Los datos de usuario (atributos, eventos personalizados, eventos de compra) utilizan identificadores de usuario y una carga útil
• Los datos de catálogo utilizan identificadores de catálogo

Braze no impone ningún requisito adicional para los nombres de archivo más allá de los que impone AWS. Los nombres de los archivos deben ser únicos. Añadir una marca de tiempo ayuda a garantizar la unicidad.

Para ver ejemplos de todos los tipos de archivos compatibles (atributos, eventos personalizados, compras, catálogos y eliminaciones de usuarios), consulta los archivos de ejemplo en braze-examples.

Identificadores de usuario

Para las sincronizaciones de datos de usuario (atributos, eventos personalizados, eventos de compra), cada fila de tu archivo fuente requiere exactamente un identificador de usuario y una columna PAYLOAD. Un archivo fuente puede contener filas con diferentes tipos de identificador, pero cada fila individual solo debe usar uno.

Además de un identificador, cada fila debe incluir una columna PAYLOAD que contenga una cadena JSON de los campos que deseas sincronizar con el usuario en Braze.

Identificadores de catálogo

Para las sincronizaciones de catálogo, tu archivo fuente debe contener las siguientes columnas. Los archivos de catálogo utilizan identificadores diferentes a los archivos de datos de usuario.

Ejemplos

• json attributes
• json custom events
• json purchase events
• csv attributes
• csv catalogs

1
2
3
4
5
6
7
{"external_id":"s3-qa-0","payload":"{\"name\": \"GT896\", \"age\": 74, \"subscriber\": true, \"retention\": {\"previous_purchases\": 21, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600803\"}"}
{"external_id":"s3-qa-1","payload":"{\"name\": \"HSCJC\", \"age\": 86, \"subscriber\": false, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600824\"}"}
{"external_id":"s3-qa-2","payload":"{\"name\": \"YTMQZ\", \"age\": 43, \"subscriber\": false, \"retention\": {\"previous_purchases\": 23, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600831\"}"}
{"external_id":"s3-qa-3","payload":"{\"name\": \"5P44M\", \"age\": 15, \"subscriber\": true, \"retention\": {\"previous_purchases\": 7, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600838\"}"}
{"external_id":"s3-qa-4","payload":"{\"name\": \"WMYS7\", \"age\": 11, \"subscriber\": true, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600844\"}"}
{"external_id":"s3-qa-5","payload":"{\"name\": \"KCBLK\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 11, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600850\"}"}
{"external_id":"s3-qa-6","payload":"{\"name\": \"T93MJ\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 10, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600856\"}"}

1
2
{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}

1
2
{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}

1
2
3
4
external_id,payload
s3-qa-load-0-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""SNXIM"", ""age"": 54, ""subscriber"": true, ""retention"": {""previous_purchases"": 19, ""vip"": true}, ""last_visit"": ""2023-08-08T16:03:26.598806""}"
s3-qa-load-1-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""0J747"", ""age"": 73, ""subscriber"": false, ""retention"": {""previous_purchases"": 22, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598816""}"
s3-qa-load-2-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""EP1U0"", ""age"": 99, ""subscriber"": false, ""retention"": {""previous_purchases"": 23, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598822""}"

1
2
3
ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

Eliminación de datos

La ingesta de datos en la nube para S3 admite la eliminación de usuarios y elementos del catálogo mediante la carga de archivos. Utiliza sincronizaciones y formatos de archivo distintos para cada uno.

• Eliminación de usuarios: crea una sincronización con el tipo de datos Delete Users y carga archivos que solo contengan identificadores de usuario (sin carga útil).
• Eliminación de elementos del catálogo: utiliza la sincronización del catálogo existente y añade una columna deleted (o DELETED) para marcar los elementos que deseas eliminar.

Eliminación de usuarios

Para eliminar perfiles de usuario en Braze utilizando archivos en S3:

1. Crea una nueva sincronización de Cloud Data Ingestion (con la misma configuración de AWS y Braze que para otras sincronizaciones).
2. Al configurar la sincronización en Braze, establece Data Type en Delete Users.
3. Sube archivos a tu contenedor de S3 que solo contengan columnas de identificadores de usuario. No incluyas una columna PAYLOAD: la sincronización falla si hay carga útil, para evitar eliminaciones accidentales.

Cada fila del archivo debe identificar exactamente a un usuario utilizando uno de los siguientes:

Ejemplo – JSON (eliminación de usuarios):

{"external_id":"user-to-delete-001"}
{"external_id":"user-to-delete-002"}
{"braze_id":"braze-id-from-profile"}

Ejemplo – CSV (eliminación de usuarios):

1
2
3
external_id
user-to-delete-001
user-to-delete-002

Cuando se ejecuta la sincronización, Braze procesa los nuevos archivos del contenedor y elimina los perfiles de usuario correspondientes.

Eliminación de elementos del catálogo

Para eliminar elementos de un catálogo utilizando el almacenamiento de archivos:

1. Utiliza la misma sincronización S3 que utilizas para sincronizar los datos del catálogo (tipo de datos Catalogs).
2. En tus archivos CSV o JSON, añade una columna opcional deleted (o DELETED).
3. Establece deleted en true para cualquier elemento del catálogo que quieras eliminar del catálogo en Braze.

Cada fila aún necesita ID y PAYLOAD. Para las filas marcadas para eliminación, la carga útil puede ser mínima; Braze elimina el elemento mediante ID.

Ejemplo – JSON (eliminación de elemento del catálogo):

{"id":"85","payload":"{\"product_name\": \"Product 85\", \"price\": 85.85}"}
{"id":"1","payload":"{\"product_name\": \"Product 1\", \"price\": 1.01}","deleted":true}

Ejemplo – CSV (eliminación de elemento del catálogo):

1
2
3
ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

Cuando se ejecuta la sincronización, las filas con deleted: true provocan que el elemento del catálogo correspondiente se elimine en Braze. Para obtener información completa sobre la sincronización y eliminación del catálogo, consulta Sincronizar y eliminar datos del catálogo.

Lo que hay que saber

• Los archivos añadidos al contenedor de origen de S3 no deben superar los 512 MB. Los archivos de más de 512 MB darán lugar a un error y no se sincronizarán con Braze.
• Aunque no hay ningún límite adicional en cuanto al número de filas por archivo, recomendamos utilizar archivos más pequeños para mejorar la velocidad de las sincronizaciones. Por ejemplo, un archivo de 500 MB tardaría considerablemente más en importarse que cinco archivos separados de 100 MB.
• No hay ningún límite adicional en cuanto al número de archivos que puedes subir en un tiempo determinado.
• No se admite el orden en los archivos ni entre ellos. Recomendamos agrupar las actualizaciones periódicamente si estás supervisando cualquier condición de carrera prevista.

Solución de problemas

Carga y procesamiento de archivos

CDI solo procesará los archivos que se añadan después de crear la sincronización. En este proceso, Braze busca nuevos archivos que se añadan, lo que desencadena un nuevo mensaje a SQS. Esto inicia una nueva sincronización para procesar el nuevo archivo.

Puedes utilizar archivos existentes para validar que Braze puede acceder a tu contenedor y detectar archivos para ingestar, pero estos no se sincronizan con Braze. Para que CDI los procese, debes volver a subir a S3 cualquier archivo existente que desees sincronizar.

Manejo de errores inesperados en los archivos

Si observas un número elevado de errores o archivos fallidos, es posible que haya otro proceso añadiendo archivos al contenedor de S3 en una carpeta distinta a la carpeta de destino para CDI.

Cuando los archivos se cargan en el contenedor de origen pero no en la carpeta de origen, CDI procesará la notificación SQS, pero no realizará ninguna acción sobre el archivo, por lo que esto puede aparecer como un error.