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 em 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 em 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 a partir de uma inscrição Pub/Sub para ingerir o novo arquivo.
• Azure Blob Storage: Quando novos arquivos são criados no contêiner, uma inscrição 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 em Nuvem é compatível com o seguinte:

• 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)	O 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)	O 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 cuja chave JSON 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. Você faz upload da chave JSON dessa conta na Braze.
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.

Alternativamente, 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 deixar o Google criar uma assinatura padrão ou criar uma separadamente. Em seguida, crie uma assinatura pull nesse tópico.

Alternativamente, 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 o 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 de posição 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. Encontre-o no Dashboard do console do Google Cloud ou execute 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.

Alternativamente, 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 a 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: Criar uma chave JSON

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

Alternativamente, 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
   • Service account JSON key: faça upload do arquivo de chave da etapa 6 e dê um nome à credencial

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 duas 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 tem 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 informe 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 tem um tópico do sistema, insira um nome para criar um. Se já existir, 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 apenas como Blob Created. O Blob Deleted também é selecionado por padrão, então 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 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: 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 dados 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

O registro de um aplicativo requer permissão para criar registros de aplicativo no Microsoft Entra ID. Se você não tem essa permissão, peça a um administrador do Entra para concluir essa 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 expirem para manter o fluxo de dados para a Braze.

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

Etapa 5: Atribuir permissões ao service principal

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

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 Message Processor: permite que o CDI visualize, recupere e exclua mensagens da sua fila.

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

Nota

Se Add role assignment estiver desabilitado, 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 essa 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 suporta arquivos JSON, CSV e Parquet. As colunas obrigatórias dependem do tipo de dados:

• 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 exigidos pelo seu provedor de armazenamento de arquivos. Os nomes de arquivo devem ser únicos. Adicionar um timestamp ajuda a garantir a unicidade.

Para exemplos de todos os tipos de arquivo suportados (atributos, eventos personalizados, compras, catálogos e exclusões de usuários), veja 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 diferentes tipos de identificadores, 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 suportada para sincronizações de armazenamento de arquivos.

Identificadores de catálogo

Para sincronizações de catálogo, seu arquivo de origem deve conter as seguintes colunas. 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, caso contrário 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, caso contrário 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, caso contrário 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 DELETED opcional. Quando DELETED é true, esse item de catálogo é removido do catálogo na Braze. Para a lista completa de colunas obrigatórias, veja Identificadores de catálogo. Para o comportamento de exclusão, veja Excluindo itens de catálogo. Para um fluxo de configuração de catálogo de ponta a ponta (incluindo a criação do catálogo de destino e o comportamento de sincronização), veja 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 arquivo. Use sincronizações e formatos de arquivo separados para cada caso.

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

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 (a 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 o upload de arquivos no seu bucket de origem que contenham apenas colunas de identificadores de usuário. Não inclua uma coluna PAYLOAD — a sincronização falhará se a carga útil estiver presente, para evitar exclusões acidentais.

Cada linha do 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ê pretende 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 utilizada 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 as 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.

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, Google Cloud Storage e Azure Blob Storage. Arquivos maiores que 512 MB resultam em 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 dos arquivos nem entre eles. Recomendamos agrupar atualizações periodicamente se você estiver monitorando possíveis condições de corrida.

Solução de problemas

Upload e processamento de arquivos

O CDI processa apenas arquivos adicionados após a criação da sincronização. Nesse processo, a Braze busca novos arquivos 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 upload novamente no bucket de origem de todos os arquivos existentes que deseja sincronizar.

Tratamento de erros inesperados em arquivos (Amazon S3)

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

Quando os arquivos são enviados para o bucket de origem, mas não para a pasta de origem, o CDI processa a notificação do SQS, mas não executa nenhuma ação no arquivo, de modo que isso pode aparecer como um erro.

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

• Habilitando e configurando notificações de eventos usando o console do Amazon S3
• Concedendo permissões para publicar mensagens de notificação de eventos em um destino
• Solução de problemas no Amazon SQS

Tratamento de erros inesperados em arquivos (Google Cloud Storage)

Assim como no Amazon S3, o CDI processa apenas 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 upload novamente.

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 tem roles/pubsub.publisher no tópico.
• A conta de serviço da Braze tem permissão de consumo na inscrição (pubsub.subscriptions.consume, atribuída por meio da função personalizada ou roles/pubsub.subscriber).
• A inscrição não tem uma fila de mensagens mortas configurada. A Braze não oferece suporte a filas de mensagens mortas para inscrições de Cloud Data Ingestion.

Para saber mais, consulte Notificações do Pub/Sub para o 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 processa apenas 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 contêiner, faça o upload novamente.

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

• A inscrição de evento existe na conta de armazenamento e está filtrada para Blob Created.
• A inscrição de evento usa Event Grid Schema. O CDI não consegue ler eventos entregues em outro esquema.
• O endpoint da inscrição de evento aponta para a fila configurada na sincronização, e não para uma fila diferente.
• A entidade de serviço da Braze tem Storage Blob Data Reader e Storage Queue Data Message Processor na conta de armazenamento.
• O segredo do cliente da entidade de serviço não expirou. O Azure aplica um vencimento nos segredos do cliente, e um segredo expirado interrompe a sincronização.

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