Ingesta de datos en la nube para Google Cloud Storage
Esta página cubre todo lo que necesitas para sincronizar datos desde Google Cloud Storage (GCS) con Braze mediante la ingesta de datos en la nube (CDI): los recursos de Google Cloud que debes crear, cómo conectar el origen y crear una sincronización en Braze, el formato de archivo para cada tipo de datos y la solución de problemas específica de GCS.
Cómo funciona
Las integraciones de Google Cloud Storage se basan en eventos en lugar de programaciones. 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 ingerir el archivo nuevo.
La integración requiere los siguientes recursos:
- Un contenedor de Cloud Storage para el almacenamiento de datos
- Un tema y una suscripción de Pub/Sub para las notificaciones de archivos nuevos
- Una cuenta de servicio a la que Braze accede mediante uno de los métodos de autenticación admitidos
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 (bucket) es el lugar donde se guardan los archivos de datos que quieres que Braze ingiera. |
| Tema de Pub/Sub | Un tema es el recurso con nombre que recibe las notificaciones de archivos nuevos de tu contenedor de Cloud Storage. |
| Suscripción de Pub/Sub | Una suscripción se vincula a un tema y entrega sus mensajes. Braze consume las notificaciones de archivos nuevos desde una suscripción de extracción (pull). |
| Cuenta de servicio | Una cuenta de servicio es una identidad no humana que Braze utiliza para acceder a tu contenedor y a tu suscripción. Braze la suplanta mediante Workload Identity Federation o utiliza una clave JSON que tú subes. |
| Workload Identity Federation | Workload Identity Federation (WIF) permite a Braze suplantar tu cuenta de servicio con una identidad de corta duración, para que no tengas que crear ni subir una clave. |
| Rol de IAM | Un rol de Identity and Access Management (IAM) es un conjunto de permisos que asignas a la cuenta de servicio en tu contenedor y tu suscripción. |
Configurar 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 > Crear. Anota el ID del proyecto y el nombre del contenedor. Los necesitarás cuando configures el origen en Braze. Braze recomienda habilitar el acceso uniforme a nivel de contenedor para que los permisos se administren con IAM.
Paso 2: Crear un tema y una suscripción de Pub/Sub
En la consola de Google Cloud, ve a Pub/Sub > Temas > Crear tema. Puedes dejar que Google cree una suscripción predeterminada o crear una por separado. Después, crea una suscripción de extracción (pull) en ese tema.
Anota el ID de suscripción. Braze necesita la suscripción (no el tema) cuando creas la sincronización. La suscripción debe ser de extracción.

No configures una cola de mensajes fallidos en esta suscripción. Braze no admite colas de mensajes fallidos para las suscripciones de ingesta de datos en la nube. Para obtener más información, consulta Temas de mensajes no entregados en la documentación de Google Cloud.
Paso 3: Enviar notificaciones del contenedor al tema

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 Configura notificaciones de Pub/Sub para 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 y, después, crea la notificación para OBJECT_FINALIZE. El evento OBJECT_FINALIZE se activa cada vez que se crea o finaliza un objeto nuevo en el contenedor.
# 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 YOUR-PROJECT-ID, YOUR-BUCKET-NAME y YOUR-TOPIC por tus propios valores. YOUR-PROJECT-NUMBER es el identificador numérico de la dirección de correo electrónico del agente de servicio, que es distinto del ID del proyecto. Puedes encontrarlo en el Panel de la consola de Google Cloud o ejecutando 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 y administración > Cuentas de servicio > Crear cuenta de servicio. En este ejemplo se usa braze-cdi-gcs como nombre de la cuenta.
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:
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: En lugar de un rol personalizado, 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.
Paso 6: Configurar la autenticación
Braze puede acceder a la cuenta de servicio con cualquiera de los siguientes métodos de autenticación:
| Método | Cómo se autentica Braze | Qué introduces en Braze |
|---|---|---|
| Workload Identity Federation | Braze impersonates your service account with a short-lived identity, so you don’t create or upload a key. | Project number, Workload identity pool ID, Provider ID, and Service account email |
| Service account key | Braze authenticates with a JSON key that you create for your service account. | JSON key file for the service account |
Workload Identity Federation
Con Workload Identity Federation (WIF), Braze se autentica en Google Cloud con una identidad de corta duración de su propio entorno AWS y luego suplanta la cuenta de servicio que creaste para Braze. Tú configuras tu proyecto para confiar en esa identidad solo para tu espacio de trabajo. No necesitas crear ni compartir una clave de cuenta de servicio.
Configuras WIF una vez por proyecto de Google Cloud. Una credencial WIF sirve tanto para fuentes de Google Cloud Storage como de BigQuery. Si ya completaste estos pasos para una fuente de BigQuery, concede a la cuenta de servicio existente los permisos para esta fuente y omite el resto de esta sección.
Requisitos previos
Para completar estos pasos en la consola de Google Cloud, necesitas permiso para crear grupos de identidades de carga de trabajo y para administrar las políticas de Identity and Access Management (IAM) de la cuenta de servicio y de tus datos. Por ejemplo, puedes usar los roles Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) y Service Account Admin (roles/iam.serviceAccountAdmin).
Confía solo en la entidad principal de tu espacio de trabajo

