Ingesta de datos en la nube para Google BigQuery
Esta página cubre todo lo que necesitas para sincronizar datos de Google BigQuery con Braze mediante la ingesta de datos en la nube (CDI): los recursos que debes crear en Google Cloud, cómo conectar el origen y crear una sincronización en Braze, la tabla de origen para cada tipo de datos y la solución de problemas específica de BigQuery.
Resumen de la configuración
- En tu cuenta de BigQuery, configura las tablas o vistas que quieras sincronizar con Braze.
- Crea una cuenta de servicio. Concédele permiso para ejecutar trabajos de consulta y acceso de lectura a los conjuntos de datos que contienen los datos que quieres sincronizar. Si la cuenta de servicio y tus datos están en proyectos diferentes, estos permisos se conceden en proyectos distintos. Para más información, consulta Dónde conceder cada permiso.
- Configura cómo accede Braze a la cuenta de servicio mediante uno de los métodos de autenticación compatibles.
- Crea un nuevo origen de datos y una sincronización en el panel de Braze.
- Valida la integración e inicia la sincronización.
Paso 1: Configura tu tabla de origen
Los pasos de esta sección crean una tabla con una columna PAYLOAD. Si prefieres dar forma a tus datos en el paso Definición de datos, puedes usar una tabla o vista existente. En ese caso, omite el paso de creación de la tabla y concede a Braze acceso de lectura a las tablas o vistas que quieras sincronizar. Para comparar las opciones, consulta Elegir una opción de definición de datos.
Puedes dar al proyecto, al conjunto de datos y a la tabla el nombre que quieras, pero los nombres de las columnas deben coincidir con las definiciones de las pestañas siguientes. También puedes usar una vista o una vista materializada en lugar de una tabla.
Si quieres, configura un nuevo proyecto o conjunto de datos para alojar tu tabla de origen:
CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Si usas una columna PAYLOAD, tu tabla o vista de origen puede incluir columnas que no aparecen en las pestañas siguientes (por ejemplo, de auditoría o hashing). Braze solo lee las columnas descritas en estas pestañas; las demás columnas no se usan durante las sincronizaciones de Cloud Data Ingestion.
Selecciona la pestaña del tipo de datos que quieres sincronizar.
Los atributos del usuario, los eventos personalizados y los eventos de compra usan la misma estructura de tabla de origen. Solo cambia el contenido de PAYLOAD.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
--At least one of external_id, alias_name and alias_label, or braze_id is required
external_id STRING,
--If using user alias, both alias_name and alias_label are required
alias_name STRING,
alias_label STRING,
--braze_id can only be used to update existing users created through the Braze SDK
braze_id STRING,
--If you include both email and phone, email is used as the primary identifier
email STRING,
phone STRING,
payload JSON
);
| Nombre del campo | Tipo | Modo |
|---|---|---|
UPDATED_AT |
TIMESTAMP | REQUIRED |
PAYLOAD |
JSON | REQUIRED |
EXTERNAL_ID |
STRING | NULLABLE |
ALIAS_NAME |
STRING | NULLABLE |
ALIAS_LABEL |
STRING | NULLABLE |
BRAZE_ID |
STRING | NULLABLE |
EMAIL |
STRING | NULLABLE |
PHONE |
STRING | NULLABLE |
UPDATED_AT: la hora en que esta fila se actualizó o se agregó a la tabla. Braze sincroniza las filas en las queUPDATED_ATes posterior al último valor sincronizado. Las filas que coincidan exactamente con la marca de tiempo límite pueden volver a sincronizarse si hay nuevas filas que comparten esa misma marca de tiempo.- Columnas de identificador de usuario: tu tabla puede contener una o más columnas de identificador de usuario. Cada fila solo debe contener un identificador (ya sea
external_id, la combinación dealias_nameyalias_label,braze_id,emailophone). Una tabla de origen puede tener columnas para uno, dos, tres, cuatro o los cinco tipos de identificador.EXTERNAL_ID: identifica al usuario que quieres actualizar. Debe coincidir con el valor deexternal_idque se usa en Braze.ALIAS_NAMEyALIAS_LABEL: estas dos columnas crean un objeto de alias de usuario.alias_namedebe ser un identificador único, yalias_labelespecifica el tipo de alias. Los usuarios pueden tener varios alias con diferentes etiquetas, pero solo unalias_namepor cadaalias_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, el correo electrónico se usa 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.
PAYLOAD: es una cadena JSON con los campos que quieres sincronizar con el usuario en Braze.
En las sincronizaciones de atributos, PAYLOAD sigue el formato del objeto de atributos del usuario. Puedes incluir atributos personalizados anidados, matrices de objetos y estados del grupo de suscripción. Para ver ejemplos de carga útil, consulta Configuración de la tabla.

