Skip to content

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, Google Cloud Storage o Azure Blob Storage con Braze.

Cómo funciona

Puedes utilizar 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 se añade 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 publica un mensaje en 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.
  • Azure Blob Storage: Cuando se crean nuevos archivos en el contenedor, una suscripción de eventos en Azure Event Grid publica un evento Blob Created en una cola de Azure Storage. Braze lee esos mensajes de la cola 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 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 siguientes.

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

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 distribuido.

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).

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

Selección de "Advanced" con un ejemplo de objeto JSON para definir quién puede acceder a una cola.

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.

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.

    El botón "Create policy" en la consola de AWS.

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

  1. Selecciona Review Policy cuando hayas terminado.

  2. Dale un nombre y una descripción a la política, y luego selecciona Create Policy.

Un ejemplo de política llamada "new-policy-name".

El campo de descripción de la política.

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.

El botón "Create role".

  1. 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.
  2. 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.
  3. Copia el ID de cuenta de Braze generado automáticamente.

La página "Añadir nuevo origen" que muestra las secciones de nombre del origen y detalles de conexión de S3.

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

La página "Create Role" de S3. Esta página tiene campos para el nombre del rol, la descripción del rol, las entidades de confianza, las políticas y el límite de permisos.

  1. 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.

ARN del rol con new-policy-name seleccionada.

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

Un ejemplo de rol llamado "new-role-name".

  1. 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

La sección de detalles de conexión de S3 que muestra los campos de credenciales (configuración de AWS y configuración de Braze) y configuración.

  1. 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.
  1. 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.
  1. 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.

Una opción para probar la conexión con una vista previa de los datos.

  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 correos electrónicos 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. 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.

Como alternativa, 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.

Como alternativa, 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 la suscripción. Braze necesita la suscripción (no el tema) cuando crees la sincronización. La suscripción debe ser de tipo pull.

Paso 3: Enviar notificaciones del contenedor al tema

Primero, asigna al agente de servicio de Cloud Storage permiso para publicar en el tema, y luego 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

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

  • YOUR-PROJECT-ID: Tu ID de 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: Tu número de proyecto, el identificador numérico que se usa en la dirección de correo electrónico del agente de servicio de Cloud Storage. Es diferente del ID de proyecto. Encuéntralo en el Dashboard de la consola de Google Cloud, o ejecuta 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.

Como alternativa, 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.

Como alternativa, 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.

La pantalla "Añadir nuevo origen" con Google Cloud Storage seleccionado de la lista de orígenes de datos.

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

El formulario de origen de Google Cloud Storage que muestra los campos de contenedor, ID de proyecto y carga de credenciales.

  1. Selecciona Probar conexión y luego selecciona Conectar al origen.
  2. 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), y luego selecciona Siguiente.
  3. En el paso Definición de datos, selecciona tu origen de GCS y luego especifica lo siguiente:

El formulario de sincronización de Google Cloud Storage que muestra los campos de ID de suscripción de Pub/Sub y ruta de la carpeta.

  1. 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 lista los archivos existentes en el contenedor, pero esos archivos no se sincronizan automáticamente.
  2. Añade correos electrónicos de contacto para notificaciones de errores. Las sincronizaciones de Google Cloud Storage se basan en eventos, por lo que no se requiere un horario. Braze ingiere los 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 varias sincronizaciones, pero cada sincronización debe apuntar a una carpeta distinta y tener su propia suscripción de Pub/Sub dedicada.

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, 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 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.

La integración requiere los siguientes recursos:

  • Una cuenta de almacenamiento con un contenedor de blobs para almacenamiento de datos
  • Una cola de Azure Storage y una suscripción de eventos para notificaciones de nuevos archivos
  • Una entidad de servicio de Microsoft Entra ID que CDI usa para leer el contenedor y la cola

Definiciones de Azure