Concede acceso al nombre de recurso de Amazon (ARN) completo de la entidad principal de Braze que aparece en tu formulario de credenciales. No concedas acceso al rol de AWS de Braze ni a la cuenta de AWS. Una concesión a nivel de rol o de cuenta permite que otros clientes de Braze lean tus datos.
Todos los espacios de trabajo de Braze en la misma instancia de Braze presentan el mismo rol de AWS. Solo el nombre de sesión al final del ARN de la entidad principal, que es el ID de tu espacio de trabajo, es único para ti.
El mapeado de atributos predeterminado de Google para proveedores de AWS establece aws_role como el ARN del rol sin el nombre de sesión. Esto significa que, si concedes acceso a identidades que coincidan con un valor de aws_role, como principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARN, estarás confiando en todos los espacios de trabajo de Braze de tu instancia, incluido el tuyo.
Para mantener tus datos limitados a tu espacio de trabajo:
- Concede acceso solo a identidades cuyo
subjectsea el ARN completo de tu entidad principal de Braze. Es la entidad principalprincipal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN. - No concedas acceso a All identities in the pool ni a identidades filtradas por
aws_roleoaccount. - No escribas una condición de atributo que compruebe solo la cuenta o el rol de AWS.
- Mantén el mapeado de atributos predeterminado para
google.subject, que esassertion.arn.
El ARN de la entidad principal de Braze es distinto para cada espacio de trabajo e instancia de Braze, y Braze usa un rol de AWS para las fuentes de Google diferente del que usa para otras fuentes, como Snowflake. Copia siempre el valor desde un formulario de credenciales de BigQuery o Google Cloud Storage en el espacio de trabajo que vas a conectar.
Copia el ARN de la entidad principal de Braze
En Braze, empieza a crear tu fuente de Google Cloud Storage y selecciona Workload Identity Federation como método de autenticación. Copia el valor del paso 1 del formulario de credenciales, Copy the Braze principal ARN, y deja el formulario abierto.
Si el campo muestra Unavailable, WIF no está disponible para tu instancia de Braze. Usa una clave de cuenta de servicio en su lugar.
Habilita las API necesarias
En la consola de Google Cloud, ve a APIs & Services > Library y habilita las siguientes API para tu proyecto:
- IAM Service Account Credentials API
- Security Token Service API
- Identity and Access Management (IAM) API
Crea el grupo de identidades de carga de trabajo y el proveedor
- Ve a IAM & Admin > Workload Identity Federation y luego selecciona Create pool.
- Introduce un nombre para el grupo, como “Braze CDI”. Anota el Pool ID y luego selecciona Continue.
- En Select a provider, selecciona AWS.
- Introduce un nombre de proveedor, como “Braze AWS”, y anota el Provider ID.
- En AWS account ID, introduce el número de 12 dígitos que sigue a
arn:aws:sts::en el ARN de la entidad principal de Braze y luego selecciona Continue. - En Configure provider attributes, mantén el mapeado predeterminado, incluido
google.subject=assertion.arn. - Selecciona Save.
Los ID de grupo y de proveedor deben tener entre 4 y 32 caracteres, con letras minúsculas, números y guiones.
Restringe el proveedor a tu entidad principal (opcional)
Para una defensa en profundidad, añade una condición de atributo para que el proveedor acepte solo la entidad principal de tu espacio de trabajo. Así, Google rechaza cualquier otra identidad en el intercambio de tokens, antes de comprobar cualquier permiso de la cuenta de servicio.
- En el grupo, selecciona el proveedor y luego selecciona Edit.
- En Attribute conditions, selecciona Add condition.
-
Introduce la siguiente condición y sustituye
BRAZE_PRINCIPAL_ARNpor el valor completo que copiaste del formulario de credenciales:assertion.arn == 'BRAZE_PRINCIPAL_ARN'
- Selecciona Save.
Esta condición dedica el proveedor a un único espacio de trabajo de Braze. Para conectar otro espacio de trabajo, crea un proveedor independiente para él o enumera ambas entidades principales, como en assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN'].
Vincula la entidad principal de Braze a la cuenta de servicio
Concede a la entidad principal de tu espacio de trabajo permiso para suplantar la cuenta de servicio:
- Ve a IAM & Admin > Workload Identity Federation y luego selecciona tu grupo.
- Selecciona Grant access y luego selecciona Grant access using service account impersonation.
- En Service account, selecciona la cuenta de servicio que creaste para Braze.
- En Select principals, selecciona Only identities matching the filter.
- En Attribute name, selecciona subject. En Attribute value, pega el ARN completo de la entidad principal de Braze del formulario de credenciales.
- Selecciona Save. Si Google te ofrece descargar un archivo de configuración de la biblioteca cliente, selecciona Dismiss. Braze no lo necesita.
Esto concede el rol Workload Identity User (roles/iam.workloadIdentityUser) en la cuenta de servicio a una entidad principal con este formato:
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN
Para confirmarlo, abre la cuenta de servicio y selecciona la pestaña Permissions. El rol Workload Identity User debería mostrar esta entidad principal, terminada en el ARN completo de tu entidad principal de Braze.

