Sincronizar y eliminar datos del catálogo

En esta página se explica cómo sincronizar los datos del catálogo.

Paso 1: Crear un nuevo catálogo

Antes de crear una nueva integración de ingesta de datos en la nube (CDI) para catálogos, necesitas crear un nuevo catálogo o identificar un catálogo existente que quieras utilizar para la integración. Existen varias formas de crear un nuevo catálogo y cualquiera de ellas funcionará para la integración CDI:

• Cargar un CSV
• Crear un catálogo en el panel de Braze o durante la configuración de CDI.
• Crear un catálogo utilizando el endpoint Crear catálogo

Cualquier cambio en el esquema del catálogo (por ejemplo, añadir nuevos campos o cambiar el tipo de campo) debe realizarse a través del panel de catálogos antes de que los datos actualizados se sincronicen mediante CDI. Recomendamos realizar estas actualizaciones cuando la sincronización esté pausada o no esté programada para ejecutarse, a fin de evitar conflictos entre los datos de tu almacén de datos y el esquema en Braze.

Paso 2: Integrar la ingesta de datos en la nube con datos de catálogo

La configuración de una sincronización de catálogo sigue de cerca el proceso de las integraciones de CDI con datos de usuario.

• snowflake
• redshift
• bigquery
• databricks
• microsoft fabric
• s3

1. Configura una tabla de origen en Snowflake. Puedes utilizar los nombres del siguiente ejemplo o elegir tus propios nombres de base de datos, esquema y tabla. También puedes usar una vista o una vista materializada en lugar de una tabla.

   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   
    CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
    CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
    CREATE OR REPLACE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC (
         UPDATED_AT TIMESTAMP_NTZ(9) NOT NULL DEFAULT SYSDATE(),
         --ID of the catalog item to be created or updated
         ID VARCHAR(16777216) NOT NULL,
         --Catalog fields and values that should be added or updated
         PAYLOAD VARCHAR(16777216) NOT NULL,
         --The catalog item associated with this ID should be deleted
         DELETED BOOLEAN
    );
   
   

2. Configura un rol, un almacén y un usuario, y concede los permisos adecuados. Si ya tienes credenciales de una sincronización existente, puedes reutilizarlas, pero asegúrate de ampliar el acceso a la tabla de origen del catálogo.

   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   
    CREATE ROLE BRAZE_INGESTION_ROLE;
   
    GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
    GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
    GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC TO ROLE BRAZE_INGESTION_ROLE;
   
    CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
    GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;
   
    CREATE USER BRAZE_INGESTION_USER;
    GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;
   
   

3. Si tu cuenta de Snowflake tiene políticas de red, incluye las IP de Braze en la lista de permitidos para que el servicio de CDI pueda conectarse. Para obtener una lista de IP, consulta Ingesta de datos en la nube.
4. En el panel de Braze, ve a Partners tecnológicos > Snowflake y crea una nueva sincronización.
5. Introduce los datos de conexión (o reutiliza las credenciales existentes) y la tabla de origen.
6. Continúa con el paso 2 del flujo de configuración, selecciona el tipo de sincronización “Catalogs” e introduce el nombre de la integración y la programación. Ten en cuenta que el nombre de la integración debe coincidir exactamente con el nombre del catálogo que creaste anteriormente.
7. Elige una frecuencia de sincronización y continúa con el siguiente paso.
8. Añade la clave pública que se muestra en el panel al usuario que creaste para que Braze se conecte a Snowflake. Para completar este paso, necesitarás a alguien con acceso SECURITYADMIN o superior en Snowflake.
9. Selecciona Probar conexión para verificar que todo funciona como se espera.
10. Guarda la sincronización y utiliza los datos de catálogo sincronizados para todos tus casos de uso de personalización.

1. Configura una tabla de origen en Redshift. Puedes utilizar los nombres del siguiente ejemplo o elegir tus propios nombres de base de datos, esquema y tabla. También puedes usar una vista o una vista materializada en lugar de una tabla.

   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   
    CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
    CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
    CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC (
       updated_at timestamptz default sysdate not null,
       --ID of the catalog item to be created or updated
       id varchar not null,
       --Catalog fields and values that should be added or updated
       payload varchar(max),
       --The catalog item associated with this ID should be deleted
       deleted boolean
    )
   
   

2. Configura un usuario y concede los permisos adecuados. Si ya tienes credenciales de una sincronización existente, puedes reutilizarlas, pero asegúrate de ampliar el acceso a la tabla de origen del catálogo.

   
   1
   2
   3
   
    CREATE USER braze_user PASSWORD '{password}';
    GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION to braze_user;
    GRANT SELECT ON TABLE CATALOGS_SYNC TO braze_user;
   
   

