Ir al contenido

Ingesta de datos en la nube para Databricks

En esta página encontrarás todo lo que necesitas para sincronizar datos de Databricks con Braze mediante la ingesta de datos en la nube (CDI): los recursos que debes crear en Databricks, cómo conectar la fuente 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 Databricks.

Resumen de la configuración

  1. En tu cuenta de Databricks, configura las tablas o vistas que quieres sincronizar con Braze.
  2. Crea credenciales para Braze con uno de los métodos de autenticación compatibles y permite el acceso a los catálogos y esquemas de Databricks que contienen los datos que quieres sincronizar.
  3. Crea un nuevo origen y una nueva sincronización en el panel de Braze.
  4. 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 ver una comparación de las opciones, consulta Elige una opción de definición de datos.

Puedes nombrar el esquema y la tabla como quieras, pero los nombres de las columnas deben coincidir con las definiciones de las siguientes pestañas. También puedes usar una vista o una vista materializada en lugar de una tabla.

Si lo deseas, configura un nuevo catálogo o esquema para alojar tu tabla de origen:

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Selecciona la pestaña del tipo de datos que quieres sincronizar.

Los atributos de 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 STRING, STRUCT, or MAP
);
Nombre del campo Tipo Modo
UPDATED_AT TIMESTAMP REQUIRED
PAYLOAD STRING, STRUCT o MAP 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 que UPDATED_AT es 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 de alias_name y alias_label, braze_id, email o phone). 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 de external_id que se usa en Braze.
    • ALIAS_NAME y ALIAS_LABEL: estas dos columnas crean un objeto de alias de usuario. alias_name debe ser un identificador único, y alias_label especifica el tipo de alias. Los usuarios pueden tener varios alias con diferentes etiquetas, pero solo un alias_name por 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, 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 o estructura con los campos que quieres sincronizar con el usuario en Braze.

Para las sincronizaciones de atributos, PAYLOAD sigue el formato del objeto de atributos de 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.

Los eventos personalizados usan la misma tabla de origen que los atributos de usuario. Crea la tabla que se muestra en la pestaña Atributos de usuario y, a continuación, rellena PAYLOAD con un objeto de eventos.

Para sincronizar eventos, se necesita un nombre de evento. Da formato al campo time como una cadena ISO 8601 o en 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, incluidos 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 de usuario. Crea la tabla que se muestra en la pestaña Atributos de usuario y, a continuación, rellena PAYLOAD con un objeto de compras.

Para sincronizar eventos de compra, se necesitan product_id, currency y price. Da formato al campo opcional time como una cadena ISO 8601 o en 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, incluidos 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,
  deleted BOOLEAN,
  payload STRING, STRUCT, or MAP
);
Nombre del campo Tipo Modo
UPDATED_AT TIMESTAMP REQUIRED
PAYLOAD STRING, STRUCT o MAP REQUIRED
ID STRING REQUIRED
DELETED BOOLEAN NULLABLE

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 el tipo de objeto de datos y sus campos en Braze. 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 STRING,
  deleted BOOLEAN
);
Nombre del campo Tipo Modo
UPDATED_AT TIMESTAMP REQUIRED
OBJECT_ID STRING REQUIRED
PAYLOAD STRING REQUIRED
DELETED BOOLEAN NULLABLE
  • UPDATED_AT: la hora en que se actualizó o se añadió esta fila a la tabla. Braze sincroniza las filas en las que UPDATED_AT es 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 de object_id que 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 es true, Braze elimina el registro en lugar de actualizarlo. Deja este valor nulo o en false para 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, a continuación, 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 STRING,
  deleted BOOLEAN
);
Nombre del campo Tipo Modo
UPDATED_AT TIMESTAMP REQUIRED
OBJECT_ID STRING REQUIRED
EXTERNAL_ID STRING NULLABLE
ALIAS_NAME STRING NULLABLE
ALIAS_LABEL STRING NULLABLE
EMAIL STRING NULLABLE
PHONE STRING NULLABLE
PAYLOAD STRING NULLABLE
DELETED BOOLEAN NULLABLE

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 los campos definidos 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 que UPDATED_AT es 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 de object_id que 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 es true, Braze elimina el registro en lugar de actualizarlo. Deja este valor nulo o en false para 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 usuarios con objetos de datos y, a continuación, elige un Nombre de la relación, como Usuario (Cuenta-Usuario).

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 STRING,
  deleted BOOLEAN
);
Nombre del campo Tipo Modo
UPDATED_AT TIMESTAMP REQUIRED
OBJECT_ID STRING REQUIRED
RELATED_OBJECT_ID STRING REQUIRED
PAYLOAD STRING NULLABLE
DELETED BOOLEAN NULLABLE

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 cada fila. Usa PAYLOAD para los campos definidos 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 que UPDATED_AT es 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 de object_id que 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 es true, Braze elimina el registro en lugar de actualizarlo. Deja este valor nulo o en false para 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 entre objetos de datos y, a continuación, elige un Nombre de la relación, como Subcuenta (Cuenta-Cuenta).

