Integrações de armazenamento de data warehouse

1. Crie uma entidade de serviço e conceda acesso às APIs do Fabric.
2. Configure um espaço de trabalho compartilhado e conceda à entidade de serviço acesso a ele.
3. No espaço de trabalho compartilhado do Fabric, configure as tabelas ou visualizações que você quer sincronizar com a Braze.
4. Crie uma nova fonte e uma sincronização no dashboard da Braze.
5. Teste a integração e inicie a sincronização.

Etapa 1.1: Configurar a entidade de serviço e conceder acesso

A Braze se conecta ao seu warehouse do Fabric usando uma entidade de serviço com autenticação do Entra ID. Crie uma nova entidade de serviço para a Braze usar e conceda acesso aos recursos do Fabric conforme necessário. A Braze precisa das seguintes informações para se conectar:

• ID do locatário (também chamado de diretório) da sua conta Azure
• ID da entidade de segurança (também chamado de ID do aplicativo) para a entidade de serviço
• Segredo do cliente para a Braze autenticar

1. No portal do Azure, navegue até o centro de administração do Microsoft Entra e, em seguida, App Registrations.
2. Selecione + New registration em Identity > Applications > App registrations
3. Insira um nome e selecione Accounts in this organizational directory only como o tipo de conta compatível. Em seguida, selecione Register.
4. Selecione o app (service principal) que você acabou de criar e navegue até Certificates & secrets > + New client secret
5. Insira uma descrição para o segredo e defina um período de vencimento para o segredo. Em seguida, selecione Add.
6. Anote o segredo do cliente criado para usar na configuração da Braze.

Nota

O Azure não permite vencimento ilimitado para segredos de entidades de serviço. Lembre-se de renovar as credenciais antes que elas expirem para manter o fluxo de dados para a Braze.

Etapa 1.2: Conceder acesso aos recursos do Fabric

Dê à Braze acesso para se conectar à sua instância do Fabric. No portal de administração do Fabric, acesse Settings > Governance and insights > Admin portal > Tenant settings.

• Em Developer settings, ative Service principals can use Fabric APIs para que a Braze possa se conectar usando o Microsoft Entra ID.
• Em OneLake settings, ative Users can access data stored in OneLake with apps external to Fabric para que a entidade de serviço possa acessar dados a partir de um app externo.

Etapa 1.3: Configurar um espaço de trabalho compartilhado e conceder acesso

Todos os recursos do Fabric que você quer conectar à Braze devem estar em um espaço de trabalho compartilhado. Se você usava apenas o My Workspace padrão, crie um novo espaço de trabalho compartilhado:

1. No menu de navegação, selecione Workspaces e, em seguida, selecione + New workspace.
2. Insira um Name para o espaço de trabalho e selecione Apply.

Depois de ter um espaço de trabalho compartilhado, conceda acesso à entidade de serviço:

1. Selecione o espaço de trabalho e, em seguida, selecione Manage Access.
2. Selecione + Add people or groups.
3. Pesquise e selecione o nome da entidade de serviço que você criou na Etapa 1.1. Se ela não aparecer, confirme se você ativou a configuração Service principals can use Fabric APIs na Etapa 1.2.
4. No menu suspenso de função, selecione Contributor.

Agora a entidade de serviço pode acessar os recursos de warehouse do Fabric nesse espaço de trabalho por meio dos endpoints SQL, incluindo o warehouse a ser usado com a Braze.

Etapa 1.4: Configurar a tabela

A Braze oferece suporte a tabelas e visualizações em warehouses do Fabric. Se precisar criar um novo warehouse, crie-o dentro do espaço de trabalho compartilhado da Etapa 1.3. Acesse Create > Data Warehouse > Warehouse no console do Fabric.

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

