Ingestão de dados na nuvem para Google Cloud Storage

Esta página reúne tudo o que você precisa para sincronizar dados do Google Cloud Storage (GCS) com a Braze usando a ingestão de dados na nuvem (CDI). Ela mostra quais recursos do Google Cloud criar, como conectar a fonte e criar uma sincronização na Braze, qual é o formato de arquivo para cada tipo de dado e como resolver problemas específicos do GCS.

Como funciona

As integrações com o Google Cloud Storage são orientadas a eventos, e não agendadas. Quando novos arquivos são finalizados no bucket, o GCS publica uma notificação OBJECT_FINALIZE em um tópico do Pub/Sub. A Braze consome essas notificações a partir de uma inscrição do Pub/Sub para ingerir o novo arquivo.

A integração exige os seguintes recursos:

• Um bucket do Cloud Storage para armazenar os dados
• Um tópico e uma inscrição do Pub/Sub para notificações de novos arquivos
• Uma conta de serviço que a Braze acessa por meio de um dos métodos de autenticação compatíveis

Definições do GCP

Configurar a 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ê vai precisar deles ao configurar a fonte na Braze. A Braze recomenda ativar o acesso uniforme no nível do bucket para que as permissões sejam gerenciadas pelo IAM.

Etapa 2: Criar um tópico e uma inscrição do Pub/Sub

No console do Google Cloud, acesse Pub/Sub > Topics > Create topic. Você pode deixar o Google criar uma inscrição padrão ou criar uma separadamente. Depois, crie uma inscrição do tipo pull nesse tópico.

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

Aviso

Não configure uma fila de mensagens inativas (dead-letter queue) nesta inscrição. A Braze não oferece suporte a filas de mensagens inativas em inscrições da ingestão de dados na nuvem. Para saber mais, consulte Tópicos de mensagens inativas na documentação do Google Cloud.

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

Importante

Não é possível criar uma notificação do Cloud Storage para o Pub/Sub no console do Google Cloud. Você precisa usar o gcloud (mostrado aqui), o Terraform ou a API JSON. Para saber mais, consulte Configurar notificações do Pub/Sub para o 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. Depois, 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 YOUR-PROJECT-ID, YOUR-BUCKET-NAME e YOUR-TOPIC pelos seus próprios valores. YOUR-PROJECT-NUMBER é o identificador numérico no endereço de e-mail do agente de serviço, que é diferente do ID do projeto. Você encontra esse número no Dashboard do console do Google Cloud ou executando 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. Este exemplo usa braze-cdi-gcs como nome da conta.

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 inscrição. Você pode atribuí-las com um papel personalizado ou com papéis predefinidos.

Papel personalizado: Crie um papel personalizado com exatamente essas permissões e vincule-o ao bucket e à inscrição:

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"

Papéis predefinidos: Em vez de um papel personalizado, atribua roles/storage.objectViewer e roles/storage.legacyBucketReader no bucket, e roles/pubsub.subscriber na inscrição. O papel objectViewer fornece storage.objects.get e storage.objects.list, e o legacyBucketReader fornece storage.buckets.get.

Etapa 6: Configurar a autenticação

A Braze pode acessar a conta de serviço com qualquer um dos seguintes métodos de autenticação:

Workload Identity Federation

Com o Workload Identity Federation (WIF), a Braze se autentica no Google Cloud com uma identidade de curta duração do próprio ambiente AWS e, em seguida, assume a identidade da conta de serviço que você criou para a Braze. Você configura seu projeto para confiar nessa identidade apenas para o seu espaço de trabalho. Não é necessário criar nem compartilhar uma chave de conta de serviço.

A configuração do WIF é feita uma vez por projeto do Google Cloud. Uma credencial WIF atende tanto a fontes do Google Cloud Storage quanto do BigQuery. Se você já concluiu essas etapas para uma fonte do BigQuery, conceda à conta de serviço existente as permissões para esta fonte e pule o restante desta seção.

Pré-requisitos