Los desencadenantes de Canvas hacen posible la personalización sin copia. Para ver la configuración del Canvas de destino y las consideraciones, consulta Personalización sin copia.

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 STRING, STRUCT, or MAP
);
Nombre del campo Tipo Obligatorio
UPDATED_AT TIMESTAMP Sí
PROPERTIES STRING, STRUCT o MAP 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.
  • PROPERTIES sustituye a la columna PAYLOAD. 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 que UPDATED_AT es 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 bien ALIAS_NAME y ALIAS_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 de external_id que se utiliza en Braze.
    • ALIAS_NAME y ALIAS_LABEL: estas 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: 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.

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 que UPDATED_AT es 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 de alias_name y alias_label, o braze_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 de external_id utilizado en Braze.
    • ALIAS_NAME y ALIAS_LABEL - Estas dos columnas crean un objeto de alias de usuario. alias_name debe ser un identificador único, y alias_label especifica el tipo de alias. Los usuarios pueden tener varios alias con diferentes etiquetas, pero solo un alias_name por 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.

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 la ingesta de datos en la nube.

Paso 2: Configura la autenticación

Braze puede conectarse a Databricks con cualquiera de los siguientes métodos de autenticación:

Método Cómo se autentica Braze Qué introduces en Braze
OAuth M2M (recomendado) Braze authenticates as a Databricks service principal using OAuth machine-to-machine (M2M) authentication. Client ID and Client secret
Personal access token Braze authenticates with a token generated in your Databricks workspace. Access token

OAuth M2M

Braze se conecta a tu espacio de trabajo de Databricks como una entidad de servicio mediante la autenticación OAuth de máquina a máquina (M2M). Databricks recomienda OAuth M2M para conexiones desatendidas como la ingesta de datos en la nube. Crea una nueva entidad de servicio para que Braze la utilice y concédele acceso a tu almacén SQL y a tus tablas de origen. Braze necesita los siguientes datos para conectarse:

  • ID de cliente (también llamado ID de aplicación) de la entidad de servicio
  • Secreto de cliente para que Braze se autentique

Crear la entidad de servicio

  1. En tu espacio de trabajo de Databricks, selecciona tu nombre de usuario en la barra superior y, a continuación, selecciona Settings.
  2. Ve a Identity and access y, a continuación, selecciona Manage junto a Service principals.
  3. Selecciona Add service principal > Add new.
  4. Introduce un nombre que te ayude a identificar la entidad de servicio, como “Braze CDI”, y luego selecciona Add.
  5. Selecciona la entidad de servicio que creaste. En la pestaña Configurations, asegúrate de que Databricks SQL access esté seleccionado.

Generar un secreto de cliente

  1. En la página de la entidad de servicio, selecciona la pestaña Secrets y, a continuación, selecciona Generate secret.
  2. Introduce una vigencia para el secreto, en días. Databricks permite una vigencia máxima de 730 días.
  3. Selecciona Generate.
  4. Copia los valores de Secret y Client ID y, a continuación, selecciona Done.

Guarda el ID de cliente y el secreto en un lugar seguro hasta que tengas que introducirlos en el panel de Braze durante el paso de creación de credenciales. Databricks muestra el secreto solo una vez.

Conceder acceso al almacén SQL

