Integraciones de almacenamiento de archivos

Esta página explica cómo configurar la ingesta de datos en el cloud para sincronizar datos de Amazon S3 o Google Cloud Storage con Braze.

Cómo funciona

Puedes usar la ingesta de datos en el cloud (CDI) para integrar directamente uno o más contenedores de almacenamiento en tu cuenta en el cloud con Braze. Cuando agregas un nuevo archivo a un contenedor, tu proveedor de cloud publica una notificación, y la ingesta de datos en el cloud de Braze sincroniza los datos.

El mecanismo de notificación depende de tu proveedor:

• Amazon S3: Cuando se publican nuevos archivos en S3, se envía un mensaje a una cola de Amazon Simple Queue Service (SQS), y Braze consume ese mensaje para ingerir el nuevo archivo.
• Google Cloud Storage (GCS): Cuando se finalizan nuevos archivos en el contenedor, GCS publica una notificación OBJECT_FINALIZE en un tema de Pub/Sub. Braze consume esas notificaciones desde una suscripción de Pub/Sub para ingerir el nuevo archivo.

La ingesta de datos en el cloud 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

Configuración de la ingesta de datos en el cloud

Los pasos de configuración dependen de tu proveedor de almacenamiento de archivos. Selecciona la pestaña de tu proveedor y, a continuación, completa la configuración compartida en las secciones siguientes.

• amazon s3
• google cloud storage

La integración requiere los siguientes recursos:

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

Definiciones de AWS

Término	Definición
Amazon Resource Name (ARN)	El ARN es un identificador único para los recursos de AWS.
Identity and Access Management (IAM)	IAM es un servicio web que te permite controlar de forma segura el acceso a los recursos de AWS. En este tutorial, crearás una política IAM y la asignarás a un rol IAM para integrar tu contenedor de S3 con la ingesta de datos en el cloud de Braze.
Amazon Simple Queue Service (SQS)	SQS es una cola alojada que te permite integrar sistemas y componentes de software distribuidos.

Configuración de la ingesta de datos en el cloud 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).

Importante

Asegúrate de crear este 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: 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.

Nota

Si subes tus archivos a la carpeta raíz de un contenedor de S3 y luego mueves algunos de ellos a una carpeta específica dentro del contenedor, es posible que se produzca un error inesperado. En su lugar, puedes cambiar las notificaciones de eventos para que solo se envíen para los archivos con el prefijo, evitar colocar archivos en el contenedor de S3 fuera de ese prefijo o actualizar la integración sin prefijo, lo que hará que se ingesten 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 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 Configuración de datos > 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 4. 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 el cloud en Braze

1. Primero, crea un nuevo origen en el panel de Braze. Ve a Configuración de datos > Cloud Data Ingestion > Sources, selecciona Add data source y, a continuación, 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
• External ID
• Nombre del 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 Configuración de datos > Cloud Data Ingestion > Syncs y selecciona Create data sync.

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 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 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 que la prueba sea exitosa, 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 para errores a nivel de usuario y sincronizaciones exitosas.
4. Crea la sincronización.

La integración requiere los siguientes recursos:

• Un contenedor de Cloud Storage para almacenamiento de datos
• Un tema y una suscripción de Pub/Sub para notificaciones de archivos nuevos
• Una cuenta de servicio cuya clave JSON subes a Braze

Definiciones de GCP

Término	Definición
Proyecto de Google Cloud	Un proyecto organiza todos tus recursos de Google Cloud y se identifica mediante un ID de proyecto y un número de proyecto únicos.
Contenedor de Cloud Storage	Un contenedor es el recipiente que almacena los archivos de datos que deseas que Braze ingeste.
Tema de Pub/Sub	Un tema es el recurso con nombre que recibe notificaciones de archivos nuevos desde tu contenedor de Cloud Storage.
Suscripción de Pub/Sub	Una suscripción se adjunta a un tema y entrega sus mensajes. Braze consume las notificaciones de archivos nuevos desde una suscripción de tipo pull.
Cuenta de servicio	Una cuenta de servicio es una identidad no humana que Braze utiliza para acceder a tu contenedor y suscripción. Subes su clave JSON a Braze.
Rol IAM	Un rol de Identity and Access Management (IAM) es una colección de permisos que asignas a la cuenta de servicio en tu contenedor y suscripción.

Configuración de la ingesta de datos en el cloud en Google Cloud

Paso 1: Crear un contenedor de Cloud Storage

