Ingestão de dados na nuvem para o Azure Blob Storage

Esta página traz tudo o que você precisa para sincronizar dados do Azure Blob Storage com a Braze usando a ingestão de dados na nuvem (CDI): os recursos do Azure que você precisa criar, como conectar a fonte e criar uma sincronização na Braze, o formato de arquivo de cada tipo de dado e a solução de problemas específica do Azure.

Como funciona

As integrações com o Azure Blob Storage são orientadas por eventos, e não agendadas. Quando novos arquivos são criados no contêiner, uma assinatura de eventos no Azure Event Grid publica um evento Blob Created em uma fila do Azure Storage. A Braze lê essas mensagens da fila para ingerir o novo arquivo.

A integração exige os seguintes recursos:

• Uma conta de armazenamento com um contêiner de blobs para armazenar os dados
• Uma fila do Azure Storage e uma assinatura de eventos para as notificações de novos arquivos
• Uma entidade de serviço do Microsoft Entra ID que a CDI usa para ler o contêiner e a fila

Definições do Azure

Configurar a ingestão de dados na nuvem no Azure

Etapa 1: Criar um contêiner

O contêiner e a fila precisam ficar na mesma conta de armazenamento. Você pode reutilizar uma conta de armazenamento existente. Se ainda não tiver uma, acesse Storage accounts > + Create no portal do Azure para criá-la.

1. No portal do Azure, acesse sua conta de armazenamento e, depois, Data storage > Containers.
2. Selecione + Add container e dê um nome a ele.

Anote o nome da conta de armazenamento e o nome do contêiner. Você vai precisar dos dois ao configurar a fonte na Braze.

Etapa 2: Criar uma fila

1. Na mesma conta de armazenamento, acesse Data storage > Queues.
2. Selecione + Queue e dê um nome a ela.

Anote o nome da fila. Você vai precisar dele ao criar a sincronização, e cada sincronização precisa da sua própria fila.

Etapa 3: Criar uma assinatura de eventos

Crie uma assinatura de eventos para que o contêiner avise a fila sempre que um arquivo chegar.

1. Na mesma conta de armazenamento, acesse Events e selecione + Event Subscription.
2. Em Event Subscription Details, insira um Name e defina Event Schema como Event Grid Schema.
3. Em Topic Details, revise o System Topic Name. Se a sua conta de armazenamento ainda não tiver um tópico do sistema, insira um nome para criar um. Se já tiver, o campo mostra esse nome e não pode ser alterado. Todas as assinaturas de eventos de uma conta de armazenamento usam o mesmo tópico do sistema.
4. Em Event Types, defina Filter to Event Types apenas como Blob Created. O Blob Deleted também vem selecionado por padrão, então desmarque essa opção.
5. Em Endpoint Details, defina Endpoint Type como Storage Queue. O link Configure an endpoint aparece depois que você escolhe um tipo de endpoint.
6. Selecione Configure an endpoint e escolha a conta de armazenamento em que você está trabalhando.
7. Selecione Select existing queue e escolha a fila que você criou na etapa 2.
8. Selecione Select para confirmar o endpoint.
9. Selecione Create.

Etapa 4: Configurar a autenticação

A CDI se conecta à sua conta de armazenamento com o seguinte método de autenticação:

Service principal

O CDI se conecta à sua conta de armazenamento usando uma entidade de serviço com autenticação do Microsoft Entra ID. A Braze precisa dos seguintes detalhes 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

Para registrar um aplicativo, você precisa de permissão para criar registros de aplicativo no Microsoft Entra ID. Se você não tiver essa permissão, peça a um administrador do Entra para concluir esta etapa e compartilhar as credenciais com você.

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 do vencimento para manter o fluxo de dados para a Braze.

Recomendamos criar uma entidade de serviço usada somente para o CDI, para que o acesso dela fique limitado ao contêiner e à fila que você está sincronizando. Se você já tiver uma configurada para uma fonte do Microsoft Fabric, pode reutilizá-la, mas ela passará a ter acesso a ambos. De qualquer forma, ela precisa das atribuições de função descritas na próxima etapa.

Etapa 5: Atribuir permissões à entidade de serviço

A CDI só precisa de acesso suficiente para ler seus arquivos e processar as mensagens da fila. Atribua estas três funções integradas na própria conta de armazenamento, e não na assinatura ou no grupo de recursos, porque as atribuições de função são herdadas pelos níveis abaixo. Não atribua funções mais amplas, como Storage Blob Data Contributor, Storage Account Contributor ou Owner, que concedem permissões de gravação e gerenciamento que a CDI nunca usa.