Término Definición
Cuenta de almacenamiento Una cuenta de almacenamiento es el recurso de Azure de nivel superior que contiene tanto el contenedor del que CDI lee archivos como la cola de la que CDI lee notificaciones.
Contenedor Un contenedor almacena los archivos de datos que quieres que CDI ingiera. Los contenedores se encuentran dentro de una cuenta de almacenamiento.
Cola de Azure Storage Una cola recibe notificaciones de nuevos archivos de tu contenedor. CDI lee y confirma los mensajes de esta cola para saber qué archivos ingerir.
Suscripción de eventos Una suscripción de eventos enruta eventos desde tu cuenta de almacenamiento a un destino, usando el servicio Azure Event Grid. La configuras para enviar eventos Blob Created a tu cola.
Tema del sistema Un tema del sistema representa el origen de los eventos. Event Grid crea uno para tu cuenta de almacenamiento cuando añades la primera suscripción de eventos.
Entidad de servicio Una entidad de servicio es una identidad de Microsoft Entra ID con la que CDI se autentica. La creas a través de un registro de aplicación e introduces sus credenciales en Braze.
Asignación de roles de Azure Una asignación de roles otorga a una entidad de servicio un conjunto de permisos en un ámbito determinado. Asignas dos roles integrados a la entidad de servicio de Braze en tu cuenta de almacenamiento.

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

Paso 1: Crear un contenedor

El contenedor y la cola deben estar en la misma cuenta de almacenamiento. Puedes reutilizar una cuenta de almacenamiento existente. Si aún no tienes una, ve a Storage accounts > + Create en el portal de Azure para crearla.

  1. En el portal de Azure, ve a tu cuenta de almacenamiento y luego a Data storage > Containers.
  2. Selecciona + Add container y dale un nombre.

Toma nota del nombre de la cuenta de almacenamiento y del nombre del contenedor. Los necesitarás cuando configures el origen en Braze.

Paso 2: Crear una cola

  1. En la misma cuenta de almacenamiento, ve a Data storage > Queues.
  2. Selecciona + Queue y dale un nombre.

Toma nota del nombre de la cola. Lo necesitarás cuando crees la sincronización, y cada sincronización necesita su propia cola.

Paso 3: Crear una suscripción de eventos

Crea una suscripción de eventos para que tu contenedor notifique a la cola cada vez que llegue un archivo.

  1. En la misma cuenta de almacenamiento, ve a Events y luego selecciona + Event Subscription.
  2. En Event Subscription Details, introduce un Nombre y establece Event Schema en Event Grid Schema.
  3. En Topic Details, revisa el System Topic Name. Si tu cuenta de almacenamiento aún no tiene un tema del sistema, introduce un nombre para crear uno. Si ya tiene uno, el campo muestra ese nombre y no se puede cambiar. Todas las suscripciones de eventos de una cuenta de almacenamiento usan el mismo tema del sistema.
  4. En Event Types, establece Filter to Event Types en Blob Created solamente. Blob Deleted también está seleccionado por defecto, así que desmárcalo.
  5. En Endpoint Details, establece Endpoint Type en Storage Queue. El enlace Configure an endpoint aparece después de elegir un tipo de endpoint.
  6. Selecciona Configure an endpoint y luego elige la cuenta de almacenamiento en la que estás trabajando.
  7. Selecciona Select existing queue y luego elige la cola que creaste en el paso 2.
  8. Selecciona Select para confirmar el endpoint.
  9. Selecciona Create.

Paso 4: Crear una entidad de servicio

CDI se conecta a tu cuenta de almacenamiento usando una entidad de servicio con autenticación de Microsoft Entra ID. Braze necesita los siguientes datos para conectarse:

  • ID de tenant (también llamado directorio) de tu cuenta de Azure
  • ID de principal (también llamado ID de aplicación) del service principal
  • Secreto de cliente para que Braze se autentique

Registrar una aplicación requiere permiso para crear registros de aplicaciones en Microsoft Entra ID. Si no lo tienes, pide a un administrador de Entra que complete este paso y comparta las credenciales contigo.

  1. En el portal de Azure, ve al centro de administración de Microsoft Entra y luego a App Registrations.
  2. Selecciona + New registration en Identity > Applications > App registrations.
  3. Introduce un nombre y selecciona Accounts in this organizational directory only como tipo de cuenta compatible. Luego, selecciona Register.
  4. Selecciona la aplicación (entidad de servicio) que acabas de crear y luego ve a Certificates & secrets > + New client secret.
  5. Introduce una descripción para el secreto y establece un periodo de caducidad para el secreto. Luego, selecciona Add.
  6. Toma nota del secreto de cliente creado para usarlo en la configuración de Braze.

Recomendamos crear una entidad de servicio que se use solo para CDI, para que su acceso se limite al contenedor y la cola que estás sincronizando. Si ya tienes una configurada para un origen de Microsoft Fabric, puedes reutilizarla, pero entonces tendrá acceso a ambos. En cualquier caso, necesita las asignaciones de roles del siguiente paso.

