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, é necessário criar um novo catálogo ou escolher um catálogo existente para usar na integração. Há algumas maneiras de criar um novo catálogo, e qualquer uma delas funciona para a integração de CDI:

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

Qualquer alteração no esquema do catálogo (por exemplo, adicionar novos campos ou mudar o tipo de um campo) deve ser feita pelo dashboard do catálogo antes que os dados atualizados sejam sincronizados pela CDI. Recomendamos fazer essas atualizações quando a sincronização estiver pausada ou sem execução agendada. Assim, você evita conflitos entre os dados do seu data warehouse e o esquema na Braze.

Etapa 2: Integre a ingestão de dados na nuvem 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 de dados de usuários.

• 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 visualização ou uma visualização 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 função, um warehouse e um usuário e conceda as permissões adequadas. Se você já tiver credenciais de uma sincronização existente, poderá reutilizá-las, mas não se esqueça 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;
   
   

   A instrução CREATE USER neste exemplo é para autenticação por par de chaves RSA. Para a federação de identidade de carga de trabalho (Workload Identity Federation), crie a função e o warehouse conforme mostrado e crie o usuário de serviço a partir do formulário de credenciais do Snowflake. As concessões de função, warehouse e banco de dados continuam as mesmas. Se sua conta usar uma política de rede, a lista de permissões da próxima etapa ainda se aplica. Para ver a instrução e onde executá-la, consulte Configurar o Snowflake para a federação de identidade de carga de trabalho.

3. Se 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 ver a lista de IPs, consulte Ingestão de dados na nuvem.
4. No dashboard da Braze, acesse Parceiros de tecnologia > Snowflake e crie uma nova sincronização.
5. Insira os detalhes da 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 “Catálogos” e insira o nome da integração e o cronograma. 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. Para um par de chaves RSA, adicione a chave pública exibida no dashboard ao usuário que você criou para a Braze se conectar ao Snowflake. Para concluir esta etapa, você precisa de alguém com acesso SECURITYADMIN ou superior no Snowflake. Para a federação de identidade de carga de trabalho, você já executou a instrução do formulário de credenciais.
9. Selecione Testar conexão para confirmar que tudo funciona como esperado.
10. Salve a sincronização e use os dados de catálogo sincronizados em 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 visualização ou uma visualização 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á tiver credenciais de uma sincronização existente, poderá reutilizá-las, mas não se esqueça 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, precisará conceder à Braze acesso de rede à sua instância do Redshift. Permita o acesso a partir dos IPs correspondentes à região do seu dashboard da Braze. Para ver a lista de IPs, consulte Ingestão de dados na nuvem.

1. Opcionalmente, configure um novo projeto ou conjunto de dados 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á tiver credenciais de uma sincronização existente, poderá reutilizá-las—mas não se esqueça 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: dá à Braze acesso para executar consultas, ler metadados do conjunto de dados e listar tabelas.
   • BigQuery Data Viewer: dá à Braze acesso para visualizar conjuntos de dados e seu conteúdo.
   • BigQuery Job User: dá à Braze acesso para executar jobs
     
     Depois de criar a conta de serviço e conceder as permissões, configure como a Braze se autentica como a conta de serviço. Use a federação de identidade de carga de trabalho, para não precisar criar uma chave, ou gere uma chave JSON. Para saber mais sobre chaves JSON, consulte Criar e excluir chaves. Se você gerar uma chave JSON, vai fazer o upload dela no dashboard da Braze mais tarde.

3. Se você tiver políticas de rede em vigor, precisará conceder à Braze acesso de rede à sua instância do BigQuery. Para ver a lista de IPs, consulte Ingestão de dados na nuvem.

1. Configure uma tabela de origem no Databricks. Você pode usar os nomes do exemplo a seguir ou escolher seus nomes de catálogo, esquema e tabela. Também é possível usar uma visualização ou uma visualização 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 ou MAP	REQUIRED
ID	STRING	REQUIRED
DELETED	BOOLEAN	NULLABLE

