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 archivo nuevo 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 archivos nuevos en S3, se envía un mensaje a una cola de Amazon Simple Queue Service (SQS), y Braze consume ese mensaje para ingestar el archivo nuevo.
• Google Cloud Storage (GCS): Cuando se finalizan archivos nuevos 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 ingestar el archivo nuevo.

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 la nube

Los pasos de configuración dependen de tu proveedor de almacenamiento de archivos. Selecciona la pestaña de tu proveedor y luego completa la configuración compartida en las secciones que siguen.

• amazon s3
• google cloud storage

La integración requiere los siguientes recursos:

• Contenedor de S3 para almacenamiento de datos
• Cola SQS para notificaciones de nuevos archivos
• Rol IAM para 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, crea una política IAM y asígnala a un rol IAM para integrar tu contenedor de S3 con la ingesta de datos en la nube 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 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:

• ARN del rol
• ID externo
• Nombre del 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 ayudarte 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 la carpeta (opcional, debe ser única en todas 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 ingerir (no los datos dentro de esos archivos). Una vez exitoso, selecciona Siguiente: Notificaciones.
3. Añade correo(s) electrónico(s) de contacto para 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 nuevos archivos
• 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 quieres que Braze ingiera.
Tema de Pub/Sub	Un tema es el recurso con nombre que recibe notificaciones de nuevos archivos de tu contenedor de Cloud Storage.
Suscripción de Pub/Sub	Una suscripción se conecta a un tema y entrega sus mensajes. Braze consume notificaciones de nuevos archivos desde una suscripción de tipo pull.
Cuenta de servicio	Una cuenta de servicio es una identidad no humana que Braze usa 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 la nube 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 creas 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 suscripciones de ingesta de datos en la nube. 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 el permiso para publicar en el tema, luego crea la notificación para OBJECT_FINALIZE. El evento OBJECT_FINALIZE se dispara 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

Reemplaza 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 ejecutar 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 la nube en Braze

1. En Braze, ve a Configuración de datos > Ingesta de datos en la nube > Orígenes, selecciona Añadir origen de datos y luego 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 dale un nombre a la credencial

3. Selecciona Probar conexión y luego selecciona Conectar al origen.
4. Crea una sincronización. Ve a Configuración de datos > Ingesta de datos en la nube > Sincronizaciones y selecciona Crear sincronización de datos. Elige un nombre de sincronización y un tipo de datos (como Atributos de usuario, Eventos personalizados, Eventos de compra, Catálogo o Eliminar usuarios), luego selecciona Siguiente.
5. En el paso de Definición de datos, selecciona tu origen de GCS y luego especifica lo siguiente:
   • ID de suscripción de Pub/Sub: el ID de suscripción del paso 2 (no el tema)
   • Ruta de la carpeta (opcional): un prefijo de ruta dentro del contenedor (consulta Sincronizar una carpeta en un contenedor compartido)

6. Selecciona Vista previa y validar para confirmar que Braze puede acceder a la suscripción y listar los archivos disponibles para ingerir. Una prueba exitosa listará 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 están basadas en eventos, por lo que no se requiere un horario: Braze ingiere nuevos archivos a medida que se suben. Revisa el resumen y luego selecciona Crear sincronización.

Sincronizar una carpeta en un contenedor compartido

Puedes reutilizar un contenedor en múltiples 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 la carpeta y la suscripción deben ser únicas en todas las sincronizaciones de un espacio de trabajo cuando múltiples 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 quieras sincronizar en un contenedor compartido:

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

2. Crea un tema dedicado y una notificación con alcance de prefijo para esa carpeta, 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 el 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 ID de suscripción de Pub/Sub y la ruta de la carpeta de esta carpeta para que la sincronización ingiera solo los archivos de esa carpeta.

Formatos de archivo requeridos

Los formatos de archivo requeridos 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 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 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 nombres de archivo más allá de los que exige tu proveedor de almacenamiento de archivos. 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 muestra 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 de 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 necesaria 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 de los archivos de datos de usuario.

Ejemplos

• atributos json
• eventos personalizados json
• eventos de compra json
• atributos csv
• catálogos csv

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 requeridas, consulta Identificadores de catálogo. Para conocer el comportamiento de eliminación, consulta Eliminación de elementos de 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 el cloud para almacenamiento de archivos permite eliminar usuarios y elementos de catálogo mediante cargas de archivos. Utiliza sincronizaciones y formatos de archivo separados para cada uno.

• 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 se van a eliminar.

Eliminación de usuarios

Para eliminar perfiles de usuario en Braze usando 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 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 usando 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 quieras 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.

Aspectos a tener en cuenta

• 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 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 y procesamiento de archivos

CDI solo procesará archivos que se hayan añadido 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. En el caso de Amazon S3, la notificación es un mensaje a SQS. En el caso de Google Cloud Storage, es un mensaje OBJECT_FINALIZE a Pub/Sub.

Puedes utilizar archivos existentes para validar que Braze pueda 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 diferente 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 realizará 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 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, vuélvelos a cargar.

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 roles/pubsub.subscriber).
• La suscripción no tiene configurada una cola de mensajes no entregados. Braze no es compatible con colas de mensajes no entregados para las suscripciones de Cloud Data Ingestion.

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