Paso 5: Asignar permisos a la entidad de servicio

CDI solo necesita el acceso suficiente para leer tus archivos y procesar los mensajes de la cola. Asigna estos dos roles integrados en la propia cuenta de almacenamiento, no a nivel de suscripción o grupo de recursos, porque las asignaciones de roles se heredan hacia abajo. No asignes roles más amplios como Storage Blob Data Contributor, Storage Account Contributor u Owner, que otorgan permisos de escritura y administración que CDI nunca usa.

  1. Ve a tu cuenta de almacenamiento y luego a Access Control (IAM).
  2. Selecciona Add > Add role assignment.
  3. Busca la entidad de servicio que creaste en el paso 4 por su nombre.
  4. Asígnale los siguientes roles integrados:
    • Storage Blob Data Reader: permite que CDI lea los archivos de tu contenedor.
    • Storage Queue Data Message Processor: permite que CDI inspeccione, recupere y elimine mensajes de tu cola.

Puedes usar un rol personalizado en su lugar, siempre que otorgue solo acceso de lectura a los blobs del contenedor y la capacidad de recibir y eliminar mensajes de la cola.

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 Azure Blob.

La pantalla "Añadir nuevo origen" con Azure Blob seleccionado de la lista de orígenes de datos.

  1. Completa los campos de Detalles de conexión de Azure Blob:
    • Credenciales: Tenant ID, Principal ID y Client Secret
    • Configuración: Storage account y Container

El formulario de detalles de conexión de Azure Blob que muestra los campos de Tenant ID, Principal ID, Client Secret, Storage account y Container.

  1. Selecciona Probar conexión y luego selecciona Conectar al origen.
  2. Crea una sincronización. Ve a Configuración de datos > Ingesta de datos en la nube > Sincronizaciones y selecciona Crear sincronización de datos.
  3. En Configuraciones, elige un nombre de sincronización, selecciona tu origen de Azure Blob y selecciona un tipo de datos (como Atributos de usuario, Eventos personalizados, Eventos de compra, Catálogo o Eliminar usuarios).
  4. En Definición de datos, especifica lo siguiente:

El formulario de sincronización de Azure Blob que muestra los campos de nombre de cola de almacenamiento y ruta de la carpeta.

  1. Selecciona Vista previa y validar para confirmar que CDI puede acceder a la cola y listar los archivos disponibles para ingerir. Una prueba exitosa lista los archivos existentes en el contenedor, pero esos archivos no se sincronizan automáticamente. La sincronización no está activa hasta que la conexión se valide correctamente.
  2. En Notificaciones, añade correos electrónicos de contacto para notificaciones de errores.
  3. Programación no tiene opciones para las sincronizaciones de almacenamiento de archivos. Las sincronizaciones de Azure Blob Storage se basan en eventos, por lo que CDI ingiere los nuevos archivos a medida que se suben.
  4. Revisa el Resumen y luego selecciona Crear sincronización.

Sincronizar una carpeta en un contenedor compartido

Puedes reutilizar un contenedor en varias sincronizaciones, pero cada sincronización necesita su propia cola de almacenamiento y su propia carpeta.

Para cada carpeta que quieras sincronizar en un contenedor compartido:

  1. Crea una cola para esa carpeta, como en el Paso 2.
  2. Crea una suscripción de eventos que envíe los eventos Blob Created del contenedor a esa cola, como en el Paso 3.
  3. Cuando crees la sincronización en Braze, introduce el nombre de la cola de almacenamiento de esa carpeta y establece la Ruta de la carpeta (opcional) en el prefijo de la carpeta, como attributes/. CDI solo ingiere archivos cuya ruta comience con ese prefijo.

Formatos de archivo obligatorios

Los formatos de archivo obligatorios son los mismos para Amazon S3, Google Cloud Storage y Azure Blob 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 del catálogo.

Braze no impone requisitos adicionales de nombre de archivo más allá de lo que exige 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 identificador, pero cada fila individual solo debe usar uno.