Particionamiento de BigQuery
CDI admite particiones para BigQuery. Si particionas por una función de UPDATED_AT (por ejemplo, con una granularidad de día, semana u hora, según el tamaño de tu conjunto de datos), BigQuery puede reducir los datos que necesita escanear. Esto mejora el rendimiento y la eficiencia en tablas muy grandes.
No particiones por ningún otro campo. Prueba distintas configuraciones para encontrar la que mejor se adapte a tus datos.
Todas las consultas de CDI filtran por UPDATED_AT, pero este comportamiento podría cambiar. Diseña el esquema de tu tabla para que no requiera que las consultas incluyan esta cláusula.
Para más información, consulta la documentación sobre particionamiento de BigQuery.
Los eventos personalizados usan la misma tabla de origen que los atributos del usuario. Crea la tabla que aparece en la pestaña Atributos del usuario y luego rellena PAYLOAD con un objeto de eventos.
Para sincronizar eventos, es obligatorio indicar un nombre de evento. Usa para el campo time una cadena ISO 8601 o el formato yyyy-MM-dd'T'HH:mm:ss:SSSZ. Si el campo time no está presente, Braze usa el valor de la columna UPDATED_AT como hora del evento. Los demás campos, como app_id y properties, son opcionales.
Puedes sincronizar un evento por fila.
{
"app_id" : "your-app-id",
"name" : "rented_movie",
"time" : "2013-07-16T19:20:45+01:00",
"properties": {
"movie": "The Sad Egg",
"director": "Alex Smith"
}
}
Los eventos de compra usan la misma tabla de origen que los atributos del usuario. Crea la tabla que aparece en la pestaña Atributos del usuario y luego rellena PAYLOAD con un objeto de compras.
Para sincronizar eventos de compra, product_id, currency y price son obligatorios. Usa para el campo opcional time una cadena ISO 8601 o el formato yyyy-MM-dd'T'HH:mm:ss:SSSZ. Si el campo time no está presente, Braze usa el valor de la columna UPDATED_AT como hora del evento. Los demás campos, como app_id, quantity y properties, son opcionales.
Puedes sincronizar un evento de compra por fila.
{
"app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
"product_id" : "Completed Order",
"currency" : "USD",
"price" : 219.98,
"time" : "2013-07-16T19:20:30+01:00",
"properties" : {
"products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99 },
{ "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99 }
]
}
}
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.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CATALOGS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
id STRING,
payload JSON,
deleted BOOLEAN
);
| Nombre del campo | Tipo | Modo |
|---|---|---|
UPDATED_AT |
TIMESTAMP | REQUIRED |
PAYLOAD |
JSON | REQUIRED |
ID |
STRING | REQUIRED |
DELETED |
BOOLEAN | OPTIONAL |
El nombre de la integración debe coincidir exactamente con el nombre del catálogo que creaste en Braze.
Braze recomienda crear una vista a partir de los datos de tu catálogo para que la tabla de origen se actualice por completo cada vez que se ejecute una sincronización. Por ejemplo, si tienes una tabla de datos de productos (product_catalog_1) con product_id y tres atributos adicionales, podrías sincronizar la siguiente vista:
CREATE view IF NOT EXISTS BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS (SELECT
last_updated as UPDATED_AT,
product_id as ID,
TO_JSON(
STRUCT(
attribute_1,
attribute_2,
attribute_3,
)
) as PAYLOAD
FROM `BRAZE_CLOUD_PRODUCTION.INGESTION.product_catalog_1`);
Antes de crear una sincronización de objetos de datos, crea en Braze el tipo de objeto de datos y sus campos. Para ver el flujo de trabajo completo, consulta Sincronizar objetos de datos.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.ACCOUNTS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
object_id STRING,
payload JSON,
deleted BOOLEAN
);
| Nombre del campo | Tipo | ¿Obligatorio? |
|---|---|---|
UPDATED_AT |
TIMESTAMP | Sí |
OBJECT_ID |
STRING | Sí |
PAYLOAD |
JSON | Sí |
DELETED |
BOOLEAN | Opcional |
UPDATED_AT: la hora en que se actualizó o se añadió esta fila a la tabla. Braze sincroniza las filas en las queUPDATED_ATes posterior al último valor sincronizado. Es posible que las filas con la marca de tiempo límite exacta se vuelvan a sincronizar si hay filas nuevas que comparten esa misma marca de tiempo.OBJECT_ID: el identificador del registro del objeto de datos. Debe coincidir con el valor deobject_idque se utiliza en Braze para este tipo de objeto de datos.PAYLOAD: una cadena JSON con los campos y valores que se van a sincronizar. Cada clave debe coincidir con un campo definido en el tipo de objeto de datos en Braze.DELETED: cuando estrue, Braze elimina el registro en lugar de actualizarlo. Deja este valor nulo o enfalsepara las filas que quieras crear o actualizar.
Los nombres de campo dentro de PAYLOAD distinguen entre mayúsculas y minúsculas. Una clave llamada NAME no coincide con un campo llamado name. Si las mayúsculas y minúsculas no coinciden, la validación indica que la clave es un campo no definido y que falta el campo que debía rellenar. Asigna a tus claves exactamente los mismos nombres con los que aparecen los campos en Configuración de datos > Objetos de datos.
Braze no crea ni modifica tipos de objetos de datos durante una sincronización. Define el tipo y todos sus campos en Braze antes de crear la sincronización. Para añadir un campo más adelante, añádelo primero al tipo y, después, actualiza tu tabla de origen o tu consulta.
Por ejemplo, un valor de PAYLOAD para una cuenta con los campos name y team_id tiene este aspecto:
{"name": "Acme Corp", "team_id": 42}
En el paso Definición de datos, selecciona el tipo de datos Objetos de datos y luego elige tu Tipo de objeto de datos. Las sincronizaciones de objetos de datos admiten Tabla y SQL.
Usa esta sincronización para conectar usuarios con registros de objetos de datos, por ejemplo, para vincular usuarios a las cuentas a las que pertenecen. Crea la relación en Braze antes de sincronizarla.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.ACCOUNT_USERS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
object_id STRING,
--At least one of external_id, alias_name and alias_label, email, or phone is required
external_id STRING,
--If using user alias, both alias_name and alias_label are required
alias_name STRING,
alias_label STRING,
email STRING,
phone STRING,
payload JSON,
deleted BOOLEAN
);
| Nombre del campo | Tipo | ¿Obligatorio? |
|---|---|---|
UPDATED_AT |
TIMESTAMP | Sí |
OBJECT_ID |
STRING | Sí |
EXTERNAL_ID |
STRING | Opcional |
ALIAS_NAME |
STRING | Opcional |
ALIAS_LABEL |
STRING | Opcional |
EMAIL |
STRING | Opcional |
PHONE |
STRING | Opcional |
PAYLOAD |
JSON | Opcional |
DELETED |
BOOLEAN | Opcional |
Cada fila necesita OBJECT_ID y al menos un identificador de usuario: EXTERNAL_ID, la combinación de ALIAS_NAME y ALIAS_LABEL, EMAIL o PHONE. Usa PAYLOAD para cualquier campo definido en la propia relación.

