Integraciones de almacenamiento de archivos

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

Cómo funciona

Puedes usar la ingesta de datos en la nube (CDI) para S3 para integrar directamente uno o más contenedores de S3 en 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 incorpora esos nuevos archivos.

La ingesta de datos en la nube es compatible con 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 el almacenamiento de datos
• Cola SQS para notificaciones de archivos nuevos
• Rol IAM para el acceso de Braze

Definiciones de AWS

Primero, define los términos utilizados durante 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 distintas sincronizaciones siempre que la carpeta sea única.

La configuración predeterminada es:

• ACL deshabilitadas
• Bloquear todo el acceso público
• Deshabilitar el versionado del contenedor
• Cifrado SSE-S3
  • SSE-S3 es el único tipo de cifrado del lado del servidor compatible. El cifrado con Amazon KMS no es compatible.

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

Paso 2: Crear una cola SQS

Crea una cola SQS para rastrear cuándo se añaden objetos al contenedor que has creado. Usa la configuración predeterminada por ahora.

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

Importante

Asegúrate de crear esta cola SQS en la misma región en la que creaste el contenedor.

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

Paso 3: Configurar la política de acceso

Para configurar la política de acceso, elige Opciones avanzadas.

Añade la siguiente declaración a la política de acceso de la cola, teniendo cuidado de reemplazar YOUR-BUCKET-NAME-HERE con el nombre de tu contenedor, YOUR-SQS-ARN con el ARN de tu cola SQS y YOUR-AWS-ACCOUNT-ID con tu ID de 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 eventos al contenedor de S3

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

Nota

Si subes tus archivos a la carpeta raíz de un contenedor de S3 y luego mueves algunos de los archivos a una carpeta específica dentro del contenedor, es posible que encuentres un error inesperado. En su lugar, puedes cambiar las notificaciones de eventos para que se envíen solo para los archivos en el prefijo, evitar colocar archivos en el contenedor de S3 fuera de ese prefijo, o actualizar la integración sin prefijo, lo que entonces ingiere todos los archivos.

Paso 5: Crear una política IAM

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

1. Ve a la sección IAM de la consola de AWS, selecciona Policies en la barra de navegación y luego 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 reemplazar YOUR-BUCKET-NAME-HERE con el nombre de tu contenedor y YOUR-SQS-ARN-HERE con 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. Dale un nombre y una descripción a la política, y luego 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 Require external ID.
3. En Braze, ve a Configuración de datos > Ingesta de datos en la nube > Orígenes, selecciona Añadir origen de datos y selecciona Amazon S3 en la sección de orígenes de archivos.
4. Copia el ID de cuenta de Braze generado automáticamente.

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

7. Adjunta la política creada en el paso 4 al rol. 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.

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

8. Toma nota del ARN del rol que creaste y del ID externo que generaste, ya que los necesitarás para crear la integración de ingesta de datos en la nube.

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

1. Primero, crea un nuevo origen en el panel de Braze. Ve a Configuración de datos > Ingesta de datos en la nube > Orígenes, selecciona Añadir origen de datos y luego selecciona Amazon S3.
2. Elige un nombre para tu origen e introduce la información del proceso de configuración de AWS para crear un nuevo origen. Especifica lo siguiente:

• Role ARN
• ID externo
• Nombre de contenedor
• Región

3. Selecciona Probar conexión para confirmar que Braze puede acceder a tu contenedor. Después de una prueba exitosa, selecciona Conectar al origen. Si la conexión falla, aparece un mensaje de error para ayudar a solucionar el problema.

4. A continuación, crea una nueva sincronización. Ve a Configuración de datos > Ingesta de datos en la nube > Sincronizaciones y selecciona Crear sincronización de datos.

5. Elige un nombre para tu sincronización. Luego, selecciona cualquier origen de S3 activo e introduce tu tabla de origen para la sincronización. Selecciona un tipo de datos y selecciona Probar conexión.

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 carpeta (opcional, debe ser única entre las sincronizaciones de un espacio de trabajo)
2. Selecciona un tipo de datos y selecciona Probar conexión para confirmar que Braze puede listar los archivos disponibles para ingestar (no los datos dentro de esos archivos). Una vez que sea exitoso, selecciona Siguiente: Notificaciones.
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 para errores a nivel de usuario y sincronizaciones exitosas.
4. Crea la sincronización.

Formatos de archivo requeridos

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

Si usas S3 para datos de catálogo, utiliza esta página junto con Sincronizar y eliminar datos de catálogo para conocer los requisitos y el comportamiento específicos de los catálogos.