Para concluir essas etapas no console do Google Cloud, você precisa de permissão para criar pools de identidade de carga de trabalho e para gerenciar políticas do Identity and Access Management (IAM) na conta de serviço e nos seus dados. Por exemplo, você pode usar as funções Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) e Service Account Admin (roles/iam.serviceAccountAdmin).

Confie apenas no principal do seu espaço de trabalho

Aviso

Conceda acesso ao Amazon Resource Name (ARN) completo do principal da Braze que aparece no seu formulário de credencial. Não conceda acesso à função AWS nem à conta AWS da Braze. Uma concessão no nível da função ou da conta permite que outros clientes da Braze leiam seus dados.

Todos os espaços de trabalho da Braze na mesma instância da Braze apresentam a mesma função AWS. Apenas o nome da sessão no final do ARN do principal, que é o ID do seu espaço de trabalho, é exclusivo para você.

O mapeamento de atributos padrão do Google para provedores AWS define aws_role como o ARN da função sem o nome da sessão. Isso significa que conceder acesso a identidades que correspondem a um valor de aws_role, como principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARN, faz com que você confie em todos os espaços de trabalho da Braze na sua instância, incluindo o seu.

Para manter seus dados restritos ao seu espaço de trabalho:

• Conceda acesso apenas a identidades cujo subject seja o ARN completo do seu principal da Braze. Esse é o principal principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN.
• Não conceda acesso a All identities in the pool nem a identidades filtradas por aws_role ou account.
• Não escreva uma condição de atributo que verifique apenas a conta ou a função AWS.
• Mantenha o mapeamento de atributos padrão para google.subject, que é assertion.arn.

O ARN do principal da Braze é diferente para cada espaço de trabalho e instância da Braze. Além disso, a Braze usa uma função AWS separada para fontes do Google em relação a outras fontes, como o Snowflake. Sempre copie o valor de um formulário de credencial do BigQuery ou do Google Cloud Storage no espaço de trabalho que você está conectando.

Copie o ARN do principal da Braze

Na Braze, comece a criar sua fonte do Google Cloud Storage e selecione Workload Identity Federation como método de autenticação. Copie o valor da etapa 1 do formulário de credencial, Copy the Braze principal ARN, e mantenha o formulário aberto.

Se o campo mostrar Unavailable, o WIF não está disponível para sua instância da Braze. Nesse caso, use uma chave de conta de serviço.

Ative as APIs necessárias

No console do Google Cloud, acesse APIs & Services > Library e ative as seguintes APIs para o seu projeto:

• IAM Service Account Credentials API
• Security Token Service API
• Identity and Access Management (IAM) API

Crie o pool de identidade de carga de trabalho e o provedor

1. Acesse IAM & Admin > Workload Identity Federation e selecione Create pool.
2. Insira um nome para o pool, como “Braze CDI”. Anote o Pool ID e selecione Continue.
3. Em Select a provider, selecione AWS.
4. Insira um nome para o provedor, como “Braze AWS”, e anote o Provider ID.
5. Em AWS account ID, insira o número de 12 dígitos que vem depois de arn:aws:sts:: no ARN do principal da Braze e selecione Continue.
6. Em Configure provider attributes, mantenha o mapeamento padrão, incluindo google.subject = assertion.arn.
7. Selecione Save.

Os IDs do pool e do provedor devem ter de 4 a 32 caracteres, usando letras minúsculas, números e hifens.

Restrinja o provedor ao seu principal (opcional)

Para ter uma camada extra de proteção, adicione uma condição de atributo para que o provedor aceite apenas o principal do seu espaço de trabalho. Assim, o Google rejeita todas as outras identidades na troca de token, antes de verificar qualquer permissão da conta de serviço.

1. No pool, selecione o provedor e, em seguida, selecione Edit.
2. Em Attribute conditions, selecione Add condition.

3. Insira a seguinte condição, substituindo BRAZE_PRINCIPAL_ARN pelo valor completo que você copiou do formulário de credencial:

   
   1
   
    assertion.arn == 'BRAZE_PRINCIPAL_ARN'
   
   

4. Selecione Save.

Essa condição dedica o provedor a um único espaço de trabalho da Braze. Para conectar outro espaço de trabalho, crie um provedor separado para ele ou liste os dois principais, como em assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN'].