3. Si tienes un firewall u otras políticas de red, debes conceder a Braze acceso de red a tu instancia de Redshift. Permite el acceso desde las siguientes IP correspondientes a la región de tu panel de Braze. Para obtener una lista de IP, consulta Ingesta de datos en la nube.

1. Opcionalmente, configura un nuevo proyecto o conjunto de datos para alojar tu tabla de origen.

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Crea una o más tablas para usar en tu integración de CDI con los siguientes campos:

1
2
3
4
5
6
7

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

2. Configura un usuario y concede los permisos adecuados. Si ya tienes credenciales de una sincronización existente, puedes reutilizarlas, pero asegúrate de ampliar el acceso a la tabla de origen del catálogo. La cuenta de servicio debe tener los siguientes permisos:
   • BigQuery Connection User: permitirá a Braze establecer conexiones.
   • BigQuery User: proporcionará a Braze acceso para ejecutar consultas, leer metadatos de conjuntos de datos y listar tablas.
   • BigQuery Data Viewer: proporcionará a Braze acceso para ver conjuntos de datos y su contenido.
   • BigQuery Job User: proporcionará a Braze acceso para ejecutar trabajos.
     
     Después de crear la cuenta de servicio y conceder los permisos, genera una clave JSON. Consulta Keys create and delete para obtener más información. La actualizarás en el panel de Braze más adelante.

3. Si tienes políticas de red configuradas, debes conceder a Braze acceso de red a tu instancia de BigQuery. Para obtener una lista de IP, consulta Ingesta de datos en la nube.

1. Configura una tabla de origen en Databricks. Puedes utilizar los nombres del siguiente ejemplo o elegir tus propios nombres de catálogo, esquema y tabla. También puedes usar una vista o una vista materializada en lugar de una tabla.

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

1
2
3
4
5
6
7

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, or MAP	REQUIRED
ID	STRING	REQUIRED
DELETED	BOOLEAN	NULLABLE

2. Crea credenciales para Braze. Braze recomienda OAuth máquina a máquina (M2M) con un servicio principal, pero también puedes utilizar un token de acceso personal. Si ya tienes credenciales de una sincronización existente, puedes reutilizarlas, pero asegúrate de ampliar el acceso a la tabla de origen del catálogo.

OAuth M2M: Crea un servicio principal, genera un secreto de cliente, concede al servicio principal el permiso Can use en tu almacén SQL y concédele SELECT en la tabla de origen del catálogo. Para conocer los pasos, consulta Crear credenciales para Braze.

Token de acceso personal:

• a. Selecciona tu nombre de usuario de Databricks y luego selecciona User Settings en el menú desplegable.
• b. En la pestaña Access tokens, selecciona Generate new token.
• c. Introduce un comentario que te ayude a identificar este token, como “Braze CDI”.
• d. Cambia la vida útil del token a sin límite dejando el campo Lifetime (days) en blanco. Selecciona Generate.
• e. Copia el token que se muestra y luego selecciona Done.
• f. Guarda el token en un lugar seguro hasta que necesites introducirlo durante el paso de creación de credenciales en el panel de Braze.

3. Si tienes políticas de red configuradas, debes conceder a Braze acceso de red a tu instancia de Databricks. Para obtener una lista de IP, consulta la página Ingesta de datos en la nube.

Crea una o más tablas para usar en tu integración de CDI con los siguientes campos:

1
2
3
4
5
6
7
8

CREATE OR ALTER TABLE [warehouse].[schema].[CDI_table_name]
(
  UPDATED_AT DATETIME2(6) NOT NULL,
  PAYLOAD VARCHAR NOT NULL,
  ID VARCHAR NOT NULL,
  DELETED BIT
)
GO

2. Configura un servicio principal y concede los permisos adecuados. Si ya tienes credenciales de una sincronización existente, puedes reutilizarlas, solo asegúrate de ampliar el acceso a la tabla de origen del catálogo. Para obtener más información sobre cómo crear un nuevo servicio principal y credenciales, consulta la página Ingesta de datos en la nube.

3. Si tienes políticas de red configuradas, debes conceder a Braze acceso de red a tu instancia de Microsoft Fabric. Para obtener una lista de IP, consulta Ingesta de datos en la nube.

Crea archivos de origen en S3 utilizando formato JSON o CSV. Cada archivo debe incluir los siguientes campos:

Campo	¿Obligatorio?	Descripción
ID	Sí	El ID del elemento de catálogo que se va a crear o actualizar.
PAYLOAD	Sí	Una cadena JSON de los campos que se sincronizarán con el elemento de catálogo en Braze.
DELETED	Opcional	Cuando se establece en true, el elemento de catálogo correspondiente se elimina del catálogo.
UPDATED_AT	No compatible	El almacenamiento de archivos no admite columnas UPDATED_AT.

Nota

Los nombres de archivo deben seguir las reglas de AWS y ser únicos. Añade marcas de tiempo para ayudar a garantizar la unicidad.

La configuración completa de S3 requiere un contenedor de S3, una cola de Amazon SQS y un rol y una política de AWS IAM. Braze solo procesa los archivos subidos después de que se crea la sincronización, así que vuelve a subir los archivos existentes que quieras ingerir.

Para el flujo de configuración completo de S3, consulta Integraciones de almacenamiento de archivos, en particular:

• Configurar la ingesta de datos en la nube en AWS
• Configurar la ingesta de datos en la nube en Braze
• Solución de problemas

Para problemas comunes de notificaciones y permisos del lado de AWS, consulta Granting permissions to publish event notification messages to a destination.

Los siguientes ejemplos muestran formatos JSON y CSV válidos para sincronizar datos de catálogo desde almacenamiento de archivos.

• json catalogs
• csv catalogs with delete
• csv catalogs without delete

{"id":"85","payload":"{\"product_name\":\"Product 85\",\"price\":85.85}"}
{"id":"86","payload":"{\"product_name\":\"Product 86\",\"price\":86.86}"}
{"id":"1","payload":"{\"product_name\":\"Product 1\",\"price\":1.01}","deleted":true}

Importante

Cada línea de tu archivo de origen debe contener JSON válido o el archivo se omitirá.

1
2
3
4

ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
86,"{""product_name"": ""Product 86"", ""price"": 86.86}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

1
2
3

ID,PAYLOAD
85,"{""product_name"": ""Product 85"", ""price"": 85.85}"
86,"{""product_name"": ""Product 86"", ""price"": 86.86}"

Para ver más ejemplos de archivos, consulta Integraciones de almacenamiento de archivos.

Cómo funciona la integración

Nota

Las vistas de sincronización de esta sección se aplican solo a integraciones de almacén de datos. Para el almacenamiento de archivos en S3, Braze procesa los archivos nuevos a medida que se cargan en tu contenedor. Consulta Integraciones de almacenamiento de archivos para más detalles.

Cada vez que se ejecuta la sincronización, Braze extrae todas las filas en las que UPDATED_AT es posterior al último valor sincronizado. Las filas en la marca de tiempo exacta del límite pueden volver a sincronizarse si nuevas filas comparten esa misma marca de tiempo. Recomendamos crear una vista en tu almacén de datos a partir de los datos de tu catálogo para configurar una tabla de origen que se actualice completamente cada vez que se ejecute una sincronización. Con las vistas, no necesitarás reescribir la consulta cada vez.

Por ejemplo, si tienes una tabla de datos de producto (product_catalog_1) con product_id y tres atributos adicionales, podrías sincronizar la siguiente vista:

• snowflake
• redshift
• bigquery
• databricks
• microsoft fabric

1
2
3
4
5
6
7
8
9
10
11
12
13

CREATE VIEW BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS
SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    product_id as id,
    TO_JSON(
        OBJECT_CONSTRUCT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'attribute_3',
            attribute_3)
    )as PAYLOAD FROM "product_catalog_1";

1
2
3
4
5
6
7
8
9
10
11
12
13

CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS
SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    Product_id as id,
    JSON_SERIALIZE(
        OBJECT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'attribute_3',
            attribute_3)
    ) as PAYLOAD FROM "product_catalog_1";

1
2
3
4
5
6
7
8
9
10
11

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`);

1
2
3
4
5
6
7
8
9
10
11

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`);

1
2
3
4
5
6
7

CREATE VIEW [braze].[user_update_example]
AS SELECT
    id as ID,
    CURRENT_TIMESTAMP as UPDATED_AT,
    JSON_OBJECT('attribute_1':attribute_1, 'attribute_2':attribute_2, 'attribute_3':attribute_3, 'attribute_4':attribute_4) as PAYLOAD

FROM [braze].[product_catalog] ;

• Los datos obtenidos de la integración se utilizarán para crear o actualizar elementos en el catálogo de destino en función del id proporcionado.
• Si DELETED se establece en true, el elemento de catálogo correspondiente se eliminará.
• La sincronización no registrará puntos de datos, pero todos los datos sincronizados contarán para el uso total de tu catálogo; este uso se mide en función del total de datos almacenados, por lo que no necesitas preocuparte por sincronizar solo los datos modificados.