Sincronizar e excluir dados do catálogo

Esta página aborda como sincronizar dados do catálogo.

Etapa 1: Criar um novo catálogo

Antes de criar uma nova integração de Cloud Data Ingestion (CDI) para catálogos, você precisa criar um novo catálogo ou identificar um catálogo existente que deseja usar para a integração. Existem algumas maneiras de criar um novo catálogo, e qualquer uma delas funciona para a integração CDI:

• Fazer upload de um CSV
• Criar um catálogo no dashboard da Braze ou durante a configuração do CDI.
• Criar um catálogo usando o endpoint Criar catálogo

Quaisquer alterações no esquema do catálogo (por exemplo, adicionar novos campos ou alterar o tipo de campo) devem ser feitas pelo dashboard de catálogos antes que os dados atualizados sejam sincronizados pelo CDI. Recomendamos fazer essas atualizações quando a sincronização estiver pausada ou não estiver programada para execução, a fim de evitar conflitos entre os dados do seu data warehouse e o esquema na Braze.

Etapa 2: Integrar o Cloud Data Ingestion com dados de catálogo

A configuração de uma sincronização de catálogo segue de perto o processo das integrações de CDI para dados de usuário.

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

1. Configure uma tabela de origem no Snowflake. Você pode usar os nomes do exemplo a seguir ou escolher seus próprios nomes de banco de dados, esquema e tabela. Também é possível usar uma view ou uma view materializada em vez de uma tabela.

   
   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. Configure uma role, um warehouse e um usuário, e conceda as permissões adequadas. Se você já possui credenciais de uma sincronização existente, pode reutilizá-las, mas certifique-se de estender o acesso à tabela de origem do 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. Se a sua conta do Snowflake tiver políticas de rede, adicione os IPs da Braze à lista de permissões para que o serviço de CDI possa se conectar. Para uma lista de IPs, consulte Cloud Data Ingestion.
4. No dashboard da Braze, navegue até Parceiros de Tecnologia > Snowflake e crie uma nova sincronização.
5. Insira os detalhes de conexão (ou reutilize credenciais existentes) e a tabela de origem.
6. Prossiga para a etapa 2 do fluxo de configuração, selecione o tipo de sincronização “Catalogs” e insira o nome da integração e o cronograma. Observe que o nome da integração deve corresponder exatamente ao nome do catálogo que você criou anteriormente.
7. Escolha uma frequência de sincronização e prossiga para a próxima etapa.
8. Adicione a chave pública exibida no dashboard ao usuário que você criou para a Braze se conectar ao Snowflake. Para concluir essa etapa, você precisará de alguém com acesso SECURITYADMIN ou superior no Snowflake.
9. Selecione Test Connection para verificar se tudo funciona conforme esperado.
10. Salve a sincronização e use os dados sincronizados do catálogo para todos os seus casos de uso de personalização.

1. Configure uma tabela de origem no Redshift. Você pode usar os nomes do exemplo a seguir ou escolher seus próprios nomes de banco de dados, esquema e tabela. Também é possível usar uma view ou uma view materializada em vez de uma tabela.

   
   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. Configure um usuário e conceda as permissões adequadas. Se você já possui credenciais de uma sincronização existente, pode reutilizá-las, mas certifique-se de estender o acesso à tabela de origem do 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. Se você tiver um firewall ou outras políticas de rede, é necessário conceder acesso de rede à Braze para a sua instância do Redshift. Permita o acesso dos seguintes IPs correspondentes à região do seu dashboard da Braze. Para uma lista de IPs, consulte Cloud Data Ingestion.

1. Opcionalmente, configure um novo projeto ou dataset para armazenar sua tabela de origem.

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Crie uma ou mais tabelas para usar na sua integração de CDI com os seguintes 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
);

NOME DO CAMPO	TIPO	MODO
UPDATED_AT	TIMESTAMP	REQUIRED
PAYLOAD	JSON	REQUIRED
ID	STRING	REQUIRED
DELETED	BOOLEAN	OPTIONAL

2. Configure um usuário e conceda as permissões adequadas. Se você já possui credenciais de uma sincronização existente, pode reutilizá-las—mas certifique-se de estender o acesso à tabela de origem do catálogo. A conta de serviço deve ter as seguintes permissões:
   • BigQuery Connection User: permite que a Braze faça conexões.
   • BigQuery User: fornece à Braze acesso para executar consultas, ler metadados de datasets e listar tabelas.
   • BigQuery Data Viewer: fornece à Braze acesso para visualizar datasets e seus conteúdos.
   • BigQuery Job User: fornece à Braze acesso para executar jobs.
     
     Após criar a conta de serviço e conceder as permissões, gere uma chave JSON. Para saber mais, consulte Keys create and delete. Você fará o upload dessa chave no dashboard da Braze posteriormente.

3. Se você tiver políticas de rede em vigor, é necessário conceder acesso de rede à Braze para a sua instância do BigQuery. Para uma lista de IPs, consulte Cloud Data Ingestion.