1. Acesse sua conta de armazenamento e, depois, Access Control (IAM).
2. Selecione Add > Add role assignment.
3. Pesquise pelo nome a entidade de serviço que você criou na etapa 4.
4. Atribua a ela as seguintes funções integradas:
   • Storage Blob Data Reader: permite que a CDI leia os arquivos do seu contêiner.
   • Storage Queue Data Reader: permite que a CDI leia a própria fila, para encontrar a fila que você informou na sincronização e verificar as propriedades dela.
   • Storage Queue Data Message Processor: permite que a CDI visualize, recupere e exclua mensagens da sua fila.

Você também pode usar uma função personalizada, desde que ela conceda apenas acesso de leitura aos blobs do contêiner, acesso de leitura à fila e a capacidade de receber e excluir mensagens da fila.

Nota

Se a opção Add role assignment estiver desativada, sua conta não pode atribuir funções nessa conta de armazenamento. Isso exige uma função como Owner ou User Access Administrator. Peça a um administrador do Azure para concluir esta etapa.

Configurar a ingestão de dados na nuvem na Braze

1. Na Braze, acesse Configurações de dados > Ingestão de dados na nuvem > Fontes, selecione Adicionar fonte de dados e, em seguida, selecione Azure Blob.

2. Preencha os campos de Detalhes da conexão do Azure Blob:
   • Credenciais: os campos do método de autenticação que você configurou na etapa 4. Insira Tenant ID, Principal ID, and Client Secret.
   • Configuração: Conta de armazenamento e Contêiner

3. Selecione Testar conexão e, depois, Conectar à fonte.
4. Crie uma sincronização. Acesse Configurações de dados > Ingestão de dados na nuvem > Sincronizações e selecione Criar sincronização de dados.
5. Em Configurações, escolha um nome para a sincronização, selecione sua fonte do Azure Blob e escolha um Tipo de dados (como Atributos do usuário, Eventos personalizados, Eventos de compra, Catálogo ou Excluir usuários).
6. Em Definição de dados, especifique o seguinte:
   • Nome da fila de armazenamento: a fila que você criou na etapa 2. Cada sincronização precisa da sua própria fila (consulte Sincronizar uma pasta em um contêiner compartilhado).
   • Caminho da pasta (opcional): um prefixo de caminho dentro do contêiner

7. Selecione Prévia e validação para confirmar que a CDI consegue acessar a fila e listar os arquivos disponíveis para ingestão. Um teste bem-sucedido lista os arquivos existentes no contêiner, mas esses arquivos não são sincronizados automaticamente. A sincronização só fica ativa depois que a conexão é validada com sucesso.
8. Em Notificações, adicione endereços de e-mail de contato para receber notificações de erro.
9. Agendamento não tem opções para sincronizações de armazenamento de arquivos. As sincronizações do Azure Blob Storage são orientadas por eventos, então a CDI ingere os novos arquivos assim que eles são enviados.
10. Revise o Resumo e selecione Criar sincronização.

Sincronizar uma pasta em um contêiner compartilhado

Você pode reutilizar um contêiner em várias sincronizações, mas cada sincronização precisa da sua própria fila de armazenamento e da sua própria pasta.

Importante

Duas sincronizações não podem usar a mesma fila de armazenamento. Se você inserir uma fila que já é usada por outra sincronização, a CDI sinaliza o problema e mostra um link para a sincronização existente.

Para cada pasta que você quer sincronizar em um contêiner compartilhado:

1. Crie uma fila para essa pasta, como na etapa 2.
2. Crie uma assinatura de eventos que envie os eventos Blob Created do contêiner para essa fila, como na etapa 3.
3. Ao criar a sincronização na Braze, insira o Nome da fila de armazenamento dessa pasta e defina o Caminho da pasta (opcional) como o prefixo da pasta, por exemplo attributes/. A CDI só ingere arquivos cujo caminho começa com esse prefixo.

Formatos de arquivo obrigatórios

A Ingestão de dados na nuvem aceita arquivos JSON, CSV e Parquet. As colunas obrigatórias variam conforme o tipo de dados. A Braze não impõe nenhum requisito de nome de arquivo além dos que o seu provedor de armazenamento de arquivos já exige. Os nomes de arquivo devem ser exclusivos, e adicionar um carimbo de data/hora ajuda a garantir isso.

Nota

Ao contrário das fontes de data warehouse, a coluna UPDATED_AT não é obrigatória nem compatível com sincronizações de armazenamento de arquivos.

Para ver exemplos de todos os tipos de arquivo aceitos, confira os arquivos de amostra em braze-examples.

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

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