Vincule o principal da Braze à conta de serviço

Conceda ao principal do seu espaço de trabalho permissão para assumir a identidade da conta de serviço:

1. Acesse IAM & Admin > Workload Identity Federation e selecione seu pool.
2. Selecione Grant access e, em seguida, selecione Grant access using service account impersonation.
3. Em Service account, selecione a conta de serviço que você criou para a Braze.
4. Em Select principals, selecione Only identities matching the filter.
5. Em Attribute name, selecione subject. Em Attribute value, cole o ARN completo do principal da Braze do formulário de credencial.
6. Selecione Save. Se o Google oferecer o download de um arquivo de configuração da biblioteca de cliente, selecione Dismiss. A Braze não precisa dele.

Isso concede a função Workload Identity User (roles/iam.workloadIdentityUser) na conta de serviço a um principal neste formato:

1

principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN

Para confirmar, abra a conta de serviço e selecione a guia Permissions. A função Workload Identity User deve listar esse principal, terminando com o ARN completo do seu principal da Braze.

Aviso

Não selecione All identities in the pool e não filtre por aws_role. As duas opções correspondem a todos os espaços de trabalho da Braze na sua instância, porque todos compartilham a mesma função AWS. Para obter detalhes, consulte Confie apenas no principal do seu espaço de trabalho.

Conceda essa função apenas na conta de serviço. Uma concessão no nível do projeto permite que o principal assuma a identidade de todas as contas de serviço do projeto.

As alterações no IAM podem levar alguns minutos para entrar em vigor. Se um teste de conexão falhar logo depois de você conceder o acesso, aguarde alguns minutos e tente novamente.

A conta de serviço também precisa de acesso aos seus dados. Confira se você concedeu a ela as permissões para esta fonte. Se você usa uma única credencial para o BigQuery e o Google Cloud Storage, conceda os dois conjuntos de permissões à mesma conta de serviço.

Insira os valores na Braze

Volte ao formulário de credencial da Braze e insira os seguintes valores do console do Google Cloud:

A Braze combina o número do projeto, o ID do pool e o ID do provedor no público (audience), que informa ao Google qual provedor valida a solicitação da Braze. Por padrão, um provedor aceita o próprio nome de recurso como público. Se você definir públicos permitidos personalizados no seu provedor, inclua o nome de recurso completo do provedor.

Como a Braze testa a conexão

Quando você testa a conexão na Braze, ela também verifica se sua configuração confia apenas no seu espaço de trabalho. Durante o teste, a Braze tenta a mesma troca com um nome de sessão de teste composto apenas por zeros, neste formato:

1

assumed-role/cdi-gcs-bigquery-sync-<deployment>/000000000000000000000000

Sua configuração precisa rejeitar essa identidade, seja na troca de token ou quando ela tenta assumir a identidade da sua conta de serviço. Se as duas etapas forem bem-sucedidas, o teste falha, porque sua configuração confia em identidades diferentes do principal do seu espaço de trabalho. Para corrigir isso, consulte Sua configuração confia em identidades além do seu espaço de trabalho.

Se você definiu a condição de atributo opcional, o Google rejeita a identidade de teste na troca de token. Caso contrário, o Google rejeita a identidade de teste quando ela tenta assumir a identidade da sua conta de serviço. Em ambos os casos, o teste é aprovado.

Você pode ver essa tentativa rejeitada nos registros de auditoria do Google Cloud sempre que testar a conexão. Esse comportamento é esperado. A tentativa vem da verificação da Braze e não dá a ninguém acesso aos seus dados.

Não adicione uma condição que rejeite apenas essa sessão de teste. Uma condição assim faz o teste passar enquanto sua configuração continua confiando em outros espaços de trabalho da Braze.

Remova o acesso da Braze

Para impedir que a Braze acesse seus dados, remova a função Workload Identity User do principal da Braze na guia Permissions da conta de serviço ou exclua o provedor.

Configure com a CLI gcloud