1. Configure uma tabela de origem no Databricks. Você pode usar os nomes do exemplo a seguir ou escolher seus próprios nomes de catálogo, esquema e tabela. Também é possível usar uma view ou uma view materializada em vez de uma tabela.

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

NOME DO CAMPO	TIPO	MODO
UPDATED_AT	TIMESTAMP	REQUIRED
PAYLOAD	STRING, STRUCT, or MAP	REQUIRED
ID	STRING	REQUIRED
DELETED	BOOLEAN	NULLABLE

2. Crie um token de acesso pessoal no seu espaço de trabalho do Databricks.

• a. Selecione seu nome de usuário do Databricks e, em seguida, selecione User Settings no menu suspenso.
• b. Na guia Access tokens, selecione Generate new token.
• c. Insira um comentário que ajude a identificar esse token, como “Braze CDI”.
• d. Altere o tempo de vida do token para sem limite, deixando o campo Lifetime (days) em branco. Selecione Generate.
• e. Copie o token exibido e selecione Done.
• f. Guarde o token em um local seguro até que seja necessário inseri-lo na etapa de criação de credenciais no dashboard da Braze.

3. Se você tiver políticas de rede em vigor, é necessário conceder acesso de rede à Braze para a sua instância do Databricks. Para uma lista de IPs, consulte a página Cloud Data Ingestion.

Crie uma ou mais tabelas para usar na sua integração de CDI com os seguintes 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. Configure um service principal e conceda as permissões adequadas. Se você já possui credenciais de uma sincronização existente, pode reutilizá-las—mas certifique-se de estender o acesso à tabela de origem do catálogo. Para saber mais sobre como criar um novo service principal e credenciais, consulte a página Cloud Data Ingestion.

3. Se você tiver políticas de rede em vigor, é necessário conceder acesso de rede à Braze para a sua instância do Microsoft Fabric. Para uma lista de IPs, consulte Cloud Data Ingestion.

Crie arquivos de origem no S3 usando o formato JSON ou CSV. Cada arquivo deve incluir os seguintes campos:

Campo	Obrigatório?	Descrição
ID	Sim	O ID do item do catálogo a ser criado ou atualizado.
PAYLOAD	Sim	Uma string JSON dos campos a serem sincronizados com o item do catálogo na Braze.
DELETED	Opcional	Quando definido como true, o item do catálogo correspondente é removido do catálogo.
UPDATED_AT	Não suportado	O armazenamento de arquivos não suporta colunas UPDATED_AT.

Nota

Os nomes de arquivo devem seguir as regras da AWS e ser únicos. Adicione timestamps para ajudar a garantir a unicidade.

A configuração completa do S3 requer um bucket S3, uma fila Amazon SQS e uma role e política do AWS IAM. A Braze processa apenas arquivos enviados após a criação da sincronização. Portanto, faça o upload novamente dos arquivos existentes que deseja ingerir.

Para o fluxo completo de configuração do S3, consulte Integrações de armazenamento de arquivos, especialmente:

• Configurando o Cloud Data Ingestion na AWS
• Configurando o Cloud Data Ingestion na Braze
• Solução de problemas

Para problemas comuns de notificação e permissão do lado da AWS, consulte Granting permissions to publish event notification messages to a destination.

Os exemplos a seguir mostram formatos JSON e CSV válidos para sincronizar dados de catálogo a partir de armazenamento de arquivos.

• 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 linha do seu arquivo de origem deve conter JSON válido, caso contrário o arquivo será ignorado.

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 exemplos adicionais de arquivos, consulte Integrações de armazenamento de arquivos.

Como a integração funciona

Nota

As visualizações de sincronização nesta seção se aplicam apenas a integrações com data warehouse. Para armazenamento de arquivos S3, a Braze processa novos arquivos à medida que são carregados no seu bucket. Consulte Integrações de armazenamento de arquivos para mais detalhes.

Cada vez que a sincronização é executada, a Braze importa todas as linhas em que UPDATED_AT é posterior ao último valor sincronizado. Linhas no timestamp exato do limite podem ser sincronizadas novamente se novas linhas compartilharem o mesmo timestamp. Recomendamos criar uma view no seu data warehouse a partir dos dados do catálogo para configurar uma tabela de origem que será totalmente atualizada a cada execução de sincronização. Com views, você não precisará reescrever a consulta a cada vez.

Por exemplo, se você tiver uma tabela de dados de produtos (product_catalog_1) com product_id e três atributos adicionais, você poderá sincronizar a seguinte view:

• 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] ;

• Os dados obtidos pela integração serão usados para criar ou atualizar itens no catálogo de destino com base no id fornecido.
• Se DELETED estiver definido como true, o item correspondente do catálogo será excluído.
• A sincronização não registra pontos de dados, mas todos os dados sincronizados contam para o uso total do catálogo. Esse uso é medido com base no total de dados armazenados, então você não precisa se preocupar em sincronizar apenas os dados alterados.