Cada linha precisa ter exatamente um identificador de usuário e uma coluna PAYLOAD. Um arquivo de origem pode ter linhas com tipos de identificador diferentes, mas cada linha deve usar apenas um.

Identificador	Descrição
EXTERNAL_ID	Identifica o usuário que você quer atualizar. Deve corresponder ao valor 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 pela 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, a Braze usará o e-mail 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.

A coluna PAYLOAD contém uma string JSON com os campos que você quer sincronizar com o usuário na Braze, seguindo o formato do objeto de atributos do usuário.

Exemplo de JSON

1
2
3

{"external_id":"s3-qa-0","payload":"{\"name\": \"GT896\", \"age\": 74, \"subscriber\": true, \"retention\": {\"previous_purchases\": 21, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600803\"}"}
{"external_id":"s3-qa-1","payload":"{\"name\": \"HSCJC\", \"age\": 86, \"subscriber\": false, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600824\"}"}
{"external_id":"s3-qa-2","payload":"{\"name\": \"YTMQZ\", \"age\": 43, \"subscriber\": false, \"retention\": {\"previous_purchases\": 23, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600831\"}"}

Exemplo de CSV

1
2
3

external_id,payload
s3-qa-load-0-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""SNXIM"", ""age"": 54, ""subscriber"": true, ""retention"": {""previous_purchases"": 19, ""vip"": true}, ""last_visit"": ""2023-08-08T16:03:26.598806""}"
s3-qa-load-1-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""0J747"", ""age"": 73, ""subscriber"": false, ""retention"": {""previous_purchases"": 22, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598816""}"

Importante

Todas as linhas do arquivo de origem devem conter JSON válido. Caso contrário, o arquivo será ignorado.

Os eventos personalizados usam as mesmas colunas de identificador de usuário que os atributos do usuário. A coluna PAYLOAD segue o formato do objeto de eventos.

1
2

{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}

Importante

Todas as linhas do arquivo de origem devem conter JSON válido. Caso contrário, o arquivo será ignorado.

Os eventos de compra usam as mesmas colunas de identificador de usuário que os atributos do usuário. A coluna PAYLOAD segue o formato do objeto de compras.

1
2

{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}

Importante

Todas as linhas do arquivo de origem devem conter JSON válido. Caso contrário, o arquivo será ignorado.

Os arquivos de catálogo usam identificadores diferentes dos arquivos de dados de usuários. Antes de criar uma sincronização de catálogo, crie o catálogo de destino na Braze. Para ver o fluxo de trabalho completo de catálogos, consulte Sincronizar e excluir dados de catálogo.

Coluna	Obrigatório	Descrição
ID	Sim	O identificador exclusivo do item de catálogo. É usado para criar, atualizar ou excluir o item na Braze.
PAYLOAD	Sim	Uma string JSON com os campos e valores do catálogo a serem sincronizados. Deve corresponder ao esquema do seu catálogo na Braze.
DELETED	Não	Quando for true, o item de catálogo com o ID correspondente será removido do catálogo na Braze. Omita essa coluna ou defina-a como false para operações de criação ou atualização.

Exemplo de JSON