Identificador Descripción
EXTERNAL_ID Identifica al usuario que deseas actualizar. Debe coincidir con el valor de external_id utilizado en Braze.
ALIAS_NAME y ALIAS_LABEL Estas dos columnas crean un objeto de alias de usuario. alias_name debe ser un identificador único, y alias_label especifica el tipo de alias. Los usuarios pueden tener varios alias con diferentes etiquetas, pero solo un alias_name por alias_label.
BRAZE_ID El identificador de usuario de Braze. Lo genera el SDK de Braze, y no se pueden crear nuevos usuarios mediante un Braze ID a través de la ingesta de datos en el cloud. Para crear nuevos usuarios, especifica un ID externo o un alias de usuario.
EMAIL La dirección de correo electrónico del usuario. Si existen varios perfiles con la misma dirección de correo electrónico, se da prioridad al perfil actualizado más recientemente. Si incluyes tanto correo electrónico como teléfono, Braze utiliza el correo electrónico como identificador principal.
PHONE El número de teléfono del usuario. Si existen varios perfiles con el mismo número de teléfono, se da prioridad al perfil actualizado más recientemente.

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 de origen debe contener las siguientes columnas. Los archivos de catálogo utilizan identificadores diferentes a los archivos de datos de usuario.

Columna Obligatorio Descripción
ID Sí El identificador único del elemento del catálogo. Se utiliza para crear, actualizar o eliminar el elemento en Braze.
PAYLOAD Sí Una cadena JSON de los campos y valores del catálogo a sincronizar. Debe coincidir con el esquema de tu catálogo en Braze.
DELETED No Cuando es true, el elemento del catálogo con el ID correspondiente se elimina del catálogo en Braze. Omite esta columna o establécela como false para operaciones de creación o actualización.

Ejemplos

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

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 ver 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. Utiliza 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 la carga útil está presente, para evitar eliminaciones accidentales.

Cada fila del archivo debe identificar exactamente a un usuario utilizando una de las siguientes opciones:

Identificador Descripción
EXTERNAL_ID Coincide con el external_id utilizado en Braze.
ALIAS_NAME y ALIAS_LABEL Ambas columnas juntas identifican al usuario por alias.
BRAZE_ID ID de usuario generado por Braze (solo usuarios existentes).

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.

Aspectos a tener en cuenta

  • Los archivos añadidos al contenedor o contenedor de origen no deben superar los 512 MB. Este límite se aplica a Amazon S3, Google Cloud Storage y Azure Blob Storage. Los archivos de más de 512 MB generan un error y no se sincronizan con Braze. Azure Blob Storage permite archivos mucho más grandes, pero la ingesta de datos en el cloud aplica el mismo límite de 512 MB en todos los orígenes de almacenamiento de archivos.
  • 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 procesarse 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 procesa los archivos que se añaden 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. Para Azure Blob Storage, es un evento Blob Created entregado a una cola de Azure Storage.

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 el contenedor de origen cualquier archivo existente que desees sincronizar.

Manejo de errores de archivo inesperados (Amazon S3)

Si observas un gran número 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 procesa 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:

Manejo de errores de archivo inesperados (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 ingestar archivos que ya existen en el contenedor, vuelve a cargarlos.

Si los archivos no se ingestan, verifica lo siguiente:

  • La notificación del contenedor existe. Lista las notificaciones en el 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 fallidos. Braze no es compatible con colas de mensajes fallidos 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.

Manejo de errores de archivo inesperados (Azure Blob Storage)

Al igual que Amazon S3 y Google Cloud Storage, CDI solo procesa los archivos cargados después de crear la sincronización. Cada nuevo blob desencadena un evento Blob Created en tu cola. Para ingestar archivos que ya existen en el contenedor, vuelve a cargarlos.

Si los archivos no se ingestan, verifica lo siguiente:

  • La suscripción de eventos existe en la cuenta de almacenamiento y está filtrada para Blob Created.
  • La suscripción de eventos utiliza Event Grid Schema. CDI no puede leer eventos entregados en otro esquema.
  • El endpoint de la suscripción de eventos apunta a la cola configurada en la sincronización, no a una cola diferente.
  • La entidad de servicio de Braze tiene Storage Blob Data Reader y Storage Queue Data Message Processor en la cuenta de almacenamiento.
  • El secreto de cliente de la entidad de servicio no ha caducado. Azure aplica una caducidad a los secretos de cliente, y un secreto caducado detiene la sincronización.

Para más información, consulta Azure Blob Storage como origen de Event Grid en la documentación de Microsoft.
New Stuff!