Ingestão de dados na nuvem para Databricks

Esta página reúne tudo o que você precisa para sincronizar dados do Databricks com a Braze usando a Ingestão de dados na nuvem (CDI). Você vai ver quais recursos criar no Databricks e como conectar a fonte e criar uma sincronização na Braze. Também vai encontrar a tabela de origem de cada tipo de dado e a solução de problemas específicos do Databricks.

Visão geral da configuração

1. Na sua conta do Databricks, configure as tabelas ou visualizações que você quer sincronizar com a Braze.
2. Crie credenciais para a Braze com um dos métodos de autenticação compatíveis e permita o acesso aos catálogos e esquemas do Databricks que contêm os dados que você quer sincronizar.
3. Crie uma nova fonte e uma sincronização no dashboard da Braze.
4. Valide a integração e inicie a sincronização.

Importante

Pode haver um tempo de aquecimento de dois a cinco minutos quando a Braze se conecta a instâncias SQL Classic e Pro. Isso pode causar atrasos na configuração e no teste da conexão, e também no início das sincronizações agendadas. Usar uma instância SQL serverless minimiza o tempo de aquecimento e melhora a taxa de transferência de consultas, mas pode gerar custos de integração um pouco maiores.

Etapa 1: Configure sua tabela de origem

As etapas desta seção criam uma tabela com uma coluna PAYLOAD. Se você planeja mapear colunas com Visual ou escrever uma consulta com SQL na etapa Definição de dados, pode usar uma tabela ou visualização existente. Nesse caso, pule a etapa de criação da tabela e conceda à Braze acesso de leitura às tabelas ou visualizações que você quer sincronizar. Para comparar as opções, consulte Escolha uma opção de definição de dados.

Você pode dar o nome que quiser ao esquema e à tabela, mas os nomes das colunas devem corresponder às definições das guias a seguir. Também é possível usar uma visualização ou uma visualização materializada em vez de uma tabela.

Se quiser, configure um novo catálogo ou esquema para armazenar sua tabela de origem:

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Nota

Se você usar uma coluna PAYLOAD, sua tabela ou visualização de origem pode incluir colunas que não aparecem nas guias a seguir (por exemplo, de auditoria ou hashing). A Braze lê apenas as colunas descritas nessas guias. As outras colunas não são usadas nas sincronizações da Ingestão de dados na nuvem.

Selecione a guia do tipo de dado que você quer sincronizar.

• atributos do usuário
• eventos personalizados
• eventos de compra
• itens de catálogo
• gatilhos do canvas
• exclusões de usuários

Atributos do usuário, eventos personalizados e eventos de compra usam o mesmo formato de tabela de origem. Só o conteúdo de PAYLOAD muda.

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

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

Nome do campo	Tipo	Modo
UPDATED_AT	TIMESTAMP	REQUIRED
PAYLOAD	STRING, STRUCT ou 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 - O horário em que esta linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. Linhas com o carimbo de data/hora exatamente no limite podem ser sincronizadas novamente se novas linhas tiverem esse mesmo carimbo de data/hora.
• Colunas de identificador de usuário - Sua tabela pode conter uma ou mais colunas de identificador de usuário. Cada linha deve conter apenas um identificador (external_id, a combinação de alias_name e alias_label, braze_id, email ou phone). Uma tabela de origem pode ter colunas para um, dois, três, quatro ou todos os cinco tipos de identificador.
  • EXTERNAL_ID - Identifica o usuário que você deseja atualizar. Deve corresponder ao valor de external_id usado na Braze.
  • ALIAS_NAME e ALIAS_LABEL - Essas duas colunas criam um objeto de alias de usuário. alias_name deve ser um identificador exclusivo, e alias_label especifica o tipo de alias. Os usuários podem ter vários aliases com rótulos diferentes, mas apenas um alias_name por alias_label.
  • BRAZE_ID - O identificador de usuário da Braze. Ele é gerado pelo SDK da Braze. Não é possível criar novos usuários usando um Braze ID por meio da ingestão de dados na nuvem. Para criar novos usuários, especifique um ID de usuário externo ou um alias de usuário.
  • EMAIL - O endereço de e-mail do usuário. Se existirem vários perfis com o mesmo endereço de e-mail, o perfil atualizado mais recentemente terá prioridade nas atualizações. Se você incluir tanto o e-mail quanto o telefone, o e-mail será usado como identificador principal.
  • PHONE - O número de telefone do usuário. Se existirem vários perfis com o mesmo número de telefone, o perfil atualizado mais recentemente terá prioridade nas atualizações.