En la consola de Google Cloud, ve a Cloud Storage > Buckets > Create. Toma nota del ID del proyecto y del nombre del contenedor, ya que los necesitarás cuando configures el origen en Braze. Recomendamos habilitar el acceso uniforme a nivel de contenedor para que los permisos se gestionen con IAM.

Alternativamente, crea el contenedor con gcloud:

1
2
3
4
gcloud storage buckets create gs://YOUR-BUCKET-NAME \
  --project=YOUR-PROJECT-ID \
  --location=YOUR-REGION \
  --uniform-bucket-level-access

Paso 2: Crear un tema y una suscripción de Pub/Sub

En la consola de Google Cloud, ve a Pub/Sub > Topics > Create topic. Puedes dejar que Google cree una suscripción predeterminada o crear una por separado. Luego, crea una suscripción de tipo pull en ese tema.

Alternativamente, usa gcloud:

1
2
3
gcloud pubsub topics create YOUR-TOPIC --project=YOUR-PROJECT-ID
gcloud pubsub subscriptions create YOUR-SUBSCRIPTION \
  --topic=YOUR-TOPIC --project=YOUR-PROJECT-ID --ack-deadline=60

Toma nota del ID de suscripción: Braze necesita la suscripción (no el tema) cuando crees la sincronización. La suscripción debe ser de tipo pull.

Advertencia

No configures una cola de mensajes no entregados en esta suscripción. Braze no admite colas de mensajes no entregados para las suscripciones de ingesta de datos en el cloud. Para obtener más información, consulta Dead-letter topics en la documentación de Google Cloud.

Paso 3: Enviar notificaciones del contenedor al tema

Importante

La creación de una notificación de Cloud Storage a Pub/Sub no está disponible en la consola de Google Cloud. Debes usar gcloud (como se muestra aquí), Terraform o la API JSON. Para obtener más información, consulta Configure Pub/Sub notifications for Cloud Storage en la documentación de Google Cloud.

Primero, asigna al agente de servicio de Cloud Storage permiso para publicar en el tema y, a continuación, crea la notificación para OBJECT_FINALIZE. El evento OBJECT_FINALIZE se activa cada vez que se crea o finaliza un nuevo objeto en el contenedor.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Get the Cloud Storage service agent for your project
gcloud storage service-agent --project=YOUR-PROJECT-ID

# Assign it Pub/Sub Publisher on the topic
gcloud pubsub topics add-iam-policy-binding YOUR-TOPIC \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:service-YOUR-PROJECT-NUMBER@gs-project-accounts.iam.gserviceaccount.com" \
  --role="roles/pubsub.publisher"

# Create the OBJECT_FINALIZE notification (optionally scope to a folder with --object-prefix)
gcloud storage buckets notifications create gs://YOUR-BUCKET-NAME \
  --topic=YOUR-TOPIC \
  --event-types=OBJECT_FINALIZE \
  --payload-format=json

Sustituye los siguientes marcadores de posición en estos comandos:

• YOUR-PROJECT-ID: el ID de tu proyecto de Google Cloud, el identificador legible (por ejemplo, my-gcp-project).
• YOUR-TOPIC: el tema de Pub/Sub que creaste en el paso 2.
• YOUR-BUCKET-NAME: el nombre de tu contenedor de Cloud Storage.
• YOUR-PROJECT-NUMBER: el número de tu proyecto, el identificador numérico utilizado en la dirección de correo electrónico del agente de servicio de Cloud Storage. Es diferente del ID del proyecto. Puedes encontrarlo en el Dashboard de la consola de Google Cloud o ejecutando el siguiente comando:

1
gcloud projects describe YOUR-PROJECT-ID --format="value(projectNumber)"

Paso 4: Crear una cuenta de servicio

En la consola de Google Cloud, ve a IAM & Admin > Service Accounts > Create service account.

Alternativamente, usa gcloud:

1
2
3
gcloud iam service-accounts create braze-cdi-gcs \
  --project=YOUR-PROJECT-ID \
  --display-name="Braze CDI GCS"

Paso 5: Asignar permisos

El conector necesita exactamente estos permisos: storage.buckets.get, storage.objects.get y storage.objects.list en el contenedor, y pubsub.subscriptions.consume en la suscripción. Puedes asignarlos con un rol personalizado o con roles predefinidos.

Rol personalizado: crea un rol personalizado con exactamente esos permisos y vincúlalo al contenedor y a la suscripción:

1
2
3
4
5
6
7
8
9
10
11
12
13
gcloud iam roles create brazeCdiGcs --project=YOUR-PROJECT-ID \
  --title="Braze CDI GCS" \
  --permissions=storage.buckets.get,storage.objects.get,storage.objects.list,pubsub.subscriptions.consume \
  --stage=GA

gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
  --member="serviceAccount:[email protected]" \
  --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"

gcloud pubsub subscriptions add-iam-policy-binding YOUR-SUBSCRIPTION \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:[email protected]" \
  --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"

Roles predefinidos: asigna roles/storage.objectViewer y roles/storage.legacyBucketReader en el contenedor, y roles/pubsub.subscriber en la suscripción. El rol objectViewer proporciona storage.objects.get y storage.objects.list, y legacyBucketReader proporciona storage.buckets.get:

1
2
3
4
5
6
7
8
9
10
gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
  --member="serviceAccount:[email protected]" \
  --role="roles/storage.objectViewer"
gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
  --member="serviceAccount:[email protected]" \
  --role="roles/storage.legacyBucketReader"
gcloud pubsub subscriptions add-iam-policy-binding YOUR-SUBSCRIPTION \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:[email protected]" \
  --role="roles/pubsub.subscriber"

Paso 6: Crear una clave JSON

En la consola de Google Cloud, abre la cuenta de servicio, ve a Keys > Add key > Create new key y selecciona JSON.

Alternativamente, usa gcloud:

1
2
gcloud iam service-accounts keys create braze-cdi-gcs-key.json \
  --iam-account=[email protected]

Configuración de la ingesta de datos en el cloud en Braze

1. En Braze, ve a Configuración de datos > Cloud Data Ingestion > Sources, selecciona Add data source y, a continuación, selecciona Google Cloud Storage.

2. Completa los campos del origen:
   • Bucket: el nombre de tu contenedor
   • Project ID: el ID de tu proyecto de GCP
   • Service account JSON key: sube el archivo de clave del paso 6 y asigna un nombre a la credencial

3. Selecciona Test connection y, a continuación, selecciona Connect to Source.
4. Crea una sincronización. Ve a Configuración de datos > Cloud Data Ingestion > Syncs y selecciona Create data sync. Elige un nombre de sincronización y un Data Type (como User Attributes, Custom Events, Purchase Events, Catalog o Delete Users) y, a continuación, selecciona Next.
5. En el paso Data definition, selecciona tu origen de GCS y especifica lo siguiente:
   • Pub/Sub subscription ID: el ID de suscripción del paso 2 (no el tema)
   • Folder path (opcional): un prefijo de ruta dentro del contenedor (consulta Sincronizar una carpeta en un contenedor compartido)

6. Selecciona Preview and validate para confirmar que Braze puede acceder a la suscripción y listar los archivos disponibles para ingestar. Una prueba exitosa mostrará los archivos existentes en el contenedor, pero esos archivos no se sincronizarán automáticamente.
7. Añade correo(s) electrónico(s) de contacto para notificaciones de errores. Las sincronizaciones de Google Cloud Storage se basan en eventos, por lo que no se requiere una programación: Braze ingesta los archivos nuevos a medida que se suben. Revisa el resumen y selecciona Create sync.

Sincronizar una carpeta en un contenedor compartido

Puedes reutilizar un contenedor en varias sincronizaciones, pero cada sincronización debe apuntar a una carpeta distinta y tener su propia suscripción de Pub/Sub dedicada.

Importante

La ruta de carpeta y la suscripción deben ser únicas en todas las sincronizaciones de un espacio de trabajo cuando varias sincronizaciones comparten el mismo contenedor de origen. Como en el paso 2, no configures una cola de mensajes no entregados en ninguna de estas suscripciones.

Para cada carpeta que desees sincronizar en un contenedor compartido:

1. Establece el campo Folder de la sincronización en el prefijo de ruta (por ejemplo, attributes/). Braze solo listará e ingestará los objetos cuya ruta comience con ese prefijo.

2. Crea un tema dedicado y una notificación con alcance de prefijo para esa carpeta, y luego crea una suscripción en ese tema:

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
    # One topic per folder
    gcloud pubsub topics create YOUR-ATTRIBUTES-TOPIC --project=YOUR-PROJECT-ID
   
    # Assign the Cloud Storage service agent publisher on the topic
    gcloud pubsub topics add-iam-policy-binding YOUR-ATTRIBUTES-TOPIC \
      --project=YOUR-PROJECT-ID \
      --member="serviceAccount:service-YOUR-PROJECT-NUMBER@gs-project-accounts.iam.gserviceaccount.com" \
      --role="roles/pubsub.publisher"
   
    # Notification scoped to the folder with --object-prefix
    gcloud storage buckets notifications create gs://YOUR-BUCKET-NAME \
      --topic=YOUR-ATTRIBUTES-TOPIC --event-types=OBJECT_FINALIZE \
      --payload-format=json --object-prefix=attributes/
   
    # One subscription per sync
    gcloud pubsub subscriptions create YOUR-ATTRIBUTES-SUBSCRIPTION \
      --topic=YOUR-ATTRIBUTES-TOPIC --project=YOUR-PROJECT-ID --ack-deadline=60
   

