Integrações de armazenamento de arquivos

Esta página aborda como configurar a Ingestão de Dados na Nuvem para sincronizar dados do Amazon S3, Google Cloud Storage ou Azure Blob Storage para a Braze.

Como funciona

Você pode usar a Ingestão de Dados na Nuvem (CDI) para integrar diretamente um ou mais buckets de armazenamento na sua conta de nuvem com a Braze. Quando você adiciona um novo arquivo a um bucket, seu provedor de nuvem publica uma notificação, e a Ingestão de Dados na Nuvem da Braze sincroniza os dados.

O mecanismo de notificação depende do seu provedor:

• Amazon S3: quando novos arquivos são publicados no S3, uma mensagem é postada em uma fila do Amazon Simple Queue Service (SQS), e a Braze consome essa mensagem para ingerir o novo arquivo.
• Google Cloud Storage (GCS): quando novos arquivos são finalizados no bucket, o GCS publica uma notificação OBJECT_FINALIZE em um tópico Pub/Sub. A Braze consome essas notificações de uma assinatura Pub/Sub para ingerir o novo arquivo.
• Azure Blob Storage: quando novos arquivos são criados no contêiner, uma assinatura de evento 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 Ingestão de Dados na Nuvem é compatível com os seguintes formatos:

• Arquivos JSON
• Arquivos CSV
• Arquivos Parquet
• Dados de atributos, eventos personalizados, eventos de compra, exclusão de usuários e catálogos

Configurando a Ingestão de Dados na Nuvem

As etapas de configuração dependem do seu provedor de armazenamento de arquivos. Selecione a guia do seu provedor e, em seguida, conclua a configuração compartilhada nas seções a seguir.

• amazon s3
• google cloud storage
• azure blob

A integração requer os seguintes recursos:

• Bucket S3 para armazenamento de dados
• Fila SQS para notificações de novos arquivos
• Função IAM para acesso da Braze

Definições da AWS

Termo	Definição
Amazon Resource Name (ARN)	O ARN é um identificador único para recursos da AWS.
Identity and Access Management (IAM)	IAM é um serviço web que permite controlar com segurança o acesso aos recursos da AWS. Neste tutorial, crie uma política IAM e atribua-a a uma função IAM para integrar o seu bucket S3 com a Ingestão de Dados na Nuvem da Braze.
Amazon Simple Queue Service (SQS)	SQS é uma fila hospedada que permite integrar sistemas e componentes de software distribuídos.

Configurando a Ingestão de Dados na Nuvem na AWS

Etapa 1: Criar um bucket de origem

Crie um bucket S3 de uso geral com as configurações padrão na sua conta AWS. Os buckets S3 podem ser reutilizados em diferentes sincronizações, desde que a pasta seja única.

As configurações padrão são:

• ACLs desativadas
• Bloquear todo o acesso público
• Desativar o versionamento do bucket
• Criptografia SSE-S3
  • SSE-S3 é o único tipo de criptografia do lado do servidor compatível. A criptografia Amazon KMS não é compatível.

Anote a região onde você criou o bucket. Você criará uma fila SQS na mesma região na próxima etapa.

Etapa 2: Criar a fila SQS

Crie uma fila SQS para rastrear quando objetos são adicionados ao bucket que você criou. Use as configurações padrão por enquanto.

Uma fila SQS deve ser globalmente única (por exemplo, apenas uma pode ser usada para uma sincronização CDI e não pode ser reutilizada em outro espaço de trabalho).

Importante

Certifique-se de criar essa fila SQS na mesma região em que você criou o bucket.

Anote o ARN e a URL da fila SQS. Você precisará deles com frequência durante essa configuração.

Etapa 3: Configurar a política de acesso

Para configurar a política de acesso, escolha Advanced options.

Adicione a seguinte declaração à política de acesso da fila, substituindo YOUR-BUCKET-NAME-HERE pelo nome do seu bucket, YOUR-SQS-ARN pelo ARN da sua fila SQS e YOUR-AWS-ACCOUNT-ID pelo ID da sua conta AWS:

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

{
  "Sid": "braze-cdi-s3-sqs-publish",
  "Effect": "Allow",
  "Principal": {
    "Service": "s3.amazonaws.com"
  },
  "Action": "SQS:SendMessage",
  "Resource": "YOUR-SQS-ARN",
  "Condition": {
    "StringEquals": {
      "aws:SourceAccount": "YOUR-AWS-ACCOUNT-ID"
    },
    "ArnLike": {
      "aws:SourceArn": "arn:aws:s3:::YOUR-BUCKET-NAME-HERE"
    }
  }
}

Etapa 4: Adicionar uma notificação de evento ao bucket S3