• PAYLOAD - É uma string ou struct com os campos que você quer sincronizar com o usuário na Braze.

Nas sincronizações de atributos, PAYLOAD segue o formato do objeto de atributos do usuário. Você pode incluir atributos personalizados aninhados, arrays de objetos e status de grupos de inscrições. Para ver exemplos de carga útil, consulte Configuração da tabela.

Os eventos personalizados usam a mesma tabela de origem dos atributos do usuário. Crie a tabela mostrada na guia Atributos do usuário e preencha PAYLOAD com um objeto de eventos.

Para sincronizar eventos, é necessário informar o nome do evento. Formate o campo time como uma string ISO 8601 ou no formato yyyy-MM-dd'T'HH:mm:ss:SSSZ. Se o campo time não estiver presente, a Braze usa o valor da coluna UPDATED_AT como horário do evento. Os outros campos, incluindo app_id e properties, são opcionais.

Você pode sincronizar um evento por linha.

1
2
3
4
5
6
7
8
9

{
    "app_id" : "your-app-id",
    "name" : "rented_movie",
    "time" : "2013-07-16T19:20:45+01:00",
    "properties": {
        "movie": "The Sad Egg",
        "director": "Alex Smith"
    }
}

Os eventos de compra usam a mesma tabela de origem dos atributos do usuário. Crie a tabela mostrada na guia Atributos do usuário e preencha PAYLOAD com um objeto de compras.

Para sincronizar eventos de compra, é necessário informar product_id, currency e price. Formate o campo opcional time como uma string ISO 8601 ou no formato yyyy-MM-dd'T'HH:mm:ss:SSSZ. Se o campo time não estiver presente, a Braze usa o valor da coluna UPDATED_AT como horário do evento. Os outros campos, incluindo app_id, quantity e properties, são opcionais.

Você pode sincronizar um evento de compra por linha.

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