Braze no impone requisitos adicionales de nombre de archivo más allá de los que aplica AWS. Los nombres de archivo deben ser únicos. Agregar una marca de tiempo ayuda a garantizar la unicidad.

Para ver ejemplos de todos los tipos de archivo admitidos (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 en tu archivo de origen requiere exactamente un identificador de usuario y una columna PAYLOAD. Un archivo de origen puede contener filas con diferentes tipos de identificadores, 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 con los campos que deseas sincronizar con el usuario en Braze.

Nota

A diferencia de los orígenes de almacén de datos, la columna UPDATED_AT no es requerida ni compatible para las sincronizaciones de almacenamiento de archivos.

Identificadores de catálogo

Para las sincronizaciones de catálogo, tu archivo de origen 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\"}"}

Importante

Cada línea en tu archivo de origen debe contener JSON válido, o el archivo será omitido.

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}}"}

Importante

Cada línea en tu archivo de origen debe contener JSON válido, o el archivo será omitido.

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\"}}"}

Importante

Cada línea en tu archivo de origen debe contener JSON válido, o el archivo será omitido.

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

Incluye una columna DELETED opcional. Cuando DELETED es true, ese elemento del catálogo se elimina del catálogo en Braze. Para ver la lista completa de columnas requeridas, consulta Identificadores de catálogo. Para conocer el comportamiento de eliminación, consulta Eliminar elementos del catálogo. Para un flujo de configuración de catálogo de extremo a extremo (incluyendo la creación del catálogo de destino y el comportamiento de sincronización), consulta Sincronizar y eliminar datos de catálogo.

Eliminación de datos

La ingesta de datos en la nube para S3 permite eliminar usuarios y elementos de catálogo mediante la carga de archivos. Usa sincronizaciones y formatos de archivo independientes para cada caso.

• Eliminación de usuarios: crea una sincronización con el tipo de datos Delete Users y carga archivos que contengan solo identificadores de usuario (sin carga útil).
• Eliminación de elementos de catálogo: usa tu sincronización de 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 mediante archivos en S3:

1. Crea una nueva sincronización de ingesta de datos en la nube (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. Carga archivos en tu contenedor de S3 que contengan solo columnas de identificadores de usuario. No incluyas una columna PAYLOAD: la sincronización falla si hay carga útil presente, para evitar eliminaciones accidentales.

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

Importante

La eliminación de usuarios es permanente y no se puede deshacer. Incluye solo los usuarios que deseas eliminar. Para más detalles, consulta Eliminar usuarios con la ingesta de datos en la nube.

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 archivos nuevos en el contenedor y elimina los perfiles de usuario correspondientes.

Eliminación de elementos de catálogo

Para eliminar elementos de un catálogo mediante almacenamiento de archivos:

1. Usa la misma sincronización de S3 que utilizas para sincronizar datos de 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 de catálogo que desees eliminar del catálogo en Braze.

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

Ejemplo – JSON (eliminación de elemento de 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 de 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 de catálogo correspondiente se elimine en Braze. Para conocer el comportamiento completo de sincronización y eliminación de catálogos, consulta Sincronizar y eliminar datos de catálogo.

Cosas que debes saber

• Los archivos añadidos al contenedor de S3 de origen no deben superar los 512 MB. Los archivos de más de 512 MB generan un error y no se sincronizan con Braze.
• Aunque no hay un límite adicional en el número de filas por archivo, recomendamos usar archivos más pequeños para mejorar la velocidad de ejecución de tus sincronizaciones. Por ejemplo, un archivo de 500 MB tardaría considerablemente más en ingerirse que cinco archivos separados de 100 MB.
• No hay un límite adicional en el número de archivos cargados en un periodo de tiempo determinado.
• No se admite el ordenamiento dentro de los archivos ni entre ellos. Recomendamos agrupar las actualizaciones periódicamente si estás monitorizando posibles condiciones de carrera.

Solución de problemas

Carga de archivos y procesamiento

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 usar archivos existentes para validar que Braze puede acceder a tu contenedor y detectar archivos para ingestar, pero no se sincronizan con Braze. Para que CDI los procese, debes volver a cargar en S3 cualquier archivo existente que quieras sincronizar.

Gestión de errores inesperados en archivos

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

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

Si tu problema está relacionado con las notificaciones de S3 o los permisos de destino de SQS (por ejemplo, errores de validación de destino), consulta la documentación de AWS:

• Habilitar y configurar notificaciones de eventos mediante la consola de Amazon S3
• Conceder permisos para publicar mensajes de notificación de eventos en un destino
• Solución de problemas en Amazon SQS