Braze necesita permiso para ejecutar consultas en tu almacén SQL, pero no necesita acceso de administrador del espacio de trabajo.

  1. En la barra lateral, selecciona SQL Warehouses y, a continuación, selecciona el almacén que quieres que utilice Braze.
  2. Selecciona Permissions.
  3. Busca y selecciona la entidad de servicio que creaste.
  4. En el desplegable de permisos, selecciona Can use y, a continuación, selecciona Add.

Conceder acceso a las tablas de origen

Concede a la entidad de servicio acceso de lectura al catálogo, el esquema y las tablas que configuraste en el Paso 1. Utiliza el ID de aplicación de la entidad de servicio (el mismo valor que el ID de cliente) como beneficiario.

GRANT USE CATALOG ON CATALOG `BRAZE-CLOUD-PRODUCTION` TO `APPLICATION_ID`;
GRANT USE SCHEMA ON SCHEMA `BRAZE-CLOUD-PRODUCTION`.INGESTION TO `APPLICATION_ID`;
GRANT SELECT ON TABLE `BRAZE-CLOUD-PRODUCTION`.INGESTION.USERS_ATTRIBUTES_SYNC TO `APPLICATION_ID`;

Sustituye APPLICATION_ID por el ID de aplicación de tu entidad de servicio. Actualiza los demás nombres según sea necesario, pero los permisos deben coincidir con el ejemplo anterior.

Actualizar el secreto de cliente

Braze almacena un secreto de cliente por credencial. Cuando lo actualizas, todos los orígenes y sincronizaciones que utilizan la credencial pasan a usar el nuevo secreto. Para sustituir el secreto:

  1. En Databricks, genera un nuevo secreto para la entidad de servicio siguiendo los pasos de Generar un secreto de cliente. Conserva el secreto antiguo hasta el paso 6.
  2. En el panel de Braze, ve a Configuración de datos > Ingesta de datos en la nube > Credenciales y, a continuación, selecciona tu credencial OAuth M2M. La sección Utilizado por enumera todos los orígenes y sincronizaciones que utilizan esta credencial.
  3. Pausa las sincronizaciones que utilizan esta credencial, o planifica la actualización para un momento en el que ninguna de ellas esté programada para ejecutarse. Así evitas que se inicie una sincronización mientras actualizas la credencial.
  4. Selecciona Editar credencial, introduce el nuevo secreto de cliente y, a continuación, selecciona Guardar. El cambio se aplica a todos los orígenes y sincronizaciones que utilizan esta credencial.
  5. Reanuda las sincronizaciones que hayas pausado.
  6. Después de que Braze guarde el nuevo secreto, elimina el secreto antiguo en Databricks.

Personal access token

Braze se autentica con un token de acceso personal generado en tu espacio de trabajo de Databricks. Las credenciales de token de acceso personal existentes siguen funcionando y no necesitas migrarlas. Sin embargo, los tokens de acceso personal suelen caducar según un calendario establecido por el administrador de tu espacio de trabajo, y las sincronizaciones se detienen cuando el token caduca. Para migrar una fuente existente a OAuth M2M, crea una credencial de OAuth M2M y selecciónala al editar la fuente.

Para crear un token de acceso personal:

  1. En tu espacio de trabajo de Databricks, selecciona tu nombre de usuario de Databricks en la barra superior y, a continuación, selecciona User Settings en el menú desplegable.
  2. En la pestaña Access tokens, selecciona Generate new token.
  3. Introduce un comentario que te ayude a identificar este token, como “Braze CDI”, y deja vacío el cuadro Lifetime (days) para que el token no caduque.
  4. Selecciona Generate.
  5. Copia el token que aparece y, a continuación, selecciona Done.

Guarda el token en un lugar seguro hasta que tengas que introducirlo en el panel de Braze durante el paso de creación de la credencial.

Paso 3: Permite el acceso a las IP de Braze

Si tienes políticas de red, debes conceder a Braze acceso de red a tu instancia de Databricks. 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.191
  • 34.206.23.173
  • 50.16.249.9
  • 52.4.160.214
  • 54.87.8.34
  • 54.156.35.251
  • 52.54.89.238
  • 18.205.178.15