{"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}

Exemplo de CSV com a coluna DELETED

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

Exemplo de CSV sem a coluna DELETED

1
2
3

ID,PAYLOAD
85,"{""product_name"": ""Product 85"", ""price"": 85.85}"
86,"{""product_name"": ""Product 86"", ""price"": 86.86}"

Os disparadores de Canvas viabilizam a personalização sem cópia de dados (zero-copy). Para ver a configuração do Canvas de destino e as considerações, consulte Personalização sem cópia de dados.

Campo	Obrigatório	Descrição
EXTERNAL_ID	Sim, external_id ou alias_name e alias_label	Identifica o usuário que você quer atualizar. Deve corresponder ao valor external_id usado na Braze.
ALIAS_NAME e ALIAS_LABEL	Sim, external_id ou 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.
PROPERTIES	Sim	String JSON com os campos que ficarão disponíveis como propriedades de personalização no seu Canvas. Deve conter informações específicas do usuário.

Para começar, selecione o tipo de dados Disparadores de Canvas ao criar uma nova sincronização.

Para excluir perfis de usuário na Braze usando arquivos do seu bucket de origem:

1. Crie uma nova sincronização de Ingestão de dados na nuvem, usando a mesma configuração das outras sincronizações.
2. Ao configurar a sincronização na Braze, defina Tipo de dados como Excluir usuários.
3. Faça upload de arquivos para o bucket de origem que contenham apenas colunas de identificador de usuário. Não inclua uma coluna PAYLOAD. Para evitar exclusões acidentais, a sincronização falha se houver carga útil.

Cada linha do arquivo deve identificar exatamente um usuário usando um destes identificadores:

Identificador	Descrição
EXTERNAL_ID	Corresponde ao external_id usado na Braze.
ALIAS_NAME e ALIAS_LABEL	As duas colunas juntas identificam o usuário pelo alias.
BRAZE_ID	ID do usuário gerado pela Braze (somente usuários existentes).

Exemplo de JSON

{"external_id":"user-to-delete-001"}
{"external_id":"user-to-delete-002"}
{"braze_id":"braze-id-from-profile"}

Exemplo de CSV

1
2
3

external_id
user-to-delete-001
user-to-delete-002

Quando a sincronização é executada, a Braze processa os novos arquivos do bucket e exclui os perfis de usuário correspondentes.

Importante

A exclusão de usuários é permanente e não pode ser desfeita. Inclua apenas os usuários que você pretende remover. Para saber mais, consulte Excluir usuários com a Ingestão de dados na nuvem.

Excluir itens do catálogo

Para remover itens de um catálogo usando armazenamento de arquivos:

1. Use a mesma sincronização que você usa para sincronizar dados do catálogo (tipo de dados Catálogos).
2. Nos seus arquivos CSV ou JSON, adicione uma coluna opcional deleted (ou DELETED).
3. Defina deleted como true para qualquer item que você queira remover do catálogo na Braze.

Cada linha ainda precisa de ID e PAYLOAD. Nas linhas marcadas para exclusão, a carga útil pode ser mínima, porque a Braze remove o item pelo ID.

Quando a sincronização é executada, as linhas com deleted: true fazem com que o item de catálogo correspondente seja excluído na Braze. Para saber mais sobre a sincronização completa do catálogo e o comportamento de exclusão, consulte Sincronizar e excluir dados do catálogo.

Informações importantes

• Os arquivos adicionados ao bucket ou contêiner de origem não devem exceder 512 MB. Esse limite se aplica ao Amazon S3, ao Google Cloud Storage e ao Azure Blob Storage. Arquivos maiores que 512 MB resultam em erro e não são sincronizados com a Braze. O próprio Azure Blob Storage permite arquivos muito maiores, mas a CDI aplica o mesmo limite de 512 MB a todas as fontes de armazenamento de arquivos.
• Embora não haja limite adicional para o número de linhas por arquivo, a Braze recomenda usar arquivos menores para acelerar suas sincronizações. Por exemplo, um arquivo de 500 MB levaria bem mais tempo para ser ingerido do que cinco arquivos separados de 100 MB.
• Não há limite adicional para o número de arquivos enviados em um determinado período.
• A ordenação não é suportada dentro dos arquivos nem entre eles. Se você estiver monitorando possíveis condições de corrida, a Braze recomenda atualizar os dados em lotes periodicamente.
• A CDI só processa arquivos adicionados depois que a sincronização é criada. Você pode usar arquivos existentes para validar se a Braze consegue acessar seu bucket e detectar os arquivos a serem ingeridos, mas eles não são sincronizados com a Braze. Para que a CDI processe esses arquivos, envie novamente ao bucket de origem todos os arquivos existentes que você quer sincronizar.

Solução de problemas

Envio e processamento de arquivos

A CDI só processa arquivos enviados depois que a sincronização é criada. Cada novo blob dispara um evento Blob Created para a sua fila. Para ingerir arquivos que já existem no contêiner, envie-os novamente.

Como lidar com erros inesperados de arquivo

Se os arquivos não estiverem sendo ingeridos, verifique o seguinte:

• A assinatura de eventos existe na conta de armazenamento e está filtrada para Blob Created.
• A assinatura de eventos usa o Event Grid Schema. A CDI não consegue ler eventos entregues em outro esquema.
• O endpoint da assinatura de eventos aponta para a fila configurada na sincronização, e não para outra fila.
• A entidade de serviço da Braze tem as funções Storage Blob Data Reader, Storage Queue Data Reader e Storage Queue Data Message Processor na conta de armazenamento.
• O segredo do cliente da entidade de serviço não venceu. O Azure aplica um vencimento aos segredos do cliente, e um segredo vencido interrompe a sincronização.

Para saber mais, consulte Azure Blob Storage como fonte do Event Grid na documentação da Microsoft.

Erro de objeto de integração incorreto

Esse erro ocorre quando dois ou mais espaços de trabalho têm integrações apontando para o mesmo bucket ou pasta de armazenamento em nuvem. Cada local de armazenamento em nuvem só pode ser usado por uma integração por vez. Para ver as etapas de resolução, consulte as Perguntas frequentes.

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