{
    "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 criar uma sincronização de catálogo, crie o catálogo de destino na Braze. Para ver o fluxo completo de catálogos, consulte Sincronizar e excluir dados de catálogo.

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

O nome da integração deve ser exatamente igual ao nome do catálogo que você criou na Braze.

A Braze recomenda criar uma visualização a partir dos dados do seu catálogo para que a tabela de origem seja totalmente atualizada a cada execução da sincronização. Por exemplo, se você tem uma tabela de dados de produtos (product_catalog_1) com product_id e três atributos adicionais, pode sincronizar a seguinte visualização:

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

Os gatilhos do Canvas viabilizam a personalização zero-copy. Para ver a configuração do Canvas de destino e as considerações, consulte Personalização zero-copy.

1
2
3
4
5
6
7
8
9
10

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

Nome do campo	Tipo	Obrigatório
UPDATED_AT	TIMESTAMP	Sim
PROPERTIES	STRING, STRUCT ou MAP	Sim
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE

As sincronizações de disparo de Canvas diferem de outras sincronizações de dados de usuários de três maneiras:

• Só há suporte para os identificadores ID externo ou alias de usuário. E-mail e números de telefone não são identificadores compatíveis.
• Só é possível sincronizar usuários que já existem na Braze. Não é possível criar novos usuários.
• PROPERTIES substitui a coluna PAYLOAD. Essa coluna é uma string JSON com os campos que você quer usar como propriedades de entrada no Canvas para personalização.

Sua tabela de disparos de Canvas precisa das seguintes colunas:

• UPDATED_AT - O momento em que essa linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. As linhas com o timestamp exatamente no limite podem ser sincronizadas novamente se novas linhas tiverem esse mesmo timestamp.
• EXTERNAL_ID ou ALIAS_NAME e ALIAS_LABEL como coluna de identificador de usuário. Essas colunas identificam os usuários para os quais você quer disparar o envio de mensagens do Canvas.
  • EXTERNAL_ID - Identifica o usuário que vai entrar no Canvas. Esse valor deve corresponder ao valor de external_id usado na Braze.
  • ALIAS_NAME e ALIAS_LABEL - Essas colunas criam um objeto de alias de usuário. alias_name deve ser um identificador único, e alias_label especifica o tipo de alias. Os usuários podem ter vários aliases com rótulos diferentes, mas apenas um alias_name por alias_label.
• PROPERTIES - Uma string JSON com os campos que ficarão disponíveis como propriedades de personalização no seu Canvas. Ela deve conter informações específicas do usuário.

Nota

As propriedades não são obrigatórias para todas as linhas ou usuários. No entanto, os valores das propriedades precisam ser uma string JSON válida. Insira uma string vazia {} se não houver propriedades para a linha.

Para começar, selecione o tipo de dado Gatilhos do Canvas ao criar uma nova sincronização.

As tabelas de origem para exclusões de usuários devem incluir um ou mais tipos de identificador de usuário e um carimbo de data/hora UPDATED_AT. Colunas de carga útil não são compatíveis com dados de exclusão de usuários.

• UPDATED_AT - O momento em que esta linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. As linhas que estiverem exatamente no carimbo de data/hora limite podem ser sincronizadas novamente se novas linhas tiverem esse mesmo carimbo de data/hora.
• Colunas de identificador de usuário - Cada linha deve conter apenas um identificador: external_id, a combinação de alias_name e alias_label, ou braze_id. Uma tabela de origem pode conter colunas para um, dois ou todos os três tipos de identificador.
  • EXTERNAL_ID - Identifica o usuário que você deseja atualizar. Deve corresponder ao valor de external_id usado na Braze.
  • ALIAS_NAME e ALIAS_LABEL - Essas duas colunas criam um objeto de alias de usuário. alias_name deve ser um identificador exclusivo, e alias_label especifica o tipo de alias. Os usuários podem ter vários aliases com rótulos diferentes, mas apenas um alias_name por alias_label.
  • BRAZE_ID - O identificador de usuário da Braze. Ele é gerado pelo SDK da Braze, e não é possível criar novos usuários usando um ID da Braze por meio da ingestão de dados na nuvem. Para criar novos usuários, especifique um ID de usuário externo ou um alias de usuário.

Importante

Não inclua uma coluna PAYLOAD na sua tabela para remoção de usuários. Para evitar a remoção acidental e permanente de usuários, a sincronização falha se uma coluna de carga útil for fornecida na tabela de origem. Quaisquer outras colunas são permitidas, mas são ignoradas pela Braze.

Crie uma tabela com os seguintes campos:

Nome do campo	Tipo	Modo
UPDATED_AT	TIMESTAMP	REQUIRED
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE
BRAZE_ID	STRING	NULLABLE

Na página Criar sincronização de importação, defina o Tipo de dados como Excluir usuários para que as ações corretas sejam executadas durante a execução da integração. Para saber mais, consulte Excluir usuários com a Ingestão de dados na nuvem.

Aviso

A exclusão de perfis de usuário não pode ser desfeita. A ação de exclusão remove os usuários permanentemente, o que pode gerar discrepâncias nos seus dados. Para mais detalhes, consulte Efeitos da exclusão de perfis de usuário.

Etapa 2: Configure a autenticação

A Braze pode se conectar ao Databricks com qualquer um dos seguintes métodos de autenticação:

OAuth M2M

A Braze se conecta ao seu espaço de trabalho do Databricks como uma entidade de serviço (service principal), usando a autenticação OAuth máquina a máquina (M2M). O Databricks recomenda o OAuth M2M para conexões sem supervisão, como a ingestão de dados na nuvem. Crie uma nova entidade de serviço para a Braze usar e conceda a ela acesso ao seu SQL warehouse e às tabelas de origem. A Braze precisa dos seguintes dados para se conectar:

• ID do cliente (também chamado de ID do aplicativo) da entidade de serviço
• Segredo do cliente para a Braze se autenticar

Criar a entidade de serviço

1. No seu espaço de trabalho do Databricks, selecione seu nome de usuário na barra superior e depois selecione Settings.
2. Acesse Identity and access e selecione Manage ao lado de Service principals.
3. Selecione Add service principal > Add new.
4. Digite um nome que ajude a identificar a entidade de serviço, como “Braze CDI”, e selecione Add.
5. Selecione a entidade de serviço que você criou. Na guia Configurations, confira se a opção Databricks SQL access está selecionada.

Gerar um segredo do cliente

1. Na página da entidade de serviço, selecione a guia Secrets e depois selecione Generate secret.
2. Informe a validade do segredo, em dias. O Databricks permite uma validade máxima de 730 dias.
3. Selecione Generate.
4. Copie os valores de Secret e Client ID e selecione Done.

Guarde o ID do cliente e o segredo em um lugar seguro até precisar inseri-los no dashboard da Braze, na etapa de criação da credencial. O Databricks mostra o segredo apenas uma vez.

Nota

O Databricks não permite validade ilimitada para segredos de entidades de serviço. Lembre-se de substituir o segredo antes que ele expire para manter o fluxo de dados para a Braze. Para ver as etapas, consulte Atualizar o segredo do cliente.

Conceder acesso ao SQL warehouse

A Braze precisa de permissão para executar consultas no seu SQL warehouse, mas não precisa de acesso de administrador do espaço de trabalho.

1. Na barra lateral, selecione SQL Warehouses e depois selecione o warehouse que você quer que a Braze use.
2. Selecione Permissions.
3. Pesquise e selecione a entidade de serviço que você criou.
4. No menu suspenso de permissões, selecione Can use e depois selecione Add.

Conceder acesso às tabelas de origem

Conceda à entidade de serviço acesso de leitura ao catálogo, ao schema e às tabelas que você configurou na Etapa 1. Use o ID do aplicativo da entidade de serviço (o mesmo valor do ID do cliente) como beneficiário da concessão.

1
2
3

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

Substitua APPLICATION_ID pelo ID do aplicativo da sua entidade de serviço. Atualize os outros nomes conforme necessário, mas as permissões devem corresponder ao exemplo anterior.

Atualizar o segredo do cliente

A Braze armazena um segredo do cliente por credencial. Quando você o atualiza, todas as fontes e sincronizações que usam a credencial passam a usar o novo segredo. Para substituir o segredo:

1. No Databricks, gere um novo segredo para a entidade de serviço seguindo as etapas em Gerar um segredo do cliente. Mantenha o segredo antigo até a etapa 6.
2. No dashboard da Braze, acesse Configurações de dados > Ingestão de dados na nuvem > Credenciais e selecione sua credencial OAuth M2M. A seção Usado por lista todas as fontes e sincronizações que usam essa credencial.
3. Pause as sincronizações que usam essa credencial ou planeje a atualização para um horário em que nenhuma delas esteja agendada para ser executada. Isso evita que uma sincronização comece enquanto você atualiza a credencial.
4. Selecione Editar credencial, insira o novo segredo do cliente e selecione Salvar. A alteração vale para todas as fontes e sincronizações que usam essa credencial.
5. Retome as sincronizações que você pausou.
6. Depois que a Braze salvar o novo segredo, exclua o segredo antigo no Databricks.

Personal access token

A Braze faz a autenticação com um token de acesso pessoal gerado no seu espaço de trabalho do Databricks. As credenciais de token de acesso pessoal existentes continuam funcionando, e você não precisa migrá-las. No entanto, os tokens de acesso pessoal costumam expirar de acordo com um cronograma definido pelo administrador do seu espaço de trabalho. Quando o token expira, as sincronizações param. Para migrar uma fonte existente para OAuth M2M, crie uma credencial OAuth M2M e selecione-a ao editar a fonte.

Para criar um token de acesso pessoal:

1. No seu espaço de trabalho do Databricks, selecione seu nome de usuário do Databricks na barra superior e, em seguida, selecione User Settings no menu suspenso.
2. Na guia Access tokens, selecione Generate new token.
3. Insira um comentário que ajude a identificar esse token, como “Braze CDI”. Para que o token não expire, deixe a caixa Lifetime (days) vazia.
4. Selecione Generate.
5. Copie o token exibido e, em seguida, selecione Done.

Guarde o token em um local seguro até precisar inseri-lo no dashboard da Braze durante a etapa de criação da credencial.

Etapa 3: Permita o acesso dos IPs da Braze

Se você tiver políticas de rede em vigor, precisa dar à Braze acesso de rede à sua instância do Databricks. Permita o acesso a partir dos IPs a seguir, de acordo com a região do seu dashboard da Braze.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

Etapa 4: Crie uma nova fonte no dashboard da Braze

No dashboard da Braze, acesse Configurações de dados > Ingestão de dados na nuvem > Fontes, selecione Adicionar fonte de dados e depois selecione Databricks.

Etapa 4.1: Adicione as informações de conexão do Databricks e a tabela de origem

Digite um nome para a sua fonte e depois informe as credenciais e a configuração do Databricks:

• Em Nome da credencial, digite um rótulo que ajude a identificar essas credenciais na Braze.
• Em Método de autenticação, selecione o método que você configurou na Etapa 2 e informe as credenciais correspondentes. Para OAuth M2M, insira Client ID and Client secret. Para Personal access token, insira Access token.

Em seguida, siga para a próxima etapa.

Etapa 4.2: Teste a conexão e conecte-se à fonte

Depois, selecione Testar conexão. Se o teste for bem-sucedido, conclua as configurações restantes e clique em Conectar à fonte. Se a conexão falhar, uma mensagem de erro vai aparecer para ajudar a solucionar o problema.

Nota

Você precisa testar uma fonte com sucesso antes de criá-la. Se você fechar a página de criação, sua fonte não será salva.

Etapa 5: Crie uma nova sincronização no dashboard da Braze

Acesse Configurações de dados > Ingestão de dados na nuvem > Sincronizações e selecione Criar sincronização de dados.

Configure os detalhes da sincronização e defina seus dados

Digite um nome para a sua sincronização. Em seguida, selecione uma fonte ativa e um tipo de dado para a sincronização. Depois, selecione Visual ou Tabela e informe sua tabela de origem, ou selecione SQL para escrever uma consulta SQL personalizada. Por fim, selecione Pré-visualizar e validar.

Depois que a validação for bem-sucedida, uma prévia dos dados vai aparecer. Selecione Próximo: Notificações para continuar. Se a validação falhar, uma mensagem de erro vai aparecer para ajudar a solucionar o problema.

Nota

Você precisa validar uma sincronização com sucesso antes de seguir para as próximas etapas. Se precisar fechar a página de criação da sincronização, selecione Salvar como rascunho para manter o trabalho em andamento.

Adicionar preferências de notificação

Insira um ou mais e-mails de contato para receber notificações de erros de sincronização. A Braze usa essas informações de contato para enviar notificações sobre erros de integração, como a perda inesperada de acesso a uma tabela.

Os e-mails de contato recebem apenas notificações de erros globais ou no nível da sincronização, como tabelas ausentes, problemas de permissões e outros. Eles não recebem notificações de problemas no nível da linha. Os erros globais indicam problemas críticos na conexão que impedem a execução das sincronizações.

Esses problemas podem incluir:

• Problemas de conectividade
• Falta de recursos
• Problemas de permissões
• O nível do catálogo está sem espaço (somente sincronizações de catálogo)

Definir o cronograma

Por fim, configure a sincronização como não recorrente ou recorrente.

As sincronizações não recorrentes são executadas somente quando você seleciona Sincronizar agora no dashboard ou chama o endpoint Disparar uma sincronização.

As sincronizações recorrentes podem ser executadas com frequência de até uma vez a cada 5 minutos ou com intervalo de até uma vez por mês. Por padrão, o intervalo mais curto que você pode definir no dashboard é de 15 minutos. Isso ajuda a gerenciar os custos de computação e o volume de solicitações do seu data warehouse. Para sincronizar a cada 5 minutos, entre em contato com o suporte da Braze ou com seu gerente de sucesso do cliente. A Braze agenda as sincronizações recorrentes em UTC.

Nota

Você precisa validar uma integração com sucesso antes que ela passe do estado Rascunho para Ativo. Se você fechar a página de criação, sua integração será salva, e você poderá voltar à página de detalhes para fazer alterações e validar.

Execute a sincronização

Depois de ativada, sua sincronização é executada no cronograma definido durante a configuração. Se quiser executar a sincronização fora do cronograma ou buscar os dados mais recentes, selecione Sincronizar agora. Essa execução não afeta as próximas sincronizações agendadas. Para iniciar uma sincronização automaticamente quando seus dados forem atualizados, chame o endpoint Disparar uma sincronização a partir do seu pipeline.

Configure integrações ou usuários adicionais (opcional)

Você pode configurar várias integrações com a Braze. Ao criar sincronizações adicionais, pode reutilizar credenciais existentes se estiver se conectando à mesma conta do Databricks.

Se você reutilizar o mesmo usuário em várias integrações, não poderá excluir esse usuário no dashboard da Braze até que ele seja removido de todas as sincronizações ativas.

Use o Databricks como fonte conectada

Uma fonte conectada é uma alternativa zero-copy à sincronização de dados com a Braze. A Braze consulta diretamente sua instância do Databricks para criar segmentos CDI, sem copiar os dados subjacentes. Para conhecer os conceitos, as limitações e os impactos nos custos, consulte Fontes conectadas.

Importante

Pode haver um tempo de aquecimento de dois a cinco minutos quando a Braze se conecta a instâncias SQL Classic e Pro. Isso causa atrasos na configuração e no teste da conexão, e também na criação e atualização de extensões de segmento CDI. Usar uma instância SQL serverless minimiza o tempo de aquecimento e melhora a taxa de transferência de consultas, mas pode gerar custos de integração um pouco maiores.

Etapa 1: Configure a autenticação e conceda permissões

Configure as credenciais da Braze com um dos métodos da Etapa 2: Configure a autenticação. Seja qual for o método escolhido, a Braze usa essas credenciais para gerar a lista de tabelas disponíveis nas suas extensões de segmento CDI e para consultar as tabelas de origem ao criar novos segmentos. Depois que a fonte conectada é criada, a Braze descobre os nomes e as descrições de todas as tabelas disponíveis para o usuário no esquema de origem.

Você pode conceder acesso a todas as tabelas de um esquema ou conceder privilégios apenas a tabelas específicas. Todas as tabelas às quais a função da Braze tiver acesso ficam disponíveis para consulta na extensão de segmento CDI.

A permissão CREATE TABLE é necessária para que a Braze possa criar uma tabela com os resultados da consulta da sua extensão de segmento CDI antes de atualizar o segmento na Braze. A Braze cria uma tabela temporária por segmento, que só existe enquanto a Braze atualiza o segmento.

• OAuth M2M: Conceda à entidade de serviço acesso ao esquema usado pela fonte conectada, incluindo CREATE TABLE. Use o ID da aplicação da entidade de serviço (o mesmo valor do ID do cliente) como beneficiário da concessão.

  
  1
  2
  3
  
    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`;
  
  

  Substitua APPLICATION_ID pelo ID da aplicação da sua entidade de serviço.

• Token de acesso pessoal: Confira se a conta de serviço tem privilégios de CREATE TABLE no esquema usado pela fonte conectada.

A configuração de acesso à rede é a mesma da Etapa 3.

Etapa 2: Crie a fonte conectada na Braze

Acesse Configurações de dados > Ingestão de dados na nuvem > Fontes conectadas, selecione Adicionar fonte de dados e depois selecione Databricks.

Em Configurar fonte, informe o seguinte:

• Credenciais: Nome da credencial, Método de autenticação, Nome do host, Caminho HTTP e os campos do seu método de autenticação. Para OAuth M2M, insira Client ID and Client secret. Para Personal access token, insira Access token.
• Configuração: Catálogo e Esquema

Escolha um nome para a fonte conectada. Esse nome aparece na lista de fontes disponíveis quando você cria uma nova extensão de segmento CDI.

Configure um tempo máximo de execução para essa fonte. A Braze interrompe automaticamente todas as consultas que ultrapassarem o tempo máximo de execução. O tempo máximo permitido é de 60 minutos. Um tempo menor reduz os custos na sua conta do Databricks. Essa configuração se aplica às consultas executadas por essa fonte, incluindo as sincronizações e as extensões de segmento CDI que a utilizam.

Selecione Testar conexão para verificar se a lista de tabelas visíveis para o usuário é a esperada e depois selecione Concluído. Sua fonte conectada está criada e pronta para uso em extensões de segmento CDI.

Você pode configurar várias fontes conectadas com a Braze, mas cada fonte deve se conectar a um esquema diferente. Ao criar fontes adicionais, você pode reutilizar credenciais existentes se estiver se conectando à mesma conta do Databricks.

Formate uma carga útil a partir de colunas existentes

Se você prefere armazenar internamente cada atributo em uma coluna própria, precisa converter essas colunas em uma string JSON para preencher a sincronização com a Braze. Use esta consulta no Databricks para formatar as colunas de origem nos campos da CDI.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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 ver mais orientações de otimização, consulte Práticas recomendadas da Ingestão de dados na nuvem.

Solução de problemas

O teste de conexão está lento

O teste de conexão é executado no seu data warehouse, então aumentar a capacidade do warehouse pode melhorar a velocidade. No Databricks, pode haver um tempo de aquecimento de dois a cinco minutos quando a Braze se conecta a instâncias SQL Classic e Pro. Isso causa atrasos na configuração e no teste da conexão, e também no início das sincronizações agendadas. Usar uma instância SQL serverless minimiza o tempo de aquecimento e melhora a taxa de transferência de consultas, mas pode gerar custos de integração um pouco maiores.

Falha no comando porque o warehouse foi interrompido

Se você receber esse erro, confira se o warehouse do Databricks está em execução.

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

Se você receber esse erro, consulte Databricks: Forbidden error while accessing S3 data.

Onde executar verificações SQL

Execute as verificações de validação diretamente no editor SQL do Databricks em um SQL warehouse, na mesma tabela ou visualização usada pela sua integração de CDI. Para saber mais, consulte Editor SQL do Databricks.

Páginas relacionadas

• Configuração da tabela para colunas obrigatórias e formatação da carga útil
• Melhores práticas para agendamento de sincronizações e eficiência no uso de pontos de dados
• Logs de sincronização e observabilidade para monitorar as execuções de sincronização
• Perguntas frequentes para dúvidas comuns sobre todas as fontes