No selecciones All identities in the pool ni filtres por aws_role. Ambas opciones coinciden con todos los espacios de trabajo de Braze de tu instancia de Braze, porque todos comparten el mismo rol de AWS. Para más detalles, consulta Confía solo en la entidad principal de tu espacio de trabajo.
Concede este rol solo en la cuenta de servicio. Una concesión a nivel de proyecto permite que la entidad principal suplante todas las cuentas de servicio del proyecto.
Los cambios de IAM pueden tardar unos minutos en aplicarse. Si una prueba de conexión falla justo después de conceder el acceso, espera unos minutos y vuelve a intentarlo.
La cuenta de servicio también necesita acceso a tus datos. Asegúrate de haberle concedido los permisos para esta fuente. Si usas una sola credencial para BigQuery y Google Cloud Storage, concede ambos conjuntos de permisos a la misma cuenta de servicio.
Introduce los valores en Braze
Vuelve al formulario de credenciales de Braze e introduce los siguientes valores de la consola de Google Cloud:
| Campo de Braze | Dónde encontrarlo |
|---|---|
| Project number | La tarjeta Project info en el Dashboard de la consola. Usa el número de proyecto numérico en lugar del ID de proyecto. |
| Workload identity pool ID | El Pool ID del grupo que creaste |
| Provider ID | El Provider ID del proveedor que creaste |
| Service account email | El Email de la cuenta de servicio en la página Service Accounts |
Braze combina el número de proyecto, el ID del grupo y el ID del proveedor en la audiencia, que indica a Google qué proveedor valida la solicitud de Braze. De forma predeterminada, un proveedor acepta su propio nombre de recurso como audiencia. Si configuras audiencias permitidas personalizadas en tu proveedor, incluye el nombre de recurso completo del proveedor.
Cómo prueba Braze la conexión
Cuando pruebas la conexión en Braze, Braze también comprueba que tu configuración confía solo en tu espacio de trabajo. Durante la prueba, Braze intenta el mismo intercambio con un nombre de sesión de prueba formado solo por ceros, con este formato:
assumed-role/cdi-gcs-bigquery-sync-<deployment>/000000000000000000000000
Tu configuración debe rechazar esta identidad, ya sea en el intercambio de tokens o cuando intente suplantar tu cuenta de servicio. Si ambos pasos se completan correctamente, la prueba falla, porque tu configuración confía en identidades distintas de la entidad principal de tu espacio de trabajo. Para solucionarlo, consulta Tu configuración confía en identidades distintas de tu espacio de trabajo.
Si configuras la condición de atributo opcional, Google rechaza la identidad de prueba en el intercambio de tokens. De lo contrario, Google rechaza la identidad de prueba cuando esa identidad intenta suplantar tu cuenta de servicio. En ambos casos, la prueba se supera.
Es posible que veas este intento rechazado en tus registros de auditoría de Google Cloud cada vez que pruebes la conexión. Es el comportamiento esperado. El intento proviene de la comprobación de Braze y no da a nadie acceso a tus datos.
No añadas una condición que rechace solo esta sesión de prueba. Una condición así supera la prueba mientras tu configuración sigue confiando en otros espacios de trabajo de Braze.
Retira el acceso de Braze
Para impedir que Braze acceda a tus datos, elimina el rol Workload Identity User de la entidad principal de Braze en la pestaña Permissions de la cuenta de servicio, o elimina el proveedor.
Configuración con la CLI de gcloud
Si prefieres la línea de comandos, los siguientes comandos habilitan las API, crean el grupo y el proveedor, y vinculan la entidad principal de Braze a tu cuenta de servicio. Sustituye los valores del primer bloque y pega el ARN de la entidad principal de Braze exactamente como lo copiaste.
PROJECT_ID="YOUR-PROJECT-ID"
POOL_ID="braze-cdi"
PROVIDER_ID="braze-aws"
SA_EMAIL="YOUR-SERVICE-ACCOUNT-EMAIL"
BRAZE_PRINCIPAL_ARN="PASTE-THE-BRAZE-PRINCIPAL-ARN-FROM-YOUR-CREDENTIAL-FORM"
PROJECT_NUMBER="$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')"
BRAZE_AWS_ACCOUNT_ID="$(echo "$BRAZE_PRINCIPAL_ARN" | cut -d: -f5)"
gcloud services enable iam.googleapis.com iamcredentials.googleapis.com sts.googleapis.com \
--project="$PROJECT_ID"
gcloud iam workload-identity-pools create "$POOL_ID" \
--project="$PROJECT_ID" --location="global" --display-name="Braze CDI"
gcloud iam workload-identity-pools providers create-aws "$PROVIDER_ID" \
--project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
--account-id="$BRAZE_AWS_ACCOUNT_ID"
# Optional: restrict the provider to your principal
gcloud iam workload-identity-pools providers update-aws "$PROVIDER_ID" \
--project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
--attribute-condition="assertion.arn == '${BRAZE_PRINCIPAL_ARN}'"
gcloud iam service-accounts add-iam-policy-binding "$SA_EMAIL" \
--project="$PROJECT_ID" \
--role="roles/iam.workloadIdentityUser" \
--member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/subject/${BRAZE_PRINCIPAL_ARN}"
Service account key
Braze se autentica con una clave JSON de tu cuenta de servicio. Las credenciales de clave de cuenta de servicio existentes siguen funcionando, así que no necesitas migrarlas.
En la consola de Google Cloud, abre la cuenta de servicio, ve a Claves > Agregar clave > Crear clave nueva y selecciona JSON. Descarga el archivo de la clave. Lo subirás a Braze cuando crees la fuente.
También puedes usar gcloud:
gcloud iam service-accounts keys create braze-cdi-key.json \
--iam-account=SERVICE_ACCOUNT_EMAIL
Reemplaza SERVICE_ACCOUNT_EMAIL por la dirección de correo electrónico de la cuenta de servicio. Para más información, consulta Crear y eliminar claves de cuentas de servicio.
Configurar la ingesta de datos en la nube en Braze
- En Braze, ve a Configuración de datos > Ingesta de datos en la nube > Orígenes, selecciona Añadir origen de datos y, a continuación, selecciona Google Cloud Storage.