2. Crie credenciais para a Braze. A Braze recomenda OAuth máquina a máquina (M2M) com uma entidade de serviço, mas você também pode usar um token de acesso pessoal. Se você já tiver credenciais de uma sincronização existente, poderá reutilizá-las, mas não se esqueça de estender o acesso à tabela de origem do catálogo.

OAuth M2M: Crie uma entidade de serviço, gere um segredo do cliente, conceda à entidade de serviço a permissão Can use no seu SQL warehouse e conceda a ela SELECT na tabela de origem do catálogo. Para ver as etapas, consulte Criar credenciais para a Braze.

Token de acesso pessoal:

• 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 a vida útil do token para sem vida útil, deixando a caixa Lifetime (days) em branco. Selecione Generate.
• e. Copie o token exibido e selecione Done.
• f. Guarde o token em um local seguro até precisar inseri-lo durante a etapa de criação de credenciais no dashboard da Braze.

3. Se você tiver políticas de rede em vigor, precisará conceder à Braze acesso de rede à sua instância do Databricks. Para ver a lista de IPs, consulte a página Ingestão de dados na nuvem.

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 uma entidade de serviço e conceda as permissões adequadas. Se você já tiver credenciais de uma sincronização existente, poderá reutilizá-las—só não se esqueça de estender o acesso à tabela de origem do catálogo. Para saber mais sobre como criar uma nova entidade de serviço e credenciais, consulte a página Ingestão de dados na nuvem.

3. Se você tiver políticas de rede em vigor, precisará conceder à Braze acesso de rede à sua instância do Microsoft Fabric. Para ver a lista de IPs, consulte Ingestão de dados na nuvem.

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 de catálogo a ser criado ou atualizado.
PAYLOAD	Sim	Uma string JSON com os campos a serem sincronizados com o item de catálogo na Braze.
DELETED	Opcional	Quando definido como true, o item de catálogo correspondente é removido do catálogo.
UPDATED_AT	Sem suporte	O armazenamento de arquivos não oferece suporte a colunas UPDATED_AT.

Nota

Os nomes de arquivo devem seguir as regras da AWS e ser exclusivos. Acrescente carimbos de data/hora para ajudar a garantir a exclusividade.

A configuração completa do S3 exige um bucket S3, uma fila do Amazon SQS e uma função e política do AWS IAM. A Braze processa apenas os arquivos enviados depois da criação da sincronização, então faça novamente o upload dos arquivos existentes que você quer ingerir.

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

• Configurar a ingestão de dados na nuvem na AWS
• Configurar a ingestão de dados na nuvem na Braze
• Solução de problemas

Para problemas comuns de notificação e permissão no lado da AWS, consulte Conceder permissões para publicar mensagens de notificação de eventos em um destino.

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

• catálogos json
• catálogos csv com exclusão
• catálogos csv sem exclusão

{"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 ver mais exemplos de arquivos, consulte Integrações de armazenamento de arquivos.

Como funciona a integração

Nota

As visualizações de sincronização desta seção se aplicam apenas a integrações de data warehouse. No armazenamento de arquivos no S3, a Braze processa novos arquivos à medida que eles são enviados para o seu bucket. Para saber mais, consulte Integrações de armazenamento de arquivos.

Sempre que a sincronização é executada, a Braze extrai todas as linhas em que UPDATED_AT é posterior ao último valor sincronizado. As linhas com o timestamp exato do limite podem ser sincronizadas novamente se novas linhas tiverem esse mesmo timestamp. Recomendamos criar uma visualização no seu data warehouse a partir dos dados do catálogo. Assim, você configura uma tabela de origem que será totalmente atualizada sempre que uma sincronização for executada. Com as visualizações, você não precisa reescrever a consulta todas as vezes.

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

• 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 da 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 seu 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.