1. No bucket criado na etapa 1, acesse Properties > Event notifications.
2. Dê um nome à configuração. Opcionalmente, especifique um prefixo ou sufixo para direcionar se você deseja que apenas um subconjunto de arquivos seja ingerido pela Braze.
3. Em Destination, selecione SQS queue e forneça o ARN da fila SQS que você criou na etapa 2.

Nota

Se você fizer upload dos seus arquivos para a pasta raiz de um bucket S3 e depois mover alguns dos arquivos para uma pasta específica dentro do bucket, poderá encontrar um erro inesperado. Em vez disso, você pode alterar as notificações de evento para enviar apenas para os arquivos no prefixo, evitar colocar arquivos no bucket S3 fora desse prefixo ou atualizar a integração sem prefixo, o que então ingere todos os arquivos.

Etapa 5: Criar uma política IAM

Crie uma política IAM para permitir que a Braze interaja com o seu bucket de origem. Para começar, faça login no console de gerenciamento da AWS como administrador da conta.

1. Acesse a seção IAM do console da AWS, selecione Policies na barra de navegação e depois selecione Create Policy.
   
   
   
   

2. Abra a guia JSON e insira o seguinte trecho de código na seção Policy Document, substituindo YOUR-BUCKET-NAME-HERE pelo nome do seu bucket e YOUR-SQS-ARN-HERE pelo nome da sua fila SQS:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE"]
        },
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE/*"]
        },
        {
            "Effect": "Allow",
            "Action": [
                "sqs:DeleteMessage",
                "sqs:GetQueueUrl",
                "sqs:ReceiveMessage",
                "sqs:GetQueueAttributes"
            ],
            "Resource": "YOUR-SQS-ARN-HERE"
        }
    ]
}

3. Selecione Review Policy quando terminar.

4. Dê um nome e uma descrição à política e selecione Create Policy.

Etapa 6: Criar uma função IAM

Para concluir a configuração na AWS, crie uma função IAM e anexe a política IAM da etapa 5 a ela.

1. Na mesma seção IAM do console onde você criou a política IAM, acesse Roles > Create Role.

2. Na AWS, selecione Another AWS Account como o tipo de seletor de entidade confiável. Forneça o ID da sua conta Braze. Marque a caixa de seleção Require external ID.
3. Na Braze, acesse Data Settings > Cloud Data Ingestion > Sources, selecione Add data source e selecione Amazon S3 na seção de fontes de arquivo.
4. Copie o Braze Account ID gerado automaticamente.

6. Na AWS, cole o ID da conta e selecione Next.

7. Anexe a política criada na etapa 4 à função. Pesquise a política na barra de busca e marque a caixa de seleção ao lado da política para anexá-la. Selecione Next quando concluir.

Dê um nome e uma descrição à função e selecione Create Role.

8. Anote o ARN da função que você criou e o ID externo que você gerou, pois você precisará deles para criar a integração de Ingestão de Dados na Nuvem.

Configurando a Ingestão de Dados na Nuvem na Braze

1. Primeiro, crie uma nova fonte no dashboard da Braze. Acesse Data Settings > Cloud Data Ingestion > Sources, selecione Add data source e depois selecione Amazon S3.
2. Escolha um nome para a sua fonte e insira as informações do processo de configuração da AWS para criar uma nova fonte. Especifique o seguinte:

• Role ARN
• External ID
• Nome do bucket
• Região

3. Selecione Test connection para confirmar que a Braze consegue acessar o seu bucket. Após um teste bem-sucedido, selecione Connect to Source. Se a conexão falhar, uma mensagem de erro será exibida para ajudar a solucionar o problema.

4. Em seguida, crie uma nova sincronização. Acesse Data Settings > Cloud Data Ingestion > Syncs e selecione Create data sync.

5. Escolha um nome para a sua sincronização. Em seguida, selecione qualquer fonte S3 ativa e insira a tabela de origem para a sincronização. Selecione um tipo de dados e selecione Test Connection.

1. Insira as informações restantes do processo de configuração da AWS. Especifique o seguinte:
   • URL do SQS (deve ser única para cada nova integração)
   • Caminho da pasta (opcional, deve ser único entre as sincronizações em um espaço de trabalho)
2. Selecione um tipo de dados e selecione Test Connection para confirmar que a Braze consegue listar os arquivos disponíveis para ingestão (não os dados dentro desses arquivos). Após o sucesso, selecione Next: Notifications.
3. Adicione e-mails de contato para notificações caso a sincronização seja interrompida por problemas de acesso ou permissões. Opcionalmente, ative notificações para erros no nível do usuário e sucessos de sincronização.
4. Crie a sincronização.

A integração requer os seguintes recursos:

• Um bucket Cloud Storage para armazenamento de dados
• Um tópico e uma assinatura Pub/Sub para notificações de novos arquivos
• Uma conta de serviço que a Braze acessa por meio de Workload Identity Federation ou de uma chave JSON que você faz upload na Braze

Definições do GCP

Termo	Definição
Projeto do Google Cloud	Um projeto organiza todos os seus recursos do Google Cloud e é identificado por um ID de projeto e um número de projeto únicos.
Bucket Cloud Storage	Um bucket é o contêiner que armazena os arquivos de dados que você deseja que a Braze ingira.
Tópico Pub/Sub	Um tópico é o recurso nomeado que recebe notificações de novos arquivos do seu bucket Cloud Storage.
Assinatura Pub/Sub	Uma assinatura é vinculada a um tópico e entrega as mensagens dele. A Braze consome notificações de novos arquivos a partir de uma assinatura pull.
Conta de serviço	Uma conta de serviço é uma identidade não humana que a Braze usa para acessar o seu bucket e a sua assinatura. A Braze personifica essa conta por meio de Workload Identity Federation ou usa uma chave JSON que você faz upload.
Workload Identity Federation	Workload Identity Federation (WIF) permite que a Braze personifique a sua conta de serviço com uma identidade de curta duração, sem a necessidade de criar ou fazer upload de uma chave.
Função IAM	Uma função de Identity and Access Management (IAM) é um conjunto de permissões que você atribui à conta de serviço no seu bucket e na sua assinatura.

Configurando a Ingestão de Dados na Nuvem no Google Cloud

Etapa 1: Criar um bucket Cloud Storage

No console do Google Cloud, acesse Cloud Storage > Buckets > Create. Anote o ID do projeto e o nome do bucket. Você precisará deles ao configurar a fonte na Braze. Recomendamos ativar o acesso uniforme no nível do bucket para que as permissões sejam gerenciadas com IAM.

Como alternativa, crie o bucket com gcloud:

1
2
3
4

gcloud storage buckets create gs://YOUR-BUCKET-NAME \
  --project=YOUR-PROJECT-ID \
  --location=YOUR-REGION \
  --uniform-bucket-level-access

Etapa 2: Criar um tópico e uma assinatura Pub/Sub

No console do Google Cloud, acesse Pub/Sub > Topics > Create topic. Você pode permitir que o Google crie uma assinatura padrão ou criar uma separadamente. Em seguida, crie uma assinatura pull nesse tópico.

Como alternativa, use gcloud:

1
2
3

gcloud pubsub topics create YOUR-TOPIC --project=YOUR-PROJECT-ID
gcloud pubsub subscriptions create YOUR-SUBSCRIPTION \
  --topic=YOUR-TOPIC --project=YOUR-PROJECT-ID --ack-deadline=60

Anote o ID da assinatura. A Braze precisa da assinatura (não do tópico) quando você cria a sincronização. A assinatura deve ser do tipo pull.

Aviso

Não configure uma fila de dead-letter nessa assinatura. A Braze não oferece suporte a filas de dead-letter para assinaturas de Ingestão de Dados na Nuvem. Para saber mais, consulte Dead-letter topics na documentação do Google Cloud.

Etapa 3: Enviar notificações do bucket para o tópico

Importante

A criação de uma notificação do Cloud Storage para o Pub/Sub não está disponível no console do Google Cloud. Você deve usar gcloud (mostrado aqui), Terraform ou a API JSON. Para saber mais, consulte Configure Pub/Sub notifications for Cloud Storage na documentação do Google Cloud.

Primeiro, atribua ao agente de serviço do Cloud Storage a permissão para publicar no tópico e, em seguida, crie a notificação para OBJECT_FINALIZE. O evento OBJECT_FINALIZE é disparado sempre que um novo objeto é criado ou finalizado no bucket.

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

# Get the Cloud Storage service agent for your project
gcloud storage service-agent --project=YOUR-PROJECT-ID

# Assign it Pub/Sub Publisher on the topic
gcloud pubsub topics add-iam-policy-binding YOUR-TOPIC \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:service-YOUR-PROJECT-NUMBER@gs-project-accounts.iam.gserviceaccount.com" \
  --role="roles/pubsub.publisher"

# Create the OBJECT_FINALIZE notification (optionally scope to a folder with --object-prefix)
gcloud storage buckets notifications create gs://YOUR-BUCKET-NAME \
  --topic=YOUR-TOPIC \
  --event-types=OBJECT_FINALIZE \
  --payload-format=json

Substitua os seguintes marcadores nesses comandos:

• YOUR-PROJECT-ID: o ID do seu projeto do Google Cloud, o identificador legível (por exemplo, my-gcp-project).
• YOUR-TOPIC: o tópico Pub/Sub que você criou na Etapa 2.
• YOUR-BUCKET-NAME: o nome do seu bucket Cloud Storage.
• YOUR-PROJECT-NUMBER: o número do seu projeto, o identificador numérico usado no endereço de e-mail do agente de serviço do Cloud Storage. Ele é diferente do ID do projeto. Você pode encontrá-lo no Dashboard do console do Google Cloud ou executar o seguinte comando:

1

gcloud projects describe YOUR-PROJECT-ID --format="value(projectNumber)"

Etapa 4: Criar uma conta de serviço

No console do Google Cloud, acesse IAM & Admin > Service Accounts > Create service account.

Como alternativa, use gcloud:

1
2
3

gcloud iam service-accounts create braze-cdi-gcs \
  --project=YOUR-PROJECT-ID \
  --display-name="Braze CDI GCS"

Etapa 5: Atribuir permissões

O conector precisa exatamente destas permissões: storage.buckets.get, storage.objects.get e storage.objects.list no bucket, e pubsub.subscriptions.consume na assinatura. Você pode atribuí-las com uma função personalizada ou com funções predefinidas.

Função personalizada: crie uma função personalizada com exatamente essas permissões e vincule-a ao bucket e à assinatura:

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

gcloud iam roles create brazeCdiGcs --project=YOUR-PROJECT-ID \
  --title="Braze CDI GCS" \
  --permissions=storage.buckets.get,storage.objects.get,storage.objects.list,pubsub.subscriptions.consume \
  --stage=GA

gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
  --member="serviceAccount:[email protected]" \
  --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"

gcloud pubsub subscriptions add-iam-policy-binding YOUR-SUBSCRIPTION \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:[email protected]" \
  --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs"

Funções predefinidas: atribua roles/storage.objectViewer e roles/storage.legacyBucketReader no bucket, e roles/pubsub.subscriber na assinatura. A função objectViewer fornece storage.objects.get e storage.objects.list, e legacyBucketReader fornece storage.buckets.get:

1
2
3
4
5
6
7
8
9
10

gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
  --member="serviceAccount:[email protected]" \
  --role="roles/storage.objectViewer"
gcloud storage buckets add-iam-policy-binding gs://YOUR-BUCKET-NAME \
  --member="serviceAccount:[email protected]" \
  --role="roles/storage.legacyBucketReader"
gcloud pubsub subscriptions add-iam-policy-binding YOUR-SUBSCRIPTION \
  --project=YOUR-PROJECT-ID \
  --member="serviceAccount:[email protected]" \
  --role="roles/pubsub.subscriber"

Etapa 6: Configurar a autenticação

A Braze pode acessar a conta de serviço com Workload Identity Federation ou com uma chave de conta de serviço. As credenciais de chave de conta de serviço existentes continuam funcionando, e você não precisa migrá-las. Uma credencial de Workload Identity Federation pode atender tanto a fontes Google Cloud Storage quanto BigQuery.

• workload identity federation
• chave de conta de serviço

Configure um pool e um provedor de identidade de carga de trabalho e vincule o principal da Braze à conta de serviço da Etapa 4. Para ver as etapas, consulte Configurando o Google Cloud para Workload Identity Federation. Use a conta de serviço que você criou na Etapa 4 e pule a etapa de criação de conta de serviço do guia.

Se você já configurou a Workload Identity Federation para outra fonte Google Cloud Storage ou BigQuery, não é necessário repetir o processo. Conceda à conta de serviço existente as permissões da Etapa 5.

No console do Google Cloud, abra a conta de serviço, acesse Keys > Add key > Create new key e selecione JSON.

Como alternativa, use gcloud:

1
2

gcloud iam service-accounts keys create braze-cdi-gcs-key.json \
  --iam-account=[email protected]

Configurando a Ingestão de Dados na Nuvem na Braze

1. Na Braze, acesse Data Settings > Cloud Data Ingestion > Sources, selecione Add data source e depois selecione Google Cloud Storage.

2. Preencha os campos da fonte:
   • Bucket: o nome do seu bucket
   • Project ID: o ID do seu projeto GCP
   • Credential: dê um nome à credencial e selecione o método de autenticação da etapa 6. Para Workload Identity Federation, insira o Project number, Workload identity pool ID, Provider ID e Service account email. Para Service Account Key, faça upload do arquivo de chave JSON.

3. Selecione Test connection e depois selecione Connect to Source.
4. Crie uma sincronização. Acesse Data Settings > Cloud Data Ingestion > Syncs e selecione Create data sync. Escolha um nome para a sincronização e um Data Type (como User Attributes, Custom Events, Purchase Events, Catalog ou Delete Users), e selecione Next.
5. Na etapa Data definition, selecione a sua fonte GCS e especifique o seguinte:
   • Pub/Sub subscription ID: o ID da assinatura da etapa 2 (não o tópico)
   • Folder path (opcional): um prefixo de caminho dentro do bucket (consulte Sincronizando uma pasta em um bucket compartilhado)

6. Selecione Preview and validate para confirmar que a Braze consegue acessar a assinatura e listar os arquivos disponíveis para ingestão. Um teste bem-sucedido lista os arquivos existentes no bucket, mas esses arquivos não são sincronizados automaticamente.
7. Adicione e-mails de contato para notificações de erros. As sincronizações do Google Cloud Storage são orientadas a eventos, portanto não é necessário agendar. A Braze ingere novos arquivos à medida que são enviados. Revise o resumo e selecione Create sync.

Sincronizando uma pasta em um bucket compartilhado

Você pode reutilizar um bucket em várias sincronizações, mas cada sincronização deve apontar para uma pasta distinta e ter sua própria assinatura Pub/Sub dedicada.

Importante

O caminho da pasta e a assinatura devem ser únicos entre as sincronizações em um espaço de trabalho para múltiplas sincronizações que compartilham o mesmo bucket de origem. Assim como na Etapa 2, não configure uma fila de dead-letter em nenhuma dessas assinaturas.

Para cada pasta que você deseja sincronizar em um bucket compartilhado:

1. Defina o campo Folder da sincronização com o prefixo do caminho (por exemplo, attributes/). A Braze só lista e ingere objetos cujo caminho começa com esse prefixo.

2. Crie um tópico dedicado e uma notificação com escopo de prefixo para essa pasta, e depois crie uma assinatura nesse tópico:

   
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   
    # One topic per folder
    gcloud pubsub topics create YOUR-ATTRIBUTES-TOPIC --project=YOUR-PROJECT-ID
   
    # Assign the Cloud Storage service agent publisher on the topic
    gcloud pubsub topics add-iam-policy-binding YOUR-ATTRIBUTES-TOPIC \
      --project=YOUR-PROJECT-ID \
      --member="serviceAccount:service-YOUR-PROJECT-NUMBER@gs-project-accounts.iam.gserviceaccount.com" \
      --role="roles/pubsub.publisher"
   
    # Notification scoped to the folder with --object-prefix
    gcloud storage buckets notifications create gs://YOUR-BUCKET-NAME \
      --topic=YOUR-ATTRIBUTES-TOPIC --event-types=OBJECT_FINALIZE \
      --payload-format=json --object-prefix=attributes/
   
    # One subscription per sync
    gcloud pubsub subscriptions create YOUR-ATTRIBUTES-SUBSCRIPTION \
      --topic=YOUR-ATTRIBUTES-TOPIC --project=YOUR-PROJECT-ID --ack-deadline=60
   
   

3. Atribua à conta de serviço da Braze a permissão de consumo nessa assinatura, conforme descrito na Etapa 5:

   
   1
   2
   3
   4
   
    gcloud pubsub subscriptions add-iam-policy-binding YOUR-ATTRIBUTES-SUBSCRIPTION \
      --project=YOUR-PROJECT-ID \
      --member="serviceAccount:[email protected]" \
      --role="roles/pubsub.subscriber"
   
   

   Se você criou a função personalizada na Etapa 5, use --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs" em vez disso.

4. Ao criar a sincronização na Braze, insira o novo Pub/Sub subscription ID e o Folder path dessa pasta para que a sincronização ingira apenas os arquivos dessa pasta.

A integração requer os seguintes recursos:

• Uma conta de armazenamento com um contêiner de blob para armazenamento de dados
• Uma fila do Azure Storage e uma assinatura de evento para notificações de novos arquivos
• Um service principal do Microsoft Entra ID que o CDI usa para ler o contêiner e a fila

Definições do Azure

Termo	Definição
Conta de armazenamento	Uma conta de armazenamento é o recurso de nível superior do Azure que contém o contêiner de onde o CDI lê os arquivos e a fila de onde o CDI lê as notificações.
Contêiner	Um contêiner armazena os arquivos de dados que você deseja que o CDI ingira. Os contêineres ficam dentro de uma conta de armazenamento.
Fila do Azure Storage	Uma fila recebe notificações de novos arquivos do seu contêiner. O CDI lê e confirma as mensagens dessa fila para saber quais arquivos ingerir.
Assinatura de evento	Uma assinatura de evento encaminha eventos da sua conta de armazenamento para um destino, usando o serviço Azure Event Grid. Você a configura para enviar eventos de Blob Created para a sua fila.
Tópico do sistema	Um tópico do sistema representa a origem dos eventos. O Event Grid cria um para a sua conta de armazenamento quando você adiciona a primeira assinatura de evento.
Service principal	Um service principal é uma identidade do Microsoft Entra ID como a qual o CDI se autentica. Você o cria por meio de um registro de aplicativo e insere as credenciais na Braze.
Atribuição de função do Azure	Uma atribuição de função concede a um service principal um conjunto de permissões em um escopo específico. Você atribui três funções integradas ao service principal da Braze na sua conta de armazenamento.

Configurando a Ingestão de Dados na Nuvem no Azure

Etapa 1: Criar um contêiner

O contêiner e a fila devem estar 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 a sua conta de armazenamento e depois acesse 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ê precisará de ambos 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ê precisará dele ao criar a sincronização, e cada sincronização precisa da sua própria fila.

Etapa 3: Criar uma assinatura de evento

Crie uma assinatura de evento para que o seu contêiner notifique 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, verifique o System Topic Name. Se a sua conta de armazenamento ainda não tiver um tópico do sistema, insira um nome para criá-lo. Se já tiver um, o campo mostra esse nome e não pode ser alterado. Todas as assinaturas de evento em uma conta de armazenamento usam o mesmo tópico do sistema.
4. Em Event Types, defina Filter to Event Types como Blob Created apenas. Blob Deleted também é selecionado por padrão, portanto desmarque-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 depois escolha a conta de armazenamento em que você está trabalhando.
7. Selecione Select existing queue e depois escolha a fila que você criou na etapa 2.
8. Selecione Select para confirmar o endpoint.
9. Selecione Create.

Etapa 4: Criar um service principal

O CDI se conecta à sua conta de armazenamento usando um service principal 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

Registrar um aplicativo requer 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 validade ilimitada em segredos de service principal. Lembre-se de atualizar as credenciais antes que elas expirem para manter o fluxo de dados para a Braze.

Recomendamos criar um service principal usado exclusivamente para o CDI, para que o acesso dele fique limitado ao contêiner e à fila que você está sincronizando. Se você já tiver um configurado para uma fonte do Microsoft Fabric, poderá reutilizá-lo, mas nesse caso ele terá acesso a ambos. De qualquer forma, ele precisa das atribuições de função da próxima etapa.

Etapa 5: Atribuir permissões ao service principal

O CDI precisa apenas de acesso suficiente para ler os seus arquivos e processar mensagens da fila. Atribua estas três funções integradas na própria conta de armazenamento, não no nível da assinatura ou do grupo de recursos, porque as atribuições de função são herdadas de forma descendente. 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 o CDI nunca utiliza.

1. Acesse a sua conta de armazenamento e depois acesse Access Control (IAM).
2. Selecione Add > Add role assignment.
3. Pesquise o service principal que você criou na etapa 4 pelo nome.
4. Atribua as seguintes funções integradas:
   • Storage Blob Data Reader: permite que o CDI leia os arquivos no seu contêiner.
   • Storage Queue Data Reader: permite que o CDI leia a fila em si, para que ele possa encontrar a fila que você nomeou na sincronização e verificar as propriedades dela.
   • Storage Queue Data Message Processor: permite que o CDI visualize, recupere e exclua mensagens na sua fila.

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

Nota

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

Configurando a Ingestão de Dados na Nuvem na Braze

1. Na Braze, acesse Data Settings > Cloud Data Ingestion > Sources, selecione Add data source e depois selecione Azure Blob.

2. Preencha os campos de Azure Blob Connection Details:
   • Credentials: Tenant ID, Principal ID e Client Secret
   • Configuration: Storage account e Container

3. Selecione Test connection e depois selecione Connect to Source.
4. Crie uma sincronização. Acesse Data Settings > Cloud Data Ingestion > Syncs e selecione Create data sync.
5. Em Configurations, escolha um nome para a sincronização, selecione a sua fonte Azure Blob e selecione um Data Type (como User Attributes, Custom Events, Purchase Events, Catalog ou Delete Users).
6. Em Data definition, especifique o seguinte:
   • Storage queue name: a fila que você criou na Etapa 2. Cada sincronização precisa da sua própria fila (consulte Sincronizando uma pasta em um contêiner compartilhado).
   • Folder path (Optional): um prefixo de caminho dentro do contêiner

7. Selecione Preview and validate para confirmar que o 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 não fica ativa até que a conexão seja validada com sucesso.
8. Em Notifications, adicione e-mails de contato para notificações de erros.
9. Schedule não tem opções para sincronizações de armazenamento de arquivos. As sincronizações do Azure Blob Storage são orientadas a eventos, portanto o CDI ingere novos arquivos à medida que são enviados.
10. Revise o Summary e selecione Create sync.

Sincronizando 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 outra sincronização já usa, o CDI sinaliza e faz um link para a sincronização existente.

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

1. Crie uma fila para essa pasta, conforme a Etapa 2.
2. Crie uma assinatura de evento que envie os eventos de Blob Created do contêiner para essa fila, conforme a Etapa 3.
3. Ao criar a sincronização na Braze, insira o Storage queue name dessa pasta e defina Folder path (Optional) com o prefixo da pasta, como attributes/. O CDI só ingere arquivos cujo caminho começa com esse prefixo.

Formatos de arquivo obrigatórios

Os formatos de arquivo obrigatórios são os mesmos para Amazon S3, Google Cloud Storage e Azure Blob Storage. A ingestão de dados na nuvem aceita arquivos JSON, CSV e Parquet. As colunas obrigatórias dependem do tipo de dado:

• Dados de usuários (atributos, eventos personalizados, eventos de compra) usam identificadores de usuário e uma carga útil
• Dados de catálogo usam identificadores de catálogo

Se você estiver usando armazenamento de arquivos para dados de catálogo, use esta página junto com Sincronizar e excluir dados de catálogo para requisitos e comportamentos específicos de catálogo.

A Braze não impõe requisitos adicionais de nome de arquivo além dos impostos pelo seu provedor de armazenamento de arquivos. Os nomes de arquivo devem ser únicos. Adicionar um carimbo de data/hora ajuda a garantir a exclusividade.

Para exemplos de todos os tipos de arquivo compatíveis (atributos, eventos personalizados, compras, catálogos e exclusões de usuários), consulte os arquivos de exemplo em braze-examples.

Identificadores de usuário

Para sincronizações de dados de usuários (atributos, eventos personalizados, eventos de compra), cada linha no seu arquivo de origem requer exatamente um identificador de usuário e uma coluna PAYLOAD. Um arquivo de origem pode conter linhas com tipos de identificadores diferentes, mas cada linha individual deve usar apenas um.

Além de um identificador, cada linha deve incluir uma coluna PAYLOAD contendo uma string JSON dos campos que você deseja sincronizar com o usuário na Braze.

Nota

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

Identificadores de catálogo

Para sincronizações de catálogo, seu arquivo de origem deve conter as colunas a seguir. Arquivos de catálogo usam identificadores diferentes dos arquivos de dados de usuários.

Exemplos

• json attributes
• json custom events
• json purchase events
• csv attributes
• csv catalogs

1
2
3
4
5
6
7

{"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\"}"}
{"external_id":"s3-qa-3","payload":"{\"name\": \"5P44M\", \"age\": 15, \"subscriber\": true, \"retention\": {\"previous_purchases\": 7, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600838\"}"}
{"external_id":"s3-qa-4","payload":"{\"name\": \"WMYS7\", \"age\": 11, \"subscriber\": true, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600844\"}"}
{"external_id":"s3-qa-5","payload":"{\"name\": \"KCBLK\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 11, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600850\"}"}
{"external_id":"s3-qa-6","payload":"{\"name\": \"T93MJ\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 10, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600856\"}"}

Importante

Cada linha no seu arquivo de origem deve conter JSON válido, ou o arquivo será ignorado.

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

Cada linha no seu arquivo de origem deve conter JSON válido, ou o arquivo será ignorado.

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

Cada linha no seu arquivo de origem deve conter JSON válido, ou o arquivo será ignorado.

1
2
3
4

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""}"
s3-qa-load-2-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""EP1U0"", ""age"": 99, ""subscriber"": false, ""retention"": {""previous_purchases"": 23, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598822""}"

1
2
3

ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

Inclua uma coluna opcional DELETED. Quando DELETED é true, o item de catálogo correspondente é removido do catálogo na Braze. Para a lista completa de colunas obrigatórias, consulte Identificadores de catálogo. Para o comportamento de exclusão, consulte Excluindo itens de catálogo. Para um fluxo de ponta a ponta de configuração de catálogo (incluindo a criação do catálogo de destino e o comportamento de sincronização), consulte Sincronizar e excluir dados de catálogo.

Excluindo dados

A ingestão de dados na nuvem para armazenamento de arquivos permite excluir usuários e itens de catálogo por meio de uploads de arquivos. Use sincronizações e formatos de arquivo separados para cada um.

• Excluindo usuários – Crie uma sincronização com o tipo de dados Delete Users e faça upload de arquivos que contenham apenas identificadores de usuários (sem carga útil).
• Excluindo itens de catálogo – Use sua sincronização de catálogo existente e adicione uma coluna deleted (ou DELETED) para marcar itens para remoção.

Excluindo usuários

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

1. Crie uma nova sincronização de ingestão de dados na nuvem (mesma configuração usada para outras sincronizações).
2. Ao configurar a sincronização na Braze, defina Data Type como Delete Users.
3. Faça upload de arquivos no seu bucket de origem que contenham apenas colunas de identificadores de usuários. Não inclua uma coluna PAYLOAD — a sincronização falha se a carga útil estiver presente, para evitar exclusões acidentais.

Cada linha no arquivo deve identificar exatamente um usuário usando um dos seguintes:

Importante

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

Exemplo – JSON (exclusão de usuários):

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

Exemplo – CSV (exclusão de usuários):

1
2
3

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

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

Excluindo itens de 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 de catálogo (tipo de dados Catalogs).
2. Nos seus arquivos CSV ou JSON, adicione uma coluna opcional deleted (ou DELETED).
3. Defina deleted como true para qualquer item de catálogo que você deseja remover do catálogo na Braze.

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

Exemplo – JSON (exclusão de item de catálogo):

{"id":"85","payload":"{\"product_name\": \"Product 85\", \"price\": 85.85}"}
{"id":"1","payload":"{\"product_name\": \"Product 1\", \"price\": 1.01}","deleted":true}

Exemplo – CSV (exclusão de item de catálogo):

1
2
3

ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

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 o comportamento completo de sincronização e exclusão de catálogos, consulte Sincronizar e excluir dados de catálogo.

Coisas para saber

• Os arquivos adicionados ao bucket ou contêiner de origem não devem exceder 512 MB. Esse limite se aplica ao Amazon S3, Google Cloud Storage e Azure Blob Storage. Arquivos maiores que 512 MB resultam em um erro e não são sincronizados com a Braze. O Azure Blob Storage em si permite arquivos muito maiores, mas o CDI aplica o mesmo limite de 512 MB em todas as fontes de armazenamento de arquivos.
• Embora não haja um limite adicional para o número de linhas por arquivo, recomendamos usar arquivos menores para melhorar a velocidade das suas sincronizações. Por exemplo, um arquivo de 500 MB levaria consideravelmente 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 de arquivos nem entre arquivos. Recomendamos agrupar as atualizações periodicamente se você estiver monitorando possíveis condições de corrida.

Solução de problemas

Upload e processamento de arquivos

O CDI só processa arquivos adicionados após a criação da sincronização. Nesse processo, a Braze verifica se novos arquivos foram adicionados, o que dispara uma nova notificação. Isso inicia uma nova sincronização para processar o novo arquivo. No Amazon S3, a notificação é uma mensagem para o SQS. No Google Cloud Storage, é uma mensagem OBJECT_FINALIZE para o Pub/Sub. No Azure Blob Storage, é um evento Blob Created entregue a uma fila do Azure Storage.

Você pode usar arquivos existentes para validar se a Braze consegue acessar seu bucket e detectar arquivos para ingestão, mas eles não são sincronizados com a Braze. Para que o CDI os processe, você precisa fazer o reenvio (upload) dos arquivos existentes que deseja sincronizar para o bucket de origem.

Tratamento de erros inesperados em arquivos (Amazon S3)

Se você está observando um número elevado de erros ou arquivos com falha, pode ser que outro processo esteja adicionando arquivos ao bucket S3 em uma pasta diferente da pasta de destino do CDI.

Quando arquivos são enviados ao bucket de origem, mas não na pasta de origem, o CDI processa a notificação do SQS, mas não executa nenhuma ação sobre o arquivo. Por isso, esse comportamento pode aparecer como um erro.

Se o problema estiver relacionado a notificações do S3 ou a permissões de destino do SQS (por exemplo, erros de validação de destino), consulte a documentação da AWS:

• Enabling and configuring event notifications using the Amazon S3 console
• Granting permissions to publish event notification messages to a destination
• Troubleshooting issues in Amazon SQS

Tratamento de erros inesperados em arquivos (Google Cloud Storage)

Assim como no Amazon S3, o CDI só processa arquivos enviados após a criação da sincronização. Cada novo objeto dispara uma mensagem OBJECT_FINALIZE para o tópico do Pub/Sub. Para ingerir arquivos que já existem no bucket, faça o reenvio deles.

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

• A notificação do bucket existe. Liste as notificações do bucket com gcloud storage buckets notifications list gs://YOUR-BUCKET-NAME.
• O agente de serviço do Cloud Storage possui roles/pubsub.publisher no tópico.
• A conta de serviço da Braze tem permissão de consumo na assinatura (pubsub.subscriptions.consume, atribuída por meio do papel personalizado ou roles/pubsub.subscriber).
• A assinatura não tem uma fila de mensagens mortas (dead-letter queue) configurada. A Braze não oferece suporte a filas de mensagens mortas para assinaturas do Cloud Data Ingestion.

Para saber mais, consulte Pub/Sub notifications for Cloud Storage na documentação do Google Cloud.

Tratamento de erros inesperados em arquivos (Azure Blob Storage)

Assim como no Amazon S3 e no Google Cloud Storage, o CDI só processa arquivos enviados após a criação da sincronização. Cada novo blob dispara um evento Blob Created para a sua fila. Para ingerir arquivos que já existem no container, faça o reenvio deles.

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

• A assinatura de evento existe na conta de armazenamento e está filtrada para Blob Created.
• A assinatura de evento usa Event Grid Schema. O CDI não consegue ler eventos entregues em outro esquema.
• O endpoint da assinatura de evento aponta para a fila configurada na sincronização, e não para uma fila diferente.
• O service principal da Braze possui Storage Blob Data Reader, Storage Queue Data Reader e Storage Queue Data Message Processor na conta de armazenamento.
• O client secret do service principal não expirou. O Azure aplica um vencimento aos client secrets, e um secret expirado interrompe a sincronização.

Para saber mais, consulte Azure Blob Storage as an Event Grid source na documentação da Microsoft.