CREATE OR ALTER TABLE [warehouse].[schema].[CDI_table_name]
(
  UPDATED_AT DATETIME2(6) NOT NULL,
  PAYLOAD VARCHAR NOT NULL,
  --at least one of external_id, alias_name and alias_label, email, phone, or braze_id is required
  EXTERNAL_ID VARCHAR,
  --if using user alias, both alias_name and alias_label are required
  ALIAS_NAME VARCHAR,
  ALIAS_LABEL VARCHAR,
  --braze_id can only be used to update existing users created through the Braze SDK
  BRAZE_ID VARCHAR,
  --If you include both email and phone, email is used as the primary identifier
  EMAIL VARCHAR,
  PHONE VARCHAR
)
GO

Você pode dar o nome que quiser ao warehouse, ao esquema e à tabela ou visualização, mas os nomes das colunas devem corresponder à definição anterior.

• 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. Linhas com o carimbo de data/hora exatamente no limite podem ser sincronizadas novamente se novas linhas compartilharem 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ê quer 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 ú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.
  • 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.
  • EMAIL - O endereço de e-mail do usuário. Se houver vários perfis com o mesmo endereço de e-mail, o perfil atualizado mais recentemente terá prioridade nas atualizações. Se você incluir e-mail e telefone, o e-mail será usado como identificador principal.
  • PHONE - O número de telefone do usuário. Se houver vários perfis com o mesmo número de telefone, o perfil atualizado mais recentemente terá prioridade nas atualizações.
• PAYLOAD - Uma string JSON com os campos que você quer sincronizar com o usuário na Braze.

Etapa 1.5: Obter a string de conexão do warehouse

Para obter o endpoint SQL do seu warehouse, acesse o workspace no Fabric, passe o mouse sobre o nome do warehouse na lista de itens e selecione Copy SQL connection string.

Etapa 1.6: Permitir IPs da Braze no firewall (opcional)

Dependendo da configuração da sua conta do Microsoft Fabric, pode ser necessário permitir os seguintes endereços IP no seu firewall para liberar o tráfego da Braze. Para saber mais sobre como ativar isso, consulte a documentação sobre o Acesso Condicional do Entra.

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

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

Etapa 2.1: Configurar uma sincronização da Ingestão de dados na nuvem

Escolha um nome para sua fonte e insira suas credenciais e configurações do Microsoft Fabric.

• Nome das credenciais é um rótulo para essas credenciais na Braze. Você pode definir aqui um valor que ajude na identificação.
• Consulte as etapas da seção 1 para saber como obter o ID do locatário, o ID do principal, o segredo do cliente e a string de conexão.

Etapa 2.2: Testar a conexão e conectar à fonte

Em seguida, selecione Testar conexão. Quando o teste for bem-sucedido, finalize as configurações restantes e selecione Conectar à fonte. Se a conexão falhar, uma mensagem de erro 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 3.1: Configurar os detalhes da sincronização e definir seus dados

Insira um nome para sua sincronização. Em seguida, selecione uma fonte ativa e um tipo de dados de sincronização. Depois, selecione Visual ou Tabela e insira sua tabela de origem, ou selecione SQL para escrever uma consulta SQL personalizada. Por fim, selecione Prévia e validação.

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

Nota

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

Etapa 3.2: Adicionar preferências de notificação

Insira um ou mais e-mails de contato para notificações de erro 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 à tabela.

Os e-mails de contato recebem apenas notificações de erros globais ou no nível da sincronização, como tabelas ausentes, permissões e outros. Eles não recebem problemas no nível da linha. 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ão
• Falta de espaço no nível do catálogo (somente sincronizações de catálogo)

Etapa 3.3: Agendamento

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

As sincronizações não recorrentes são executadas apenas 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é a cada 5 minutos ou tão raramente quanto uma vez por mês. Por padrão, o menor intervalo que você pode definir no dashboard é de 15 minutos, o que ajuda a gerenciar os custos de computação do seu warehouse e o volume de solicitações. 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.

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

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

Depois de ativada, a sincronização é executada no cronograma configurado 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 regularmente. Para iniciar uma sincronização automaticamente quando seus dados forem atualizados, chame o endpoint Disparar uma sincronização a partir do seu pipeline.