BRAZE_ID no es compatible con las sincronizaciones de relaciones de usuario, a diferencia de las sincronizaciones de atributos del usuario. Usa uno de los identificadores mencionados anteriormente.
UPDATED_AT: la hora en que se actualizó o se añadió esta fila a la tabla. Braze sincroniza las filas en las queUPDATED_ATes posterior al último valor sincronizado. Es posible que las filas con la marca de tiempo límite exacta se vuelvan a sincronizar si hay filas nuevas que comparten esa misma marca de tiempo.OBJECT_ID: el identificador del registro del objeto de datos. Debe coincidir con el valor deobject_idque se utiliza en Braze para este tipo de objeto de datos.PAYLOAD: una cadena JSON con los campos y valores que se van a sincronizar. Cada clave debe coincidir con un campo definido en el tipo de objeto de datos en Braze.DELETED: cuando estrue, Braze elimina el registro en lugar de actualizarlo. Deja este valor nulo o enfalsepara las filas que quieras crear o actualizar.
Los nombres de campo dentro de PAYLOAD distinguen entre mayúsculas y minúsculas. Una clave llamada NAME no coincide con un campo llamado name. Si las mayúsculas y minúsculas no coinciden, la validación indica que la clave es un campo no definido y que falta el campo que debía rellenar. Asigna a tus claves exactamente los mismos nombres con los que aparecen los campos en Configuración de datos > Objetos de datos.
Braze no crea ni modifica tipos de objetos de datos durante una sincronización. Define el tipo y todos sus campos en Braze antes de crear la sincronización. Para añadir un campo más adelante, añádelo primero al tipo y, después, actualiza tu tabla de origen o tu consulta.
En el paso Definición de datos, selecciona el tipo de datos Relaciones de usuario de objetos de datos y luego elige un Nombre de la relación, como User (Account-User).
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.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.ACCOUNT_SUBACCOUNTS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
object_id STRING,
related_object_id STRING,
payload JSON,
deleted BOOLEAN
);
| Nombre del campo | Tipo | ¿Obligatorio? |
|---|---|---|
UPDATED_AT |
TIMESTAMP | Sí |
OBJECT_ID |
STRING | Sí |
RELATED_OBJECT_ID |
STRING | Sí |
PAYLOAD |
JSON | Opcional |
DELETED |
BOOLEAN | Opcional |
OBJECT_ID es el registro desde el que parte la relación, y RELATED_OBJECT_ID es el registro al que apunta. Ambos son obligatorios en todas las filas. Usa PAYLOAD para cualquier campo definido en la propia relación.
UPDATED_AT: la hora en que se actualizó o se añadió esta fila a la tabla. Braze sincroniza las filas en las queUPDATED_ATes posterior al último valor sincronizado. Es posible que las filas con la marca de tiempo límite exacta se vuelvan a sincronizar si hay filas nuevas que comparten esa misma marca de tiempo.OBJECT_ID: el identificador del registro del objeto de datos. Debe coincidir con el valor deobject_idque se utiliza en Braze para este tipo de objeto de datos.PAYLOAD: una cadena JSON con los campos y valores que se van a sincronizar. Cada clave debe coincidir con un campo definido en el tipo de objeto de datos en Braze.DELETED: cuando estrue, Braze elimina el registro en lugar de actualizarlo. Deja este valor nulo o enfalsepara las filas que quieras crear o actualizar.
Los nombres de campo dentro de PAYLOAD distinguen entre mayúsculas y minúsculas. Una clave llamada NAME no coincide con un campo llamado name. Si las mayúsculas y minúsculas no coinciden, la validación indica que la clave es un campo no definido y que falta el campo que debía rellenar. Asigna a tus claves exactamente los mismos nombres con los que aparecen los campos en Configuración de datos > Objetos de datos.
Braze no crea ni modifica tipos de objetos de datos durante una sincronización. Define el tipo y todos sus campos en Braze antes de crear la sincronización. Para añadir un campo más adelante, añádelo primero al tipo y, después, actualiza tu tabla de origen o tu consulta.
En el paso Definición de datos, selecciona el tipo de datos Relaciones de objetos de datos y luego elige un Nombre de la relación, como Subaccount (Account-Account).
Los desencadenantes de Canvas impulsan la personalización sin copia de datos. Para ver la configuración del Canvas de destino y otras consideraciones, consulta Personalización sin copia de datos.
CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC`
(
updated_at TIMESTAMP DEFAULT current_timestamp,
--At least one of external_id or alias_name and alias_label is required
external_id STRING,
--If using user alias, both alias_name and alias_label are required
alias_name STRING,
alias_label STRING,
properties JSON
);
| Nombre del campo | Tipo | ¿Obligatorio? |
|---|---|---|
UPDATED_AT |
TIMESTAMP | Sí |
PROPERTIES |
JSON | Sí |
EXTERNAL_ID |
STRING | NULLABLE |
ALIAS_NAME |
STRING | NULLABLE |
ALIAS_LABEL |
STRING | NULLABLE |
Las sincronizaciones de desencadenantes de Canvas se diferencian de otras sincronizaciones de datos de usuario en tres aspectos:
- Solo se admiten como identificadores el ID externo o el alias de usuario. El correo electrónico y los números de teléfono no son identificadores admitidos.
- Solo se pueden sincronizar usuarios existentes de Braze. No se pueden crear usuarios nuevos.
PROPERTIESsustituye a la columnaPAYLOAD. Se trata de una cadena JSON con los campos que quieres usar como propiedades de entrada en Canvas para la personalización.
Tu tabla de desencadenantes de Canvas necesita las siguientes columnas:
UPDATED_AT: la hora en que esta fila se actualizó o se añadió a la tabla. Braze sincroniza las filas en las queUPDATED_ATes posterior al último valor sincronizado. Las filas con la marca de tiempo exacta del límite pueden volver a sincronizarse si hay filas nuevas que comparten esa misma marca de tiempo.EXTERNAL_ID, o bienALIAS_NAMEyALIAS_LABEL, como columna de identificador de usuario. Estas columnas identifican a los usuarios para los que quieres desencadenar la mensajería de Canvas.EXTERNAL_ID: identifica al usuario que entrará en el Canvas. Debe coincidir con el valor deexternal_idque se utiliza en Braze.ALIAS_NAMEyALIAS_LABEL: estas columnas crean un objeto de alias de usuario.alias_namedebe ser un identificador único yalias_labelespecifica el tipo de alias. Los usuarios pueden tener varios alias con etiquetas diferentes, pero solo unalias_namepor cadaalias_label.
PROPERTIES: una cadena JSON de campos que estarán disponibles como propiedades de personalización en tu Canvas. Debe contener información específica del usuario.

No es necesario incluir propiedades en todas las filas ni para todos los usuarios. Sin embargo, los valores de las propiedades deben ser una cadena JSON válida. Introduce una cadena {} vacía si la fila no tiene propiedades.
Para empezar, selecciona el tipo de datos Desencadenantes de Canvas al crear una nueva sincronización.
Las tablas de origen para eliminaciones de usuarios deben incluir uno o más tipos de identificador de usuario y una marca de tiempo UPDATED_AT. Las columnas de carga útil no son compatibles con los datos de eliminación de usuarios.
UPDATED_AT- La hora en que se actualizó o agregó esta fila a la tabla. Braze sincroniza las filas en las queUPDATED_ATes posterior al último valor sincronizado. Las filas con la marca de tiempo exacta del límite podrían volver a sincronizarse si hay filas nuevas que comparten esa misma marca de tiempo.- Columnas de identificador de usuario - Cada fila solo debe contener un identificador:
external_id, la combinación dealias_nameyalias_label, obraze_id. Una tabla de origen puede contener columnas para uno, dos o los tres tipos de identificador.EXTERNAL_ID- Identifica al usuario que quieres actualizar. Debe coincidir con el valor deexternal_idutilizado en Braze.ALIAS_NAMEyALIAS_LABEL- Estas dos columnas crean un objeto de alias de usuario.alias_namedebe ser un identificador único, yalias_labelespecifica el tipo de alias. Los usuarios pueden tener varios alias con diferentes etiquetas, pero solo unalias_namepor cadaalias_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.

No incluyas una columna PAYLOAD en tu tabla para la eliminación de usuarios. Para evitar la eliminación accidental y permanente de usuarios, la sincronización falla si se proporciona una columna de carga útil en la tabla de origen. Puedes incluir cualquier otra columna, pero Braze las ignora.
Crea una tabla con los siguientes campos:
| Nombre del campo | Tipo | Modo |
|---|---|---|
UPDATED_AT |
TIMESTAMP | REQUIRED |
EXTERNAL_ID |
STRING | NULLABLE |
ALIAS_NAME |
STRING | NULLABLE |
ALIAS_LABEL |
STRING | NULLABLE |
BRAZE_ID |
STRING | NULLABLE |
En la página Crear sincronización de importación, establece el Tipo de datos en Eliminar usuarios para que se realicen las acciones adecuadas durante la ejecución de la integración. Para más información, consulta Eliminar usuarios con Cloud Data Ingestion.

La eliminación de perfiles de usuario no se puede deshacer. La acción de eliminación quita a los usuarios de forma permanente, lo que puede provocar discrepancias en tus datos. Para más detalles, consulta Efectos de eliminar perfiles de usuario.
Paso 2: Crea una cuenta de servicio y concede permisos
Crea una cuenta de servicio en GCP para que Braze la use para conectarse y leer datos de tus tablas. La cuenta de servicio debe tener los siguientes permisos:
- BigQuery Connection User: Permite a Braze establecer conexiones.
- BigQuery User: Proporciona a Braze acceso para ejecutar consultas, leer metadatos de conjuntos de datos y enumerar tablas.
- BigQuery Data Viewer: Proporciona a Braze acceso para ver los conjuntos de datos y su contenido.
- BigQuery Job User: Proporciona a Braze acceso para ejecutar trabajos.
Dónde conceder cada permiso
Cada consulta de BigQuery se ejecuta como un trabajo en un proyecto y puede leer tablas de otros proyectos. BigQuery comprueba cada permiso en su propio proyecto. Si tu cuenta de servicio y tus datos están en el mismo proyecto, concede todos los roles en ese proyecto. De lo contrario, concede cada rol en el proyecto indicado en la siguiente tabla.
| Rol | Dónde concederlo |
|---|---|
| BigQuery Job User BigQuery User BigQuery Connection User |
Depende de tu método de autenticación: Clave de cuenta de servicio: El proyecto en el que se creó la cuenta de servicio. Es el valor project_id del archivo de clave JSON y puede ser distinto del Proyecto que introduces en Braze.Workload Identity Federation: El proyecto que introduces en el campo Proyecto de tu origen de Braze. Braze ejecuta los trabajos de consulta en este proyecto, y BigQuery le factura las consultas. |
| BigQuery Data Viewer | Los conjuntos de datos o tablas que sincronizas, en el proyecto que introduces en el campo Proyecto de tu origen de Braze. Si sincronizas una vista o usas una consulta SQL que lee de otros conjuntos de datos, concede también este rol en esos conjuntos de datos. |

Si te autenticas con una clave de cuenta de servicio y tu cuenta de servicio se creó en un proyecto distinto al de tus datos, concede BigQuery Job User en el proyecto de la cuenta de servicio y BigQuery Data Viewer en los conjuntos de datos que sincronizas. Si la cuenta de servicio no tiene bigquery.jobs.create en su propio proyecto, las sincronizaciones fallan con un error 403 Access Denied.
Paso 3: Configura 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 BigQuery como de Google Cloud Storage. Si ya completaste estos pasos para una fuente de Google Cloud Storage, 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 BigQuery 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.
Paso 4: Permite el acceso a las IP de Braze
Si tienes políticas de red, debes dar a Braze acceso de red a tu instancia de BigQuery. Permite el acceso desde las siguientes IP correspondientes a la región de tu panel de Braze.
Para las instancias US-01, US-02, US-03, US-04, US-05, US-06, US-07, estas son las direcciones IP correspondientes:
23.21.118.19134.206.23.17350.16.249.952.4.160.21454.87.8.3454.156.35.25152.54.89.23818.205.178.15
Para la instancia US-08, estas son las direcciones IP correspondientes:
52.151.246.5152.170.163.18240.76.166.15740.76.166.17040.76.166.16740.76.166.16140.76.166.15640.76.166.16640.76.166.16040.88.51.7452.154.67.1740.76.166.8040.76.166.8440.76.166.8540.76.166.8140.76.166.7140.76.166.14440.76.166.145
Para la instancia US-10, estas son las direcciones IP correspondientes:
100.25.232.16435.168.86.17952.7.44.1173.92.153.1835.172.3.12950.19.162.19
Para las instancias EU-01 y EU-02, estas son las direcciones IP correspondientes:
52.58.142.24252.29.193.12135.158.29.22818.157.135.973.123.166.463.64.27.363.65.88.253.68.144.1883.70.107.88
Para la instancia AU-01, estas son las direcciones IP correspondientes:
13.210.1.14513.211.70.15913.238.45.5452.65.73.16754.153.242.23954.206.45.213
Para la instancia ID-01, estas son las direcciones IP correspondientes:
108.136.157.246108.137.30.20716.78.128.7116.78.14.13416.78.162.20843.218.73.35
Para la instancia JP-01, estas son las direcciones IP correspondientes:
13.159.155.21254.199.221.24113.192.23.1654.250.120.13918.181.114.2323.114.38.100
Para la instancia KR-01, estas son las direcciones IP correspondientes:
43.200.215.452.79.67.17552.79.113.603.34.212.9254.116.134.2313.37.197.225
Paso 5: Crea un nuevo origen en el panel de Braze
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, a continuación, selecciona Google BigQuery.
Paso 5.1: Añade la información de conexión de BigQuery y la tabla de origen
Introduce un nombre para tu origen y, a continuación, introduce tus credenciales y la configuración de BigQuery:
- En Nombre de la credencial, introduce una etiqueta que te ayude a identificar estas credenciales en Braze.
- Para el método de autenticación, selecciona el método que configuraste en el Paso 3 e introduce sus credenciales. 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.
Después, introduce los campos de configuración restantes.
Paso 5.2: Prueba la conexión y conéctate al origen
A continuación, selecciona Probar conexión. Cuando se complete correctamente, finaliza la configuración restante y haz clic en Conectar al origen. Si la conexión falla, aparecerá un mensaje de error para ayudarte a solucionar el problema.
Paso 6: Crear una nueva sincronización en el panel de Braze
Ve a Configuración de datos > Ingesta de datos en la nube > Sincronizaciones y selecciona Crear sincronización de datos.
Configura los detalles de la sincronización y define tus datos
Introduce un nombre para tu sincronización. A continuación, selecciona un origen activo y un tipo de datos de sincronización. Después, selecciona un modo de sincronización y define tus datos. Luego, selecciona Vista previa y validar.
Cuando la validación se realice correctamente, aparecerá una vista previa de los datos. Selecciona Siguiente: Notificaciones para continuar. Si la validación falla, aparecerá un mensaje de error para ayudarte a solucionar el problema.

Debes validar correctamente una sincronización antes de avanzar a los siguientes pasos. Si necesitas cerrar la página de creación de la sincronización, selecciona Guardar como borrador para conservar tu trabajo en curso.
Añadir preferencias de notificación
Introduce uno o varios correos electrónicos de contacto para las notificaciones de errores de sincronización. Braze utiliza esta información de contacto para enviar notificaciones sobre errores de integración, como la pérdida inesperada de acceso a una tabla.
Los correos electrónicos de contacto solo reciben notificaciones de errores globales o a nivel de sincronización, como tablas que faltan, permisos y otros. No reciben notificaciones de problemas a nivel de fila. Los errores globales indican problemas críticos con la conexión que impiden que se ejecuten las sincronizaciones.
Estos problemas pueden ser los siguientes:
- Problemas de conectividad
- Falta de recursos
- Problemas de permisos
- El nivel de catálogo se ha quedado sin espacio (solo sincronizaciones de catálogo)
Establecer la programación
Por último, configura tu sincronización como no recurrente o recurrente.
Las sincronizaciones no recurrentes solo se ejecutan cuando seleccionas Sincronizar ahora en el panel o llamas al endpoint Desencadenar una sincronización.
Las sincronizaciones recurrentes pueden ejecutarse con una frecuencia de hasta cada 5 minutos o con tan poca frecuencia como una vez al mes. De forma predeterminada, el intervalo más corto que puedes establecer en el panel es de 15 minutos, lo que ayuda a gestionar los costos de computación de tu almacén y el volumen de solicitudes. Para sincronizar con una frecuencia de hasta cada 5 minutos, ponte en contacto con el soporte de Braze o con tu administrador de éxito de cliente. Braze programa las sincronizaciones recurrentes en UTC.

Debes validar correctamente una integración antes de que pueda pasar del estado Borrador al estado Activo. Si cierras la página de creación, tu integración se guarda y puedes volver a la página de detalles para hacer cambios y validarla.
Ejecutar la sincronización
Una vez activada, tu sincronización se ejecuta según la programación configurada durante la instalación. Si quieres ejecutar la sincronización fuera de su programación o para obtener los datos más recientes, selecciona Sincronizar ahora. Esta ejecución no afecta a las futuras sincronizaciones programadas regularmente. Para iniciar una sincronización automáticamente cuando se actualicen tus datos, llama al endpoint Desencadenar una sincronización desde tu canalización.
Configurar integraciones o usuarios adicionales (opcional)
Puedes configurar varias integraciones con Braze. Al crear sincronizaciones adicionales, puedes reutilizar las credenciales existentes si te conectas a la misma cuenta de BigQuery.
Si reutilizas el mismo usuario en varias integraciones, no podrás eliminarlo en el panel de Braze hasta que lo quites de todas las sincronizaciones activas.
Usa BigQuery como fuente conectada
Una fuente conectada es una alternativa sin copia de datos a la sincronización de datos con Braze. Braze consulta directamente tu instancia de BigQuery para crear Segments de CDI, sin copiar los datos subyacentes. Para conocer los conceptos, las limitaciones y las implicaciones de costos, consulta Fuentes conectadas.
Paso 1: Crea una cuenta de servicio y concede permisos
Crea una cuenta de servicio en GCP para que Braze la use al conectarse y leer datos de tus tablas. La cuenta de servicio debe tener los siguientes permisos:
- BigQuery Connection User: Permite a Braze establecer conexiones.
- BigQuery User: Proporciona a Braze acceso para ejecutar consultas, leer los metadatos de los conjuntos de datos y enumerar las tablas.
- BigQuery Data Viewer: Proporciona a Braze acceso para ver los conjuntos de datos y su contenido.
- BigQuery Job User: Proporciona a Braze acceso para ejecutar trabajos.
- bigquery.tables.create: Proporciona a Braze acceso para crear tablas temporales durante la actualización de un Segment.
Concede estos roles en los proyectos descritos en Dónde conceder cada permiso. Concede bigquery.tables.create en el mismo proyecto que BigQuery Job User.
Esta cuenta de servicio se usa para generar la lista de tablas disponibles en tus extensiones de segmento CDI y para consultar las tablas de origen al crear nuevos Segments. Una vez creada la fuente conectada, Braze detecta los nombres y la descripción de todas las tablas disponibles para el usuario en el esquema de origen.
Puedes conceder acceso a todas las tablas de un conjunto de datos o conceder privilegios solo a tablas específicas. Todas las tablas a las que tenga acceso el rol de Braze estarán disponibles para consultarlas en la extensión de segmento CDI.
El permiso create table es necesario para que Braze pueda crear una tabla con los resultados de la consulta de tu extensión de segmento CDI antes de actualizar el Segment en Braze. Braze crea una tabla temporal por cada Segment, y la tabla solo existe mientras Braze actualiza el Segment.
Después de crear la cuenta de servicio y conceder los permisos, configura cómo accede Braze a ella con uno de los métodos del Paso 3: Configura la autenticación. Si ya configuraste Workload Identity Federation para este proyecto, puedes reutilizarla. Concede a la cuenta de servicio existente los permisos de este paso.
La configuración del acceso a la red es la misma que en el Paso 4.
Paso 2: Crea la fuente conectada en Braze
Ve a Configuración de datos > Ingesta de datos en la nube > Fuentes conectadas, selecciona Añadir origen de datos y, a continuación, selecciona Google BigQuery.
En Configurar origen, introduce lo siguiente:
- Credenciales: Nombre de la credencial y los campos correspondientes a tu método de autenticación. 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.
- Configuración: Proyecto y Conjunto de datos
Elige un nombre para la fuente conectada. Este nombre aparece en la lista de fuentes disponibles cuando creas una nueva extensión de segmento CDI.
Configura un tiempo máximo de ejecución para esta fuente. Braze cancela automáticamente cualquier consulta que supere el tiempo máximo de ejecución. El tiempo máximo de ejecución permitido es de 60 minutos; un tiempo de ejecución menor reduce los costos generados en tu cuenta de BigQuery. Esta configuración se aplica a las consultas que se ejecutan a través de esta fuente, incluidas las sincronizaciones y las extensiones de segmento CDI que la usan.
Selecciona Probar conexión para verificar que la lista de tablas visibles para el usuario es la que esperas y, a continuación, selecciona Hecho. Tu fuente conectada ya está creada y lista para usarse en las extensiones de segmento CDI.
Puedes configurar varias fuentes conectadas con Braze, pero cada fuente debe configurarse para conectarse a un conjunto de datos diferente. Al crear fuentes adicionales, puedes reutilizar las credenciales existentes si te conectas a la misma cuenta de BigQuery.
Formatear una carga útil a partir de columnas existentes
Si prefieres almacenar internamente cada atributo en su propia columna, tienes que convertir esas columnas en una cadena JSON para completar la sincronización con Braze. Usa esta consulta en BigQuery para dar formato a las columnas de origen como campos de CDI.
CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (attribute_1 string,
attribute_2 STRING,
attribute_3 NUMERIC,
my_user_id STRING);
SELECT
CURRENT_TIMESTAMP as UPDATED_AT,
my_user_id as EXTERNAL_ID,
TO_JSON(
STRUCT(
'attribute_1' AS attribute_1,
'attribute_2'AS attribute_2,
'yet_another_attribute'AS attribute_3
)
) as PAYLOAD
FROM BRAZE.EXAMPLE_USER_DATA;
Para ver más recomendaciones de optimización, consulta Prácticas recomendadas de ingesta de datos en la nube.
Solución de problemas
Probar conexión se ejecuta con lentitud
Probar conexión se ejecuta en tu almacén de datos, así que aumentar la capacidad del almacén puede mejorar su velocidad. Usar una instancia SQL sin servidor minimiza el tiempo de calentamiento y mejora el rendimiento de las consultas, pero puede aumentar ligeramente los costos de integración.
El usuario no tiene permiso para consultar la tabla
Si recibes este error, añade permisos de usuario para consultar la tabla.
El usuario no tiene el permiso bigquery.jobs.create en el proyecto
Si recibes este error, la cuenta de servicio no puede ejecutar trabajos de consulta en el proyecto indicado en el error. Concede el rol BigQuery Job User a la cuenta de servicio en ese proyecto. Si te autenticas con una clave de cuenta de servicio, este es el proyecto en el que se creó la cuenta de servicio, que puede ser distinto del proyecto que contiene tus datos. Para más detalles, consulta Dónde conceder cada permiso.
Tu uso superó la cuota personalizada
Si recibes este error, tienes que actualizar tu cuota para poder seguir sincronizando a tu ritmo actual.
No se encontró la tabla en la ubicación {region}
Si recibes este error, verifica que tu tabla esté en el proyecto y el conjunto de datos correctos.
Firma JWT no válida
Si recibes este error, comprueba que el servicio de la API de BigQuery esté habilitado para tu cuenta.
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.
Dónde ejecutar comprobaciones SQL
Ejecuta las comprobaciones de validación directamente en el espacio de trabajo SQL de BigQuery Studio, sobre la misma tabla o vista que usa tu integración de CDI. Para más información, consulta Introducción a BigQuery Studio.
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