- Completa los campos del origen:
- Bucket: el nombre de tu contenedor
- ID del proyecto: el ID de tu proyecto de GCP
- Credencial: asigna un nombre a la credencial y selecciona el método de autenticación que configuraste en el Paso 6. Para Workload Identity Federation, introduce Project number, Workload identity pool ID, Provider ID, and Service account email. Para Service account key, introduce JSON key file for the service account.

- Selecciona Probar conexión y, después, Conectar al origen.
- 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 para la sincronización y un Tipo de datos (como Atributos del usuario, Eventos personalizados, Eventos de compra, Catálogo o Eliminar usuarios) y, a continuación, selecciona Siguiente.
- En el paso Definición de datos, selecciona tu origen de GCS y, a continuación, especifica lo siguiente:
- ID de suscripción de Pub/Sub: el ID de suscripción del paso 2 (no el tema)
- Ruta de carpeta (opcional): un prefijo de ruta dentro del contenedor (consulta Sincronizar una carpeta en un contenedor compartido)

- Selecciona Vista previa y validación para confirmar que Braze puede acceder a la suscripción y listar los archivos disponibles para la ingesta. Una prueba correcta muestra los archivos existentes en el contenedor, pero esos archivos no se sincronizan automáticamente.
- Añade direcciones de correo electrónico de contacto para las notificaciones de errores. Las sincronizaciones de Google Cloud Storage se basan en eventos, así que no hace falta una programación. Braze ingiere los archivos nuevos a medida que se suben. Revisa el resumen y, a continuación, 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.

