Integrações de armazenamento de arquivos

Esta página aborda como configurar o suporte da Ingestão de Dados na Nuvem e sincronizar dados relevantes do S3 para a Braze.

Esta página mostra as etapas de sincronização e origem que estão atualmente em Acesso Antecipado (EA). Para as etapas da experiência geralmente disponível, expanda Experiência de disponibilidade geral abaixo.

Como funciona

Você pode usar a Ingestão de Dados na Nuvem (CDI) para S3 para integrar diretamente um ou mais buckets S3 na sua conta AWS com a Braze. Quando novos arquivos são publicados no S3, uma mensagem é postada no SQS, e a Ingestão de Dados na Nuvem da Braze recebe esses novos arquivos.

A Ingestão de Dados na Nuvem suporta o seguinte:

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

Pré-requisitos

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

Primeiro, vamos definir os termos usados durante esta tarefa.

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

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 Opções avançadas.

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.

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 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 5 à 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 origem no dashboard da Braze. Acesse Data Settings > Cloud Data Ingestion > Sources, selecione Add data source e, em seguida, selecione Amazon S3.
2. Escolha um nome para sua origem e insira as informações do processo de configuração da AWS para criar uma nova origem. Especifique o seguinte:

• ARN da função
• ID externo
• 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 Data Settings > Cloud Data Ingestion > Syncs e selecione Create data sync.

5. Escolha um nome para sua sincronização. Em seguida, selecione qualquer origem S3 ativa e insira sua tabela de origem para a sincronização. Selecione um tipo de dado 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 exclusivo 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 dado 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 se a sincronização for interrompida devido a problemas de acesso ou permissões. Opcionalmente, ative as notificações para erros no nível do usuário e sucessos de sincronização.
4. Crie a sincronização.

Formatos de arquivo necessários

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

A Braze não impõe requisitos adicionais de nome de arquivo além do que é imposto pela AWS. Os nomes dos arquivos devem ser únicos. Adicionar um timestamp ajuda a garantir a exclusividade.

Para exemplos de todos os tipos de arquivo suportados (atributos, eventos personalizados, compras, catálogos e exclusões de usuários), consulte os arquivos de amostra 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.

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

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

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

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

Excluindo dados

A Ingestão de Dados na Nuvem para S3 suporta a exclusão de usuários e itens do 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 dado Delete Users e faça upload de arquivos que contenham apenas identificadores de usuários (sem carga útil).
• Excluindo itens do 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ários na Braze usando arquivos no S3:

1. Crie uma nova sincronização de Ingestão de Dados na Nuvem (mesma configuração da AWS e da Braze que para outras sincronizações).
2. Ao configurar a sincronização na Braze, defina Data Type como Delete Users.
3. Faça upload de arquivos para seu bucket S3 que contenham apenas colunas de identificador de usuário. 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:

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 novos arquivos no bucket e exclui os perfis de usuário correspondentes.

Excluindo itens do catálogo

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

1. Use a mesma sincronização S3 que você usa para sincronizar dados do catálogo (tipo de dado Catalogs).
2. Nos seus arquivos CSV ou JSON, adicione uma coluna opcional deleted (ou DELETED).
3. Defina deleted como true para qualquer item do 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 do 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 do 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, linhas com deleted: true fazem com que o item do catálogo correspondente seja excluído na Braze. Para o comportamento completo de sincronização e exclusão do catálogo, consulte Sincronizar e excluir dados do catálogo.

Informações importantes

• Os arquivos adicionados ao bucket de origem S3 não devem exceder 512 MB. Arquivos maiores que 512 MB resultarão em um erro e não serão sincronizados com a Braze.
• Embora não haja limite adicional no 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 no número de arquivos enviados em um determinado período.
• A ordenação não é suportada dentro ou entre arquivos. 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 só processará arquivos que forem adicionados após a criação da sincronização. Nesse processo, a Braze procura novos arquivos sendo adicionados, o que aciona uma nova mensagem para o SQS. Isso inicia uma nova sincronização para processar o novo arquivo.

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ê deve fazer upload novamente para o S3 de quaisquer arquivos existentes que deseja sincronizar.

Tratando erros inesperados de arquivos

Se você estiver observando um alto 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 arquivos são enviados para o bucket de origem, mas não na pasta de origem, o CDI processará a notificação do SQS, mas não tomará nenhuma ação sobre o arquivo, então isso pode aparecer como um erro.