Se você preferir a linha de comando, os comandos a seguir ativam as APIs, criam o pool e o provedor e vinculam o principal da Braze à sua conta de serviço. Substitua os valores do primeiro bloco e cole o ARN do principal da Braze exatamente como foi copiado.

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
27
28

PROJECT_ID="YOUR-PROJECT-ID"
POOL_ID="braze-cdi"
PROVIDER_ID="braze-aws"
SA_EMAIL="YOUR-SERVICE-ACCOUNT-EMAIL"
BRAZE_PRINCIPAL_ARN="PASTE-THE-BRAZE-PRINCIPAL-ARN-FROM-YOUR-CREDENTIAL-FORM"

PROJECT_NUMBER="$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')"
BRAZE_AWS_ACCOUNT_ID="$(echo "$BRAZE_PRINCIPAL_ARN" | cut -d: -f5)"

gcloud services enable iam.googleapis.com iamcredentials.googleapis.com sts.googleapis.com \
  --project="$PROJECT_ID"

gcloud iam workload-identity-pools create "$POOL_ID" \
  --project="$PROJECT_ID" --location="global" --display-name="Braze CDI"

gcloud iam workload-identity-pools providers create-aws "$PROVIDER_ID" \
  --project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
  --account-id="$BRAZE_AWS_ACCOUNT_ID"

# Optional: restrict the provider to your principal
gcloud iam workload-identity-pools providers update-aws "$PROVIDER_ID" \
  --project="$PROJECT_ID" --location="global" --workload-identity-pool="$POOL_ID" \
  --attribute-condition="assertion.arn == '${BRAZE_PRINCIPAL_ARN}'"

gcloud iam service-accounts add-iam-policy-binding "$SA_EMAIL" \
  --project="$PROJECT_ID" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principal://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/${POOL_ID}/subject/${BRAZE_PRINCIPAL_ARN}"

Service account key

A Braze faz a autenticação com uma chave JSON da sua conta de serviço. As credenciais de chave de conta de serviço já existentes continuam funcionando, e você não precisa migrá-las.

No console do Google Cloud, abra a conta de serviço, acesse Chaves > Adicionar chave > Criar nova chave e selecione JSON. Baixe o arquivo da chave. Você vai enviá-lo para a Braze ao criar a fonte.

Se preferir, use o gcloud:

1
2

gcloud iam service-accounts keys create braze-cdi-key.json \
  --iam-account=SERVICE_ACCOUNT_EMAIL

Substitua SERVICE_ACCOUNT_EMAIL pelo endereço de e-mail da conta de serviço. Para saber mais, consulte Criar e excluir chaves de conta de serviço.

Configurar a ingestão de dados na nuvem na Braze

1. Na Braze, acesse Configurações de dados > Ingestão de dados na nuvem > Fontes, selecione Adicionar fonte de dados e depois selecione Google Cloud Storage.

2. Preencha os campos da fonte:
   • Bucket: o nome do seu bucket
   • ID do projeto: o ID do seu projeto no GCP
   • Credencial: dê um nome à credencial e selecione o método de autenticação que você configurou na Etapa 6. Para Workload Identity Federation, insira Project number, Workload identity pool ID, Provider ID, and Service account email. Para Service account key, insira JSON key file for the service account.

3. Selecione Testar conexão e depois Conectar à fonte.
4. Crie uma sincronização. Acesse Configurações de dados > Ingestão de dados na nuvem > Sincronizações e selecione Criar sincronização de dados. Escolha um nome para a sincronização e um Tipo de dados (como Atributos do usuário, Eventos personalizados, Eventos de compra, Catálogo ou Excluir usuários) e selecione Próximo.
5. Na etapa Definição de dados, selecione sua fonte do GCS e especifique o seguinte:
   • ID da inscrição do Pub/Sub: o ID da inscrição da etapa 2 (não o tópico)
   • Caminho da pasta (opcional): um prefixo de caminho dentro do bucket (consulte Sincronizar uma pasta em um bucket compartilhado)

6. Selecione Prévia e validação para confirmar que a Braze consegue acessar a inscrição 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 endereços de e-mail de contato para receber notificações de erro. As sincronizações do Google Cloud Storage são orientadas a eventos, então não é necessário definir um cronograma. A Braze ingere os novos arquivos à medida que eles são carregados. Revise o resumo e selecione Criar sincronização.