Cuando varias sincronizaciones comparten el mismo contenedor de origen, tanto la ruta de carpeta como la suscripción deben ser únicas entre las sincronizaciones de un espacio de trabajo. Al igual que en el Paso 2, no configures una cola de mensajes fallidos en ninguna de estas suscripciones.
Para cada carpeta que quieras sincronizar en un contenedor compartido:
- Establece el campo Carpeta de la sincronización con el prefijo de ruta (por ejemplo,
attributes/). Braze solo lista e ingiere los objetos cuya ruta empieza por ese prefijo. -
Crea un tema dedicado y una notificación limitada al prefijo para esa carpeta y, después, crea una suscripción en ese tema:
# 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
-
Asigna a la cuenta de servicio de Braze el permiso de consumo en esa suscripción, como en el Paso 5:
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. - Cuando crees la sincronización en Braze, introduce el nuevo ID de suscripción de Pub/Sub y la Ruta de carpeta de esta carpeta para que la sincronización solo ingiera los archivos de esa carpeta.
Formatos de archivo obligatorios
La ingesta de datos en la nube admite archivos JSON, CSV y Parquet. Las columnas obligatorias dependen del tipo de datos. Braze no impone ningún requisito adicional sobre los nombres de archivo más allá de los que establezca tu proveedor de almacenamiento de archivos. Los nombres de archivo deben ser únicos; añadir una marca de tiempo ayuda a garantizarlo.

A diferencia de las fuentes de almacén de datos, la columna UPDATED_AT no es obligatoria ni se admite en las sincronizaciones de almacenamiento de archivos.
Para ver ejemplos de todos los tipos de archivo admitidos, consulta los archivos de muestra en braze-examples.
Selecciona la pestaña del tipo de datos que quieres sincronizar.
Cada fila necesita exactamente un identificador de usuario y una columna PAYLOAD. Un archivo de origen puede contener filas con distintos tipos de identificador, pero cada fila individual solo debe usar uno.
| Identificador | Descripción |
|---|---|
EXTERNAL_ID |
Identifica al usuario que quieres actualizar. Debe coincidir con el valor 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 etiquetas diferentes, pero solo un alias_name por cada alias_label. |
BRAZE_ID |
El identificador de usuario de Braze. Lo genera el SDK de Braze, y no se pueden crear nuevos usuarios con un ID de Braze mediante la ingesta de datos en la nube. Para crear nuevos usuarios, especifica un ID de usuario 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 prioriza para las actualizaciones el perfil actualizado más recientemente. Si incluyes tanto el correo electrónico como el 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 prioriza para las actualizaciones el perfil actualizado más recientemente. |
La columna PAYLOAD contiene una cadena JSON con los campos que quieres sincronizar con el usuario en Braze, siguiendo el formato del objeto de atributos del usuario.
Ejemplo JSON
{"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\"}"}
Ejemplo CSV
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""}"

Cada línea de tu archivo de origen debe contener JSON válido; de lo contrario, se omite el archivo.
Los eventos personalizados utilizan las mismas columnas de identificador de usuario que los atributos del usuario. La columna PAYLOAD sigue el formato del objeto de eventos.
{"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}}"}

Cada línea de tu archivo de origen debe contener JSON válido; de lo contrario, se omite el archivo.
Los eventos de compra utilizan las mismas columnas de identificador de usuario que los atributos del usuario. La columna PAYLOAD sigue el formato del objeto de compras.
{"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\"}}"}

