Ir al contenido

Esta página fue traducida automáticamente y puede contener errores. Para informar de un error de traducción, usa el componente de comentarios situado bajo el sumario, a la derecha de la página.

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 Cloud Data Ingestion (CDI) para catálogos, debes crear un nuevo catálogo o identificar un catálogo existente que quieras utilizar para la integración. Hay varias formas de crear un nuevo catálogo, y cualquiera de ellas funcionará para la integración de CDI:

Sube un CSV
Crea un catálogo en el panel de Braze o durante la configuración de CDI.
Crea 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 hacerse a través del panel de catálogos antes de sincronizar los datos actualizados mediante CDI. Te recomendamos hacer estas actualizaciones cuando la sincronización esté en pausa o no esté programada para ejecutarse, para evitar conflictos entre los datos de tu almacén de datos y el esquema en Braze.

Paso 2: Integra la ingesta de datos en la nube con los datos del catálogo

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

Configura una tabla de origen en Snowflake. Puedes usar 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.

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

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.

 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;

La instrucción CREATE USER de este ejemplo es para la autenticación con par de claves RSA. Para Workload Identity Federation, crea el rol y el almacén como se muestra, y crea el usuario de servicio desde el formulario de credenciales de Snowflake. Los permisos del rol, el almacén y la base de datos siguen siendo los mismos. Si tu cuenta usa una política de red, la lista de direcciones IP permitidas del siguiente paso sigue aplicándose. Para ver la instrucción y dónde ejecutarla, consulta Configurar Snowflake para Workload Identity Federation.

Si tu cuenta de Snowflake tiene políticas de red, incluye en la lista de permitidos las IP de Braze para que el servicio CDI pueda conectarse. Para ver una lista de IP, consulta Ingesta de datos en la nube.
En el panel de Braze, ve a Partners tecnológicos > Snowflake y crea una nueva sincronización.
Introduce los datos de conexión (o reutiliza credenciales existentes) y la tabla de origen.
Continúa con el paso 2 del flujo de configuración, selecciona el tipo de sincronización “Catálogos” e introduce el nombre y la programación de la integración. Ten en cuenta que el nombre de la integración debe coincidir exactamente con el nombre del catálogo que creaste anteriormente.
Elige una frecuencia de sincronización y continúa con el siguiente paso.
Para un par de claves RSA, añade la clave pública que aparece en el panel al usuario que creaste para que Braze se conecte a Snowflake. Para completar este paso, necesitas a alguien con acceso SECURITYADMIN o superior en Snowflake. Para Workload Identity Federation, ya ejecutaste la instrucción desde el formulario de credenciales.
Selecciona Probar conexión para comprobar que todo funciona como se espera.
Guarda la sincronización y usa los datos del catálogo sincronizados para todos tus casos de uso de personalización.

Configura una tabla de origen en Redshift. Puedes usar 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.

 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
 )

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.

 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;

Si tienes un firewall u otras políticas de red, debes dar 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 ver una lista de IP, consulta Ingesta de datos en la nube.

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

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

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

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

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 permisos de la siguiente sección:
- 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
  
  Después de crear la cuenta de servicio y conceder los permisos, configura cómo se autentica Braze como la cuenta de servicio. Usa Workload Identity Federation, para no tener que crear una clave, o genera una clave JSON. Para obtener más información sobre las claves JSON, consulta Crear y eliminar claves. Si generas una clave JSON, la subirás al panel de Braze más adelante.

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

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

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

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

Crea credenciales para Braze. Braze recomienda OAuth de máquina a máquina (M2M) con una entidad de servicio, pero también puedes usar 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 una entidad de servicio, genera un secreto de cliente, concede a la entidad de servicio el permiso Can use en tu almacén SQL y concédele SELECT en la tabla de origen del catálogo. Para ver los pasos, consulta Crear credenciales para Braze.

Token de acceso personal:

a. Selecciona tu nombre de usuario de Databricks y, a continuación, 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 duración del token a sin duración dejando en blanco el cuadro Lifetime (days). Selecciona Generate.
e. Copia el token que aparece y, a continuación, 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.

Si tienes políticas de red, debes dar a Braze acceso de red a tu instancia de Databricks. Para ver 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:

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

Configura una entidad de servicio 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 saber más sobre cómo crear una nueva entidad de servicio y credenciales, consulta la página Ingesta de datos en la nube.

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

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

Campo	¿Obligatorio?	Descripción
`ID`	Sí	El ID del elemento del catálogo que se va a crear o actualizar.
`PAYLOAD`	Sí	Una cadena JSON con los campos que se sincronizarán con el elemento del catálogo en Braze.
`DELETED`	Opcional	Cuando se establece en `true`, el elemento del 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 que sean únicos.

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 crear la sincronización, así que vuelve a subir los archivos existentes que quieras ingerir.

Para ver el flujo completo de configuración de S3, consulta Integraciones de almacenamiento de archivos, especialmente:

Para problemas habituales de notificaciones y permisos en AWS, consulta Conceder permisos para publicar mensajes de notificación de eventos en un destino.

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

{"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; de lo contrario, se omite el archivo.

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

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 solo se aplican a las integraciones de almacén de datos. Para el almacenamiento de archivos en S3, Braze procesa los nuevos archivos 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 sea posterior al último valor sincronizado. Las filas que coincidan exactamente con la marca de tiempo límite pueden volver a sincronizarse si hay filas nuevas que comparten esa misma marca de tiempo. Te recomendamos que crees 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 por completo cada vez que se ejecute una sincronización. Con las vistas, no tendrás que volver a escribir la consulta cada vez.

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 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";

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";

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

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

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 artículos en el catálogo de destino en función del id proporcionado.
Si DELETED se establece en true, se eliminará el artículo del catálogo correspondiente.
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, así que no tienes que preocuparte por sincronizar solo los datos modificados.

New Stuff!