3. Asigna a la cuenta de servicio de Braze permiso de consumo en esa suscripción, como en el paso 5:

   1
   2
   3
   4
    gcloud pubsub subscriptions add-iam-policy-binding YOUR-ATTRIBUTES-SUBSCRIPTION \
      --project=YOUR-PROJECT-ID \
      --member="serviceAccount:[email protected]" \
      --role="roles/pubsub.subscriber"
   

   Si creaste el rol personalizado en el paso 5, usa --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs" en su lugar.

4. Cuando crees la sincronización en Braze, introduce el nuevo Pub/Sub subscription ID y la Folder path de esta carpeta para que la sincronización ingeste solo los archivos de esa carpeta.

Formatos de archivo obligatorios

Los formatos de archivo obligatorios son los mismos para Amazon S3 y Google Cloud Storage. La ingesta de datos en el cloud admite archivos JSON, CSV y Parquet. Las columnas obligatorias 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 utilizas almacenamiento de archivos para datos de catálogo, usa 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 tu proveedor de almacenamiento de archivos. Los nombres de archivo deben ser únicos. Añadir 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 de 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 datos de almacén de datos, la columna UPDATED_AT no es obligatoria ni está admitida 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 de tu archivo de origen debe contener JSON válido, o el archivo se omitirá.

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 de tu archivo de origen debe contener JSON válido, o el archivo se omitirá.

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 de tu archivo de origen debe contener JSON válido, o el archivo se omitirá.

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 obligatorias, 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 (incluida 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 el cloud para almacenamiento de archivos 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 utilizando archivos en tu contenedor de origen:

1. Crea una nueva sincronización de ingesta de datos en el cloud (la misma configuración 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 origen 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 utilizando uno de los siguientes:

Importante

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

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 utilizando almacenamiento de archivos:

1. Usa la misma sincronización 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 origen no deben superar los 512 MB. Este límite se aplica tanto a Amazon S3 como a Google Cloud Storage. 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 utilizar 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 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 una nueva notificación. Esto inicia una nueva sincronización para procesar el nuevo archivo. Para Amazon S3, la notificación es un mensaje a SQS. Para Google Cloud Storage, es un mensaje OBJECT_FINALIZE a Pub/Sub.

Puedes usar archivos existentes para validar que Braze puede acceder a tu contenedor y detectar archivos para ingerir, pero no se sincronizan con Braze. Para que CDI los procese, debes volver a cargar en el contenedor de origen cualquier archivo existente que quieras sincronizar.

Gestión de errores inesperados en archivos (Amazon S3)

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:

• Habilitación y configuración de notificaciones de eventos mediante la consola de Amazon S3
• Concesión de permisos para publicar mensajes de notificación de eventos en un destino
• Solución de problemas en Amazon SQS

Gestión de errores inesperados en archivos (Google Cloud Storage)

Al igual que Amazon S3, CDI solo procesa los archivos cargados después de crear la sincronización. Cada nuevo objeto desencadena un mensaje OBJECT_FINALIZE en tu tema de Pub/Sub. Para ingerir archivos que ya existen en el contenedor, vuelve a cargarlos.

Si los archivos no se ingieren, verifica lo siguiente:

• La notificación del contenedor existe. Enumera las notificaciones del contenedor con gcloud storage buckets notifications list gs://YOUR-BUCKET-NAME.
• El agente de servicio de Cloud Storage tiene roles/pubsub.publisher en el tema.
• La cuenta de servicio de Braze tiene permiso de consumo en la suscripción (pubsub.subscriptions.consume, asignado a través del rol personalizado o de roles/pubsub.subscriber).
• La suscripción no tiene configurada una cola de mensajes no entregados. Braze no admite colas de mensajes no entregados para las suscripciones de Cloud Data Ingestion.

Para más información, consulta Notificaciones de Pub/Sub para Cloud Storage en la documentación de Google Cloud.