Cada línea de tu archivo de origen debe contener JSON válido; de lo contrario, se omite el archivo.
Los archivos de catálogo utilizan identificadores distintos a los de los archivos de datos de usuario. Antes de crear una sincronización de catálogo, crea el catálogo de destino en Braze. Para ver el flujo de trabajo completo del catálogo, consulta Sincronizar y eliminar datos del catálogo.
| Columna | Obligatorio | Descripción |
|---|---|---|
ID |
Sí | El identificador único del artículo del catálogo. Se utiliza para crear, actualizar o eliminar el artículo en Braze. |
PAYLOAD |
Sí | Una cadena JSON con los campos y valores del catálogo que quieres sincronizar. Debe coincidir con el esquema de tu catálogo en Braze. |
DELETED |
No | Cuando es true, el artículo del catálogo con el ID coincidente se elimina del catálogo en Braze. Omite esta columna o establécela en false para las operaciones de creación o actualización. |
Ejemplo JSON
{"id":"85","payload":"{\"product_name\":\"Product 85\",\"price\":85.85}"}
{"id":"86","payload":"{\"product_name\":\"Product 86\",\"price\":86.86}"}
{"id":"1","payload":"{\"product_name\":\"Product 1\",\"price\":1.01}","deleted":true}
Ejemplo CSV con la columna DELETED
ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
86,"{""product_name"": ""Product 86"", ""price"": 86.86}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true
Ejemplo CSV sin la columna DELETED
ID,PAYLOAD
85,"{""product_name"": ""Product 85"", ""price"": 85.85}"
86,"{""product_name"": ""Product 86"", ""price"": 86.86}"
Antes de crear una sincronización de objetos de datos, crea el tipo de objeto de datos y sus campos en Braze. Para ver el flujo de trabajo completo, consulta Sincronizar objetos de datos.
A diferencia de las fuentes de almacén de datos, las fuentes de almacenamiento de archivos incluyen los campos del objeto de datos en una columna PAYLOAD en lugar de usar una columna por campo.
| Columna | Obligatorio | Descripción |
|---|---|---|
OBJECT_ID |
Sí | El identificador del registro del objeto de datos. Se utiliza para crear, actualizar o eliminar el registro en Braze. |
PAYLOAD |
Sí | Una cadena JSON con los campos y valores que quieres sincronizar. Cada clave debe coincidir con un campo definido en el tipo de objeto de datos en Braze, incluidas las mayúsculas y minúsculas. |
DELETED |
No | Cuando es true, el registro con el OBJECT_ID coincidente se elimina en Braze. Omite esta columna o establécela en false para las operaciones de creación o actualización. |
Ejemplo JSON
{"object_id":"acct-001","payload":"{\"name\":\"Acme Corp\",\"team_id\":42}"}
{"object_id":"acct-002","payload":"{\"name\":\"Initech\",\"team_id\":17}"}
{"object_id":"acct-003","payload":"{\"name\":\"Hooli\",\"team_id\":5}","deleted":true}
Ejemplo CSV
OBJECT_ID,PAYLOAD,DELETED
acct-001,"{""name"": ""Acme Corp"", ""team_id"": 42}",false
acct-002,"{""name"": ""Initech"", ""team_id"": 17}",false
acct-003,"{""name"": ""Hooli"", ""team_id"": 5}",true
Usa esta sincronización para conectar usuarios con registros de objetos de datos, por ejemplo, para vincular usuarios con las cuentas a las que pertenecen. Crea la relación en Braze antes de sincronizarla.
Cada fila necesita OBJECT_ID y al menos un identificador de usuario.
| Columna | Obligatorio | Descripción |
|---|---|---|
OBJECT_ID |
Sí | El identificador del registro del objeto de datos con el que está relacionado el usuario. |
EXTERNAL_ID |
Sí, al menos un identificador de usuario por fila | Coincide con el external_id utilizado en Braze. |
ALIAS_NAME y ALIAS_LABEL |
Sí, al menos un identificador de usuario por fila | Ambas columnas juntas identifican al usuario por su alias. |
EMAIL |
Sí, al menos un identificador de usuario por fila | La dirección de correo electrónico del usuario. |
PHONE |
Sí, al menos un identificador de usuario por fila | El número de teléfono del usuario. |
PAYLOAD |
No | Una cadena JSON con los campos y valores de la propia relación. |
DELETED |
No | Cuando es true, se elimina la relación entre el registro y el usuario. |

A diferencia de las sincronizaciones de atributos del usuario, BRAZE_ID no se admite en las sincronizaciones de relaciones de usuario. Usa uno de los identificadores indicados anteriormente.
Ejemplo JSON
{"object_id":"acct-001","external_id":"user-1","payload":"{\"role\":\"admin\"}"}
{"object_id":"acct-001","email":"[email protected]","payload":"{\"role\":\"member\"}"}
{"object_id":"acct-002","external_id":"user-9","deleted":true}
Usa esta sincronización para conectar registros de objetos de datos entre sí, por ejemplo, para vincular cuentas con sus cuentas principales. Crea la relación en Braze antes de sincronizarla.
| Columna | Obligatorio | Descripción |
|---|---|---|
OBJECT_ID |
Sí | El registro desde el que parte la relación. |
RELATED_OBJECT_ID |
Sí | El registro al que apunta la relación. |
PAYLOAD |
No | Una cadena JSON con los campos y valores de la propia relación. |
DELETED |
No | Cuando es true, se elimina la relación entre los dos registros. |
Ejemplo JSON
{"object_id":"acct-001","related_object_id":"acct-010","payload":"{\"tier\":\"parent\"}"}
{"object_id":"acct-001","related_object_id":"acct-011","payload":"{\"tier\":\"parent\"}"}
{"object_id":"acct-002","related_object_id":"acct-020","deleted":true}
Los desencadenantes de Canvas hacen posible la personalización sin copia. Para ver la configuración del Canvas de destino y otras consideraciones, consulta Personalización sin copia.
| Campo | Obligatorio | Descripción |
|---|---|---|
EXTERNAL_ID |
Sí, uno de external_id o alias_name y alias_label |
Identifica al usuario que quieres actualizar. Debe coincidir con el valor external_id utilizado en Braze. |
ALIAS_NAME y ALIAS_LABEL |
Sí, uno de external_id o 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 etiquetas diferentes, pero solo un alias_name por cada alias_label. |
PROPERTIES |
Sí | Cadena JSON con los campos que quieres poner a disposición como propiedades de personalización en tu Canvas. Debe contener información específica del usuario. |
Para empezar, selecciona el tipo de datos Desencadenantes de Canvas al crear una nueva sincronización.
Para eliminar perfiles de usuario en Braze mediante archivos de tu contenedor de origen:
- Crea una nueva sincronización de ingesta de datos en la nube con la misma configuración que para las demás sincronizaciones.
- Al configurar la sincronización en Braze, establece Tipo de datos en Eliminar usuarios.
- Sube a tu contenedor de origen archivos que contengan solo columnas de identificador de usuario. No incluyas una columna
PAYLOAD: para evitar eliminaciones accidentales, la sincronización falla si hay una carga útil.
Cada fila del archivo debe identificar exactamente a un usuario mediante uno de los siguientes identificadores:
| 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 su alias. |
BRAZE_ID |
ID de usuario generado por Braze (solo usuarios existentes). |
Ejemplo JSON
{"external_id":"user-to-delete-001"}
{"external_id":"user-to-delete-002"}
{"braze_id":"braze-id-from-profile"}
Ejemplo CSV
external_id
user-to-delete-001
user-to-delete-002
Cuando se ejecuta la sincronización, Braze procesa los archivos nuevos del contenedor y elimina los perfiles de usuario correspondientes.

