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 ou Google Cloud 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 a partir de uma assinatura Pub/Sub para ingerir o novo arquivo.

A Ingestão de Dados na 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

Configuração da 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

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 exclusivo 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 de IAM e atribua-a a uma função de IAM para integrar 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.

Configuração da Ingestão de Dados na Nuvem na AWS

Etapa 1: Criar um bucket de origem

Crie um bucket S3 de uso geral com configurações padrão na sua conta AWS. Buckets S3 podem ser reutilizados em 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 controle de versão do bucket
• Criptografia SSE-S3
  • SSE-S3 é o único tipo de criptografia do lado do servidor suportado. A criptografia do Amazon KMS não é suportada.

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

Etapa 2: Criar fila SQS

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

Uma fila SQS deve ser única globalmente (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 esta SQS na mesma região em que você criou o bucket.

Anote o ARN e o URL da fila SQS — você precisará deles com frequência durante esta configuração.

Etapa 3: Configurar a política de acesso

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

Anexe a seguinte declaração à política de acesso da fila, tomando cuidado para substituir YOUR-BUCKET-NAME-HERE pelo nome do bucket, YOUR-SQS-ARN pelo ARN da fila SQS e YOUR-AWS-ACCOUNT-ID pelo ID da conta da 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 direcionamento se quiser que apenas um subconjunto de arquivos seja ingerido pela Braze.
3. Em Destination, selecione SQS queue e forneça o ARN da 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 no bucket, pode 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 fará com que todos os arquivos sejam ingeridos.

Etapa 5: Criar uma política de IAM

Crie uma política de IAM para permitir que a Braze interaja com 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, em seguida, selecione Create Policy.
   
   
   
   

2. Abra a guia JSON e insira o seguinte trecho de código na seção Policy Document, tomando o cuidado de substituir YOUR-BUCKET-NAME-HERE pelo nome do bucket e YOUR-SQS-ARN-HERE pelo nome da fila do 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 de IAM

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

1. Na mesma seção de IAM do console em que criou a política de IAM, acesse Roles > Create Role.

2. Na AWS, selecione Another AWS Account como o tipo de seletor de entidade confiável. Forneça seu ID de conta da Braze. Marque a caixa de seleção Require external ID.
3. Na Braze, acesse Configurações de dados > Ingestão de Dados na Nuvem > 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. Procure a política na barra de pesquisa e marque a caixa de seleção ao lado da política para anexá-la. Selecione Next quando terminar.

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.

Configuração da Ingestão de Dados na Nuvem na Braze

1. Primeiro, crie uma nova fonte no dashboard da Braze. Acesse Configurações de dados > Ingestão de Dados na Nuvem > Sources, selecione Add data source e, em seguida, 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 pode acessar 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 Configurações de dados > Ingestão de Dados na Nuvem > 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 único para cada nova integração)
   • Caminho da pasta (opcional, deve ser único entre sincronizações em um espaço de trabalho)
2. Selecione um tipo de dados e selecione Test Connection para confirmar que a Braze pode 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-mail(s) de contato para notificações caso a sincronização seja interrompida por problemas de acesso ou permissões. Opcionalmente, ative notificações para erros em nível de usuário e sincronizações bem-sucedidas.
4. Crie a sincronização.

A integração requer os seguintes recursos:

• Um bucket do 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 exclusivos.
Bucket do 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 do Cloud Storage.
Assinatura Pub/Sub	Uma assinatura se conecta a um tópico e entrega suas mensagens. 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 seu bucket e sua assinatura. Você faz upload da chave JSON dela na Braze.
Função IAM	Uma função de Identity and Access Management (IAM) é uma coleção de permissões que você atribui à conta de serviço no seu bucket e na sua assinatura.

Configuração da Ingestão de Dados na Nuvem no Google Cloud

Etapa 1: Criar um bucket do 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 em nível de 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 mensagens mortas (dead-letter queue) nesta assinatura. A Braze não oferece suporte a filas de mensagens mortas 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 espaços reservados nestes 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 do 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 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: 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]

Configuração da Ingestão de Dados na Nuvem na Braze

1. Na Braze, acesse Configurações de dados > Ingestão de Dados na Nuvem > Sources, selecione Add data source e, em seguida, 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, em seguida, selecione Connect to Source.
4. Crie uma sincronização. Acesse Configurações de dados > Ingestão de Dados na Nuvem > 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, em seguida, selecione Next.
5. Na etapa Data definition, selecione 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 pode acessar a assinatura e listar os arquivos disponíveis para ingestão. Um teste bem-sucedido listará os arquivos existentes no bucket, mas esses arquivos não serão sincronizados automaticamente.
7. Adicione e-mail(s) de contato para notificações de erros. As sincronizações do Google Cloud Storage são orientadas por eventos, portanto nenhum cronograma é necessário — 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 sincronizações em um espaço de trabalho para múltiplas sincronizações compartilhando o mesmo bucket de origem. Assim como na Etapa 2, não configure uma fila de mensagens mortas (dead-letter queue) 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 listará e ingerirá apenas objetos cujo caminho comece com esse prefixo.

2. Crie um tópico dedicado e uma notificação com escopo de prefixo para essa pasta, 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 a 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.

Formatos de arquivo obrigatórios

Os formatos de arquivo obrigatórios são os mesmos para Amazon S3 e Google Cloud Storage. A ingestão de dados na nuvem aceita 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 do que é exigido 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 aceitos (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 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 aceita 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, o item do 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 do 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), 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 tipo.

• 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 uma das seguintes opções:

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 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.

Informações importantes

• Os arquivos adicionados ao bucket de origem não devem exceder 512 MB. Esse limite se aplica tanto ao Amazon S3 quanto ao Google Cloud Storage. Arquivos maiores que 512 MB resultam em erro e não são sincronizados com a Braze.
• Embora não haja 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

A 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. Para o Amazon S3, a notificação é uma mensagem para o SQS. Para o Google Cloud Storage, é uma mensagem OBJECT_FINALIZE para o Pub/Sub.

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 a CDI os processe, você precisa fazer o re-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 alto de erros ou arquivos com falha, pode haver outro processo adicionando arquivos ao bucket S3 em uma pasta diferente da pasta de destino da CDI.

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

Se o seu problema está 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:

• Ativando 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 o Amazon S3, a CDI só processa arquivos enviados após a criação da sincronização. Cada novo objeto dispara uma mensagem OBJECT_FINALIZE para o seu tópico Pub/Sub. Para ingerir arquivos que já existem no bucket, faça o re-upload 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 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 Pub/Sub para Cloud Storage na documentação do Google Cloud.