Para la instancia US-08, estas son las direcciones IP correspondientes:

  • 52.151.246.51
  • 52.170.163.182
  • 40.76.166.157
  • 40.76.166.170
  • 40.76.166.167
  • 40.76.166.161
  • 40.76.166.156
  • 40.76.166.166
  • 40.76.166.160
  • 40.88.51.74
  • 52.154.67.17
  • 40.76.166.80
  • 40.76.166.84
  • 40.76.166.85
  • 40.76.166.81
  • 40.76.166.71
  • 40.76.166.144
  • 40.76.166.145

Para la instancia US-10, estas son las direcciones IP correspondientes:

  • 100.25.232.164
  • 35.168.86.179
  • 52.7.44.117
  • 3.92.153.18
  • 35.172.3.129
  • 50.19.162.19

Para las instancias EU-01 y EU-02, estas son las direcciones IP correspondientes:

  • 52.58.142.242
  • 52.29.193.121
  • 35.158.29.228
  • 18.157.135.97
  • 3.123.166.46
  • 3.64.27.36
  • 3.65.88.25
  • 3.68.144.188
  • 3.70.107.88

Para la instancia AU-01, estas son las direcciones IP correspondientes:

  • 13.210.1.145
  • 13.211.70.159
  • 13.238.45.54
  • 52.65.73.167
  • 54.153.242.239
  • 54.206.45.213

Para la instancia ID-01, estas son las direcciones IP correspondientes:

  • 108.136.157.246
  • 108.137.30.207
  • 16.78.128.71
  • 16.78.14.134
  • 16.78.162.208
  • 43.218.73.35

Para la instancia JP-01, estas son las direcciones IP correspondientes:

  • 13.159.155.212
  • 54.199.221.241
  • 13.192.23.16
  • 54.250.120.139
  • 18.181.114.232
  • 3.114.38.100

Para la instancia KR-01, estas son las direcciones IP correspondientes:

  • 43.200.215.4
  • 52.79.67.175
  • 52.79.113.60
  • 3.34.212.92
  • 54.116.134.231
  • 3.37.197.225

Paso 4: 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 Databricks.

Paso 4.1: Añade la información de conexión de Databricks y la tabla de origen

Introduce un nombre para tu origen y, a continuación, introduce tus credenciales y la configuración de Databricks:

  • En Nombre de la credencial, introduce una etiqueta que te ayude a identificar estas credenciales en Braze.
  • En Método de autenticación, selecciona el método que configuraste en el Paso 2 e introduce sus credenciales. Para OAuth M2M, introduce Client ID and Client secret. Para Personal access token, introduce Access token.

Después, continúa con el siguiente paso.

Paso 4.2: Prueba la conexión y conéctate al origen

A continuación, selecciona Probar conexión. Si la prueba se completa correctamente, termina de configurar los ajustes restantes y haz clic en Conectar al origen. Si la conexión falla, aparecerá un mensaje de error que te ayudará a solucionar el problema.

Paso 5: Crea 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. Luego, selecciona un modo de sincronización y define tus datos. Después, selecciona Vista previa y validación.

Cuando la validación se complete 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.

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.

Ejecutar la sincronización

Una vez activada, tu sincronización se ejecuta según la programación que configuraste 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 habitualmente. 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 Databricks.

Si reutilizas el mismo usuario en varias integraciones, no podrás eliminarlo en el panel de Braze hasta que se haya quitado de todas las sincronizaciones activas.

Usar Databricks como fuente conectada

Una fuente conectada es una alternativa sin copia a la sincronización de datos en Braze. Braze consulta directamente tu instancia de Databricks para crear segmentos CDI sin copiar los datos subyacentes. Para conocer los conceptos, las limitaciones y las implicaciones de costos, consulta Fuentes conectadas.

Paso 1: Configurar la autenticación y conceder permisos

Configura las credenciales para Braze con uno de los métodos de Paso 2: Configurar la autenticación. Sea cual sea el método que elijas, Braze usa estas credenciales para generar la lista de tablas disponibles en tus extensiones de segmento CDI y para consultar las tablas de origen y crear nuevos segmentos. Después de crear la fuente conectada, Braze detecta los nombres y las descripciones de todas las tablas disponibles para el usuario en el esquema de origen.

Puedes conceder acceso a todas las tablas de un esquema o conceder privilegios solo a tablas específicas. Todas las tablas a las que tenga acceso el rol de Braze estarán disponibles para consultar 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 segmento en Braze. Braze crea una tabla temporal por segmento, que solo persiste mientras Braze actualiza el segmento.

  • OAuth M2M: Concede a la entidad de servicio acceso al esquema usado para la fuente conectada, incluido CREATE TABLE. Usa el ID de aplicación de la entidad de servicio (el mismo valor que el ID de cliente) como beneficiario.

      GRANT USE CATALOG ON CATALOG `BRAZE-CLOUD-PRODUCTION` TO `APPLICATION_ID`;
      GRANT USE SCHEMA, CREATE TABLE ON SCHEMA `BRAZE-CLOUD-PRODUCTION`.INGESTION TO `APPLICATION_ID`;
      GRANT SELECT ON SCHEMA `BRAZE-CLOUD-PRODUCTION`.INGESTION TO `APPLICATION_ID`;
    

    Sustituye APPLICATION_ID por el ID de aplicación de tu entidad de servicio.

  • Token de acceso personal: Asegúrate de que la cuenta de servicio tenga privilegios CREATE TABLE en el esquema usado para la fuente conectada.

La configuración del acceso a la red es la misma que en el Paso 3.

Paso 2: Crear la fuente conectada en Braze

Ve a Configuración de datos > Ingesta de datos en la nube > Fuentes conectadas, selecciona Añadir fuente de datos y, a continuación, selecciona Databricks.

En Configurar fuente, introduce lo siguiente:

  • Credenciales: Nombre de la credencial, Método de autenticación, Nombre de host, Ruta HTTP y los campos de tu método de autenticación. Para OAuth M2M, introduce Client ID and Client secret. Para Personal access token, introduce Access token.
  • Configuración: Catálogo y Esquema

Elige un nombre para la fuente conectada. Este nombre se usa en la lista de fuentes disponibles cuando creas una nueva extensión de segmento CDI.

Configura un tiempo de ejecución máximo para esta fuente. Braze cancela automáticamente cualquier consulta que supere el tiempo de ejecución máximo. El tiempo de ejecución máximo permitido es de 60 minutos; un tiempo de ejecución menor reduce los costos generados en tu cuenta de Databricks. 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 extensiones de segmento CDI.

Puedes configurar varias fuentes conectadas con Braze, pero cada fuente debe configurarse para conectarse a un esquema diferente. Al crear fuentes adicionales, puedes reutilizar las credenciales existentes si te conectas a la misma cuenta de Databricks.

Formatear una carga útil a partir de columnas existentes

Si prefieres almacenar cada atributo en su propia columna internamente, tienes que convertir esas columnas en una cadena JSON para completar la sincronización con Braze. Usa esta consulta en Databricks para formatear las columnas de origen en 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,
        attribute_2,
        attribute_3
      )
    ) as PAYLOAD
  FROM BRAZE.EXAMPLE_USER_DATA;

Para obtener más orientación sobre optimización, consulta Prácticas recomendadas de la ingesta de datos en la nube.

Solución de problemas

La prueba de conexión es lenta

La prueba de conexión se ejecuta en tu almacén de datos, así que aumentar la capacidad del almacén puede mejorar su velocidad. En Databricks, puede haber un tiempo de calentamiento de dos a cinco minutos cuando Braze se conecta a instancias SQL Classic y Pro. Esto provoca retrasos durante la configuración y la prueba de la conexión, así como al inicio de las sincronizaciones programadas. Usar una instancia SQL sin servidor minimiza el tiempo de calentamiento y mejora el rendimiento de las consultas, pero puede suponer costos de integración ligeramente más altos.

El comando falló porque el almacén estaba detenido

Si recibes este error, asegúrate de que el almacén de Databricks esté en ejecución.

Service: Amazon S3; Status Code: 403; Error Code: 403 Forbidden

Si recibes este error, consulta Databricks: Error de acceso prohibido al acceder a datos de S3.

Dónde ejecutar comprobaciones SQL

Ejecuta las comprobaciones de validación directamente en el editor SQL de Databricks, en un almacén SQL, sobre la misma tabla o vista que usa tu integración de CDI. Para más información, consulta Editor SQL de Databricks.

New Stuff!