La eliminación de usuarios es permanente y no se puede deshacer. Incluye solo a los usuarios que quieras eliminar. Para más información, consulta Eliminar usuarios con la ingesta de datos en la nube.
Eliminar elementos del catálogo
Para eliminar artículos de un catálogo mediante el almacenamiento de archivos:
- Usa la misma sincronización que utilizas para sincronizar datos del catálogo (tipo de datos Catálogos).
- En tus archivos CSV o JSON, añade una columna opcional
deleted(oDELETED). - Establece
deletedentruepara cualquier artículo que quieras eliminar del catálogo en Braze.
Cada fila sigue necesitando ID y PAYLOAD. En las filas marcadas para eliminación, la carga útil puede ser mínima; Braze elimina el artículo según su ID.
Cuando se ejecuta la sincronización, las filas con deleted: true hacen que se elimine el artículo correspondiente del catálogo en Braze. Para conocer el comportamiento completo de sincronización y eliminación de catálogos, consulta Sincronizar y eliminar datos del catálogo.
Aspectos que debes saber
- Los archivos que se añaden al 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 admite de por sí archivos mucho más grandes, pero la CDI aplica el mismo límite de 512 MB a todas las fuentes de almacenamiento de archivos.
- Aunque no hay ningún límite adicional en el número de filas por archivo, Braze recomienda usar archivos más pequeños para que tus sincronizaciones se ejecuten más rápido. Por ejemplo, un archivo de 500 MB tardaría bastante más en ingerirse que cinco archivos independientes de 100 MB.
- No hay ningún límite adicional en el número de archivos que se cargan en un periodo determinado.
- No se admite la ordenación dentro de los archivos ni entre ellos. Braze recomienda agrupar las actualizaciones en lotes de forma periódica si estás vigilando posibles condiciones de carrera.
- La CDI solo procesa los archivos que se añaden después de crear la sincronización. 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 la CDI los procese, vuelve a cargar en el contenedor de origen los archivos existentes que quieras sincronizar.
Solución de problemas
Subida y procesamiento de archivos
CDI solo procesa los archivos subidos después de crear la sincronización. Cada objeto nuevo desencadena un mensaje OBJECT_FINALIZE a tu tema de Pub/Sub. Para ingerir archivos que ya existen en el contenedor, vuelve a subirlos.
Gestión de errores inesperados en archivos
Si los archivos no se ingieren, comprueba lo siguiente:
- La notificación del contenedor existe. Lista las notificaciones del contenedor con
gcloud storage buckets notifications list gs://YOUR-BUCKET-NAME. - El agente de servicio de Cloud Storage tiene
roles/pubsub.publisheren el tema. - La cuenta de servicio de Braze tiene permiso de consumo en la suscripción (
pubsub.subscriptions.consume, asignado mediante el rol personalizado oroles/pubsub.subscriber). - La suscripción no tiene configurada una cola de mensajes fallidos. Braze no admite colas de mensajes fallidos para las suscripciones de ingesta de datos en la nube.
Para obtener más información, consulta Notificaciones de Pub/Sub para Cloud Storage en la documentación de Google Cloud.
Tu configuración confía en identidades distintas de tu espacio de trabajo
Si usas Workload Identity Federation, la prueba de conexión puede fallar con el siguiente error:
Your workload identity pool trusts every Braze customer, not only this workspace. Braze authenticated against it with a test identity (000000000000000000000000) that belongs to no Braze workspace, and your Google Cloud project accepted it, so another Braze customer could read this data. Grant the Workload Identity User role on your service account to the full Braze principal shown on the credential screen (principal://…/subject/<full ARN>) rather than to the role (principalSet://…/attribute.aws_role/…); restricting the pool provider’s attribute condition to that same principal works as well. Then test the connection again.
Esto significa que Google aceptó la identidad de prueba de Braze tanto en el intercambio de tokens como en la suplantación de identidad de la cuenta de servicio, como se describe en Cómo prueba Braze la conexión. Este error suele producirse cuando la cuenta de servicio concede acceso a todas las identidades del grupo, o a identidades filtradas por aws_role.
Para corregir este error:
- En la consola de Google Cloud, abre la cuenta de servicio y selecciona la pestaña Permisos.
- Busca todas las entidades principales con el rol Workload Identity User que empiecen por
principalSet://y hagan referencia a tu grupo. Quita el rol de cada una de ellas. - Asegúrate de que tu entidad principal completa tenga el rol, como se describe en Vincular la entidad principal de Braze a la cuenta de servicio.
- Ve a IAM y administración > IAM y comprueba si hay concesiones de Workload Identity User a nivel de proyecto para tu grupo. Elimínalas.
- Vuelve a probar la conexión.
Como alternativa, restringe la condición de atributo del proveedor a tu entidad principal completa, como se describe en Restringir el proveedor a tu entidad principal (opcional). Así, Google rechaza cualquier otra identidad en el intercambio de tokens. Aun así, te recomendamos conceder acceso únicamente a tu entidad principal completa.
Braze no pudo confirmar que tu grupo confíe solo en este espacio de trabajo
Si usas Workload Identity Federation, la prueba de conexión puede fallar con el siguiente error:
Braze could not confirm that your workload identity pool trusts only this workspace. The check needs Google to explicitly refuse an identity that is not yours, and this attempt failed for another reason instead. Please try again; if it keeps happening, contact support.
La comprobación de Braze descrita en Cómo prueba Braze la conexión no llegó a un resultado. Por ejemplo, un error de red o un error temporal de Google Cloud interrumpió la comprobación. Este error no significa que tu configuración sea demasiado amplia. Vuelve a probar la conexión. Si el error persiste, ponte en contacto con el soporte de Braze.
Permiso denegado cuando Braze suplanta la identidad de la cuenta de servicio
Si usas Workload Identity Federation y la prueba de conexión falla con un error de permisos en iam.serviceAccounts.getAccessToken, comprueba lo siguiente:
- La pestaña Permisos de la cuenta de servicio muestra el rol Workload Identity User para una entidad principal que termina en el ARN completo de tu entidad principal de Braze, copiado de un formulario de credenciales de BigQuery o Google Cloud Storage en el mismo espacio de trabajo.
- La API IAM Service Account Credentials está habilitada.
- Has esperado unos minutos desde que concediste el acceso.
Se rechaza el intercambio de tokens
Si usas Workload Identity Federation y la prueba de conexión falla en el intercambio de tokens de Google Security Token Service, comprueba lo siguiente:
- El número de proyecto, el ID del grupo y el ID del proveedor que introdujiste en Braze coinciden con tu configuración de Google Cloud.
- El ID de cuenta de AWS del proveedor coincide con el ID de cuenta del ARN de la entidad principal de Braze.
- Si estableciste una condición de atributo, contiene el ARN completo de tu entidad principal, exactamente como lo copiaste.
- Si estableciste audiencias permitidas personalizadas, incluyen el nombre completo del recurso del proveedor.
- El grupo y el proveedor están habilitados.
Error de objeto de integración incorrecto
Este error se produce cuando dos o más espacios de trabajo tienen integraciones que apuntan al mismo contenedor o carpeta de almacenamiento en el cloud. Cada ubicación de almacenamiento en el cloud solo puede usarla una integración a la vez. Para conocer los pasos de resolución, consulta las preguntas frecuentes.
Páginas relacionadas
- Configuración de tablas para conocer las columnas obligatorias y el formato de la carga útil
- Buenas prácticas para la programación de sincronizaciones y el uso eficiente de los puntos de datos
- Registros de sincronización y observabilidad para supervisar las ejecuciones de sincronización
- Preguntas frecuentes para resolver dudas comunes sobre todas las fuentes