Sincronizar uma pasta em um bucket compartilhado

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

Importante

Quando várias sincronizações compartilham o mesmo bucket de origem, o caminho da pasta e a inscrição precisam ser exclusivos entre as sincronizações de um espaço de trabalho. Assim como na Etapa 2, não configure uma fila de mensagens inativas em nenhuma dessas inscrições.

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

1. Defina o campo Pasta 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 limitada ao prefixo dessa pasta. Depois, crie uma inscrição 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 inscrição, como 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 o papel personalizado na Etapa 5, use --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs" no lugar.

4. Ao criar a sincronização na Braze, insira o novo ID da inscrição do Pub/Sub e o Caminho da pasta dessa pasta, para que a sincronização ingira somente os arquivos dela.

Formatos de arquivo obrigatórios

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

Nota

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

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

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

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

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

Identificador	Descrição
EXTERNAL_ID	Identifica o usuário que você quer atualizar. Deve corresponder ao valor external_id usado na Braze.
ALIAS_NAME e ALIAS_LABEL	Essas duas colunas criam um objeto de alias de usuário. alias_name deve ser um identificador exclusivo, e alias_label especifica o tipo de alias. Os usuários podem ter vários aliases com rótulos diferentes, mas apenas um alias_name por alias_label.
BRAZE_ID	O identificador de usuário da Braze. Ele é gerado pelo SDK da Braze, e não é possível criar novos usuários usando um ID da Braze pela Ingestão de dados na nuvem. Para criar novos usuários, especifique um ID de usuário externo ou um alias de usuário.
EMAIL	O endereço de e-mail do usuário. Se houver vários perfis com o mesmo endereço de e-mail, o perfil atualizado mais recentemente terá prioridade nas atualizações. Se você incluir e-mail e telefone, a Braze usará o e-mail como identificador principal.
PHONE	O número de telefone do usuário. Se houver vários perfis com o mesmo número de telefone, o perfil atualizado mais recentemente terá prioridade nas atualizações.

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

Exemplo de JSON

1
2
3

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

Exemplo de CSV

1
2
3

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

Importante

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

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

1
2

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

Importante

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

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

1
2

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

Importante

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

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

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

Exemplo de JSON

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

Exemplo de CSV com a coluna DELETED

1
2
3
4

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

Exemplo de CSV sem a coluna DELETED

1
2
3

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

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

Campo	Obrigatório	Descrição
EXTERNAL_ID	Sim, external_id ou alias_name e alias_label	Identifica o usuário que você quer atualizar. Deve corresponder ao valor external_id usado na Braze.
ALIAS_NAME e ALIAS_LABEL	Sim, external_id ou alias_name e alias_label	Essas duas colunas criam um objeto de alias de usuário. alias_name deve ser um identificador exclusivo, e alias_label especifica o tipo de alias. Os usuários podem ter vários aliases com rótulos diferentes, mas apenas um alias_name por alias_label.
PROPERTIES	Sim	String JSON com os campos que ficarão disponíveis como propriedades de personalização no seu Canvas. Deve conter informações específicas do usuário.

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

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

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

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

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

Exemplo de JSON

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

Exemplo de CSV

1
2
3

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

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

Importante

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

Excluir itens do catálogo

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

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

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

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

Informações importantes

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

Solução de problemas

Upload e processamento de arquivos

A CDI só processa arquivos carregados depois que a sincronização é criada. Cada novo objeto dispara uma mensagem OBJECT_FINALIZE para o seu tópico do Pub/Sub. Para ingerir arquivos que já existem no bucket, carregue-os novamente.

Lidar com erros inesperados de arquivos

Se os arquivos não forem 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 pelo papel personalizado ou por roles/pubsub.subscriber).
• A inscrição não tem uma fila de mensagens inativas configurada. A Braze não oferece suporte a filas de mensagens inativas em inscrições da ingestão de dados na nuvem.

Para saber mais, consulte Notificações do Pub/Sub para o Cloud Storage na documentação do Google Cloud.

Sua configuração confia em identidades além do seu espaço de trabalho

Se você usa a Workload Identity Federation, o teste de conexão pode falhar com o seguinte erro:

Your workload identity pool trusts every Braze customer, not only this workspace. Braze authenticated against it with a test identity (000000000000000000000000) that belongs to no Braze workspace, and your Google Cloud project accepted it, so another Braze customer could read this data. Grant the Workload Identity User role on your service account to the full Braze principal shown on the credential screen (principal://…/subject/<full ARN>) rather than to the role (principalSet://…/attribute.aws_role/…); restricting the pool provider’s attribute condition to that same principal works as well. Then test the connection again.

Isso significa que o Google aceitou a identidade de teste da Braze tanto na troca de tokens quanto na simulação da conta de serviço, conforme descrito em Como a Braze testa a conexão. Esse erro geralmente acontece quando a conta de serviço concede acesso a todas as identidades do pool ou a identidades filtradas por aws_role.

Para corrigir esse erro:

1. No console do Google Cloud, abra a conta de serviço e selecione a guia Permissions.
2. Encontre todos os principais com o papel Workload Identity User que começam com principalSet:// e fazem referência ao seu pool. Remova o papel de cada um deles.
3. Confira se o seu principal completo tem o papel, conforme descrito em Vincular o principal da Braze à conta de serviço.
4. Acesse IAM & Admin > IAM e verifique se há concessões do papel Workload Identity User no nível do projeto para o seu pool. Remova-as.
5. Teste a conexão novamente.

Como alternativa, restrinja a condição de atributo do provedor ao seu principal completo, conforme descrito em Restringir o provedor ao seu principal (opcional). Assim, o Google rejeita todas as outras identidades na troca de tokens. Mesmo assim, recomendamos conceder acesso somente ao seu principal completo.

A Braze não conseguiu confirmar que seu pool confia apenas neste espaço de trabalho

Se você usa a Workload Identity Federation, o teste de conexão pode falhar com o seguinte erro:

Braze could not confirm that your workload identity pool trusts only this workspace. The check needs Google to explicitly refuse an identity that is not yours, and this attempt failed for another reason instead. Please try again; if it keeps happening, contact support.

A verificação da Braze descrita em Como a Braze testa a conexão não chegou a um resultado. Por exemplo, um erro de rede ou um erro temporário do Google Cloud interrompeu a verificação. Esse erro não significa que sua configuração é ampla demais. Teste a conexão novamente. Se o erro continuar, entre em contato com o suporte da Braze.

Permissão negada quando a Braze simula a conta de serviço

Se você usa a Workload Identity Federation e o teste de conexão falha com um erro de permissão em iam.serviceAccounts.getAccessToken, verifique o seguinte:

• A guia Permissions da conta de serviço lista o papel Workload Identity User para um principal que termina com o ARN completo do seu principal da Braze, copiado de um formulário de credenciais do BigQuery ou do Google Cloud Storage no mesmo espaço de trabalho.
• A IAM Service Account Credentials API está ativada.
• Você aguardou alguns minutos depois de conceder o acesso.

A troca de tokens é rejeitada

Se você usa a Workload Identity Federation e o teste de conexão falha na troca de tokens do Google Security Token Service, verifique o seguinte:

• O número do projeto, o ID do pool e o ID do provedor que você informou na Braze correspondem à sua configuração do Google Cloud.
• O ID da conta AWS do provedor corresponde ao ID da conta no ARN do principal da Braze.
• Se você definiu uma condição de atributo, ela contém o ARN completo do seu principal, exatamente como foi copiado.
• Se você definiu públicos permitidos personalizados, eles incluem o nome completo do recurso do provedor.
• O pool e o provedor estão ativados.

Erro de objeto de integração incorreto

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

Páginas relacionadas

• Configuração da tabela para colunas obrigatórias e formatação da carga útil
• Melhores práticas para agendamento de sincronizações e eficiência no uso de pontos de dados
• Logs de sincronização e observabilidade para monitorar as execuções de sincronização
• Perguntas frequentes para dúvidas comuns sobre todas as fontes