Ingestão de dados na nuvem para o Google BigQuery

Esta página aborda tudo o que você precisa para sincronizar dados do Google BigQuery com a Braze usando a ingestão de dados na nuvem (CDI): os recursos a criar no Google Cloud, como conectar a fonte e criar uma sincronização na Braze, a tabela de origem para cada tipo de dado e a solução de problemas específica do BigQuery.

Visão geral da configuração

1. Na sua conta do BigQuery, configure as tabelas ou visualizações que você deseja sincronizar com a Braze.
2. Crie uma conta de serviço e permita o acesso aos projetos e conjuntos de dados do BigQuery que contêm os dados que você deseja sincronizar.
3. Configure como a Braze acessa a conta de serviço, usando um dos métodos de autenticação compatíveis.
4. Crie uma nova fonte e uma sincronização no dashboard da Braze.
5. Valide a integração e inicie a sincronização.

Etapa 1: Configure sua tabela de origem

As etapas desta seção criam uma tabela com uma coluna PAYLOAD. Se você planeja mapear colunas com Visual ou escrever uma consulta com SQL na etapa Definição de dados, pode usar uma tabela ou visualização existente. Pule a etapa de criação da tabela e conceda à Braze acesso de leitura às tabelas ou visualizações que você deseja sincronizar. Para comparar as opções, consulte Escolha uma opção de definição de dados.

Você pode dar o nome que quiser ao projeto, ao conjunto de dados e à tabela, mas os nomes das colunas devem corresponder às definições das guias a seguir. Você também pode usar uma visualização ou uma visualização materializada em vez de uma tabela.

Se quiser, configure um novo projeto ou conjunto de dados para armazenar sua tabela de origem:

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Nota

Se você usar uma coluna PAYLOAD, sua tabela ou visualização de origem pode incluir colunas que não estão listadas nas guias a seguir (por exemplo, de auditoria ou hashing). A Braze lê apenas as colunas descritas nessas guias; as outras colunas não são usadas durante as sincronizações da ingestão de dados na nuvem.

Selecione a guia do tipo de dado que você deseja sincronizar.

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

Atributos do usuário, eventos personalizados e eventos de compra usam o mesmo formato de tabela de origem. Apenas o conteúdo de PAYLOAD muda.

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

CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.USERS_ATTRIBUTES_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp,
  --At least one of external_id, alias_name and alias_label, or braze_id is required
  external_id STRING,
  --If using user alias, both alias_name and alias_label are required
  alias_name STRING,
  alias_label STRING,
  --braze_id can only be used to update existing users created through the Braze SDK
  braze_id STRING,
  --If you include both email and phone, email is used as the primary identifier
  email STRING,
  phone STRING,
  payload JSON
);

Nome do campo	Tipo	Modo
UPDATED_AT	TIMESTAMP	REQUIRED
PAYLOAD	JSON	REQUIRED
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE
BRAZE_ID	STRING	NULLABLE
EMAIL	STRING	NULLABLE
PHONE	STRING	NULLABLE

• UPDATED_AT - O horário em que esta linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. Linhas com o carimbo de data/hora exatamente no limite podem ser sincronizadas novamente se novas linhas tiverem esse mesmo carimbo de data/hora.
• Colunas de identificador de usuário - Sua tabela pode conter uma ou mais colunas de identificador de usuário. Cada linha deve conter apenas um identificador (external_id, a combinação de alias_name e alias_label, braze_id, email ou phone). Uma tabela de origem pode ter colunas para um, dois, três, quatro ou todos os cinco tipos de identificador.
  • EXTERNAL_ID - Identifica o usuário que você deseja atualizar. Deve corresponder ao valor de 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. Não é possível criar novos usuários usando um Braze ID por meio da 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 existirem vários perfis com o mesmo endereço de e-mail, o perfil atualizado mais recentemente terá prioridade nas atualizações. Se você incluir tanto o e-mail quanto o telefone, o e-mail será usado como identificador principal.
  • PHONE - O número de telefone do usuário. Se existirem vários perfis com o mesmo número de telefone, o perfil atualizado mais recentemente terá prioridade nas atualizações.
• PAYLOAD - É uma string JSON com os campos que você deseja sincronizar com o usuário na Braze.

Para sincronizações de atributos, o PAYLOAD segue o formato do objeto de atributos do usuário. Você pode incluir atributos personalizados aninhados, arrays de objetos e status de grupos de inscrições. Para ver exemplos de carga útil, consulte Configuração da tabela.

Importante

Particionamento no BigQuery

A CDI oferece suporte a partições no BigQuery. Se você particionar por uma função de UPDATED_AT (por exemplo, com granularidade de dia, semana ou hora, dependendo do tamanho do seu conjunto de dados), o BigQuery consegue reduzir os dados que precisa varrer. Isso melhora a performance e a eficiência em tabelas muito grandes.

Não particione por nenhum outro campo. Teste diferentes configurações para encontrar a melhor opção para os seus dados.

Todas as consultas da CDI filtram por UPDATED_AT, mas esse comportamento pode mudar. Projete o esquema da sua tabela para não exigir que as consultas incluam essa cláusula.

Para saber mais, consulte a documentação de particionamento do BigQuery.

Os eventos personalizados usam a mesma tabela de origem que os atributos do usuário. Crie a tabela mostrada na guia Atributos do usuário e preencha o PAYLOAD com um objeto de eventos.

Para sincronizar eventos, é necessário informar o nome do evento. Formate o campo time como uma string ISO 8601 ou no formato yyyy-MM-dd'T'HH:mm:ss:SSSZ. Se o campo time não estiver presente, a Braze usa o valor da coluna UPDATED_AT como horário do evento. Os demais campos, incluindo app_id e properties, são opcionais.

Você pode sincronizar um evento por linha.

1
2
3
4
5
6
7
8
9

{
    "app_id" : "your-app-id",
    "name" : "rented_movie",
    "time" : "2013-07-16T19:20:45+01:00",
    "properties": {
        "movie": "The Sad Egg",
        "director": "Alex Smith"
    }
}

Os eventos de compra usam a mesma tabela de origem que os atributos do usuário. Crie a tabela mostrada na guia Atributos do usuário e preencha o PAYLOAD com um objeto de compras.

Para sincronizar eventos de compra, é necessário informar product_id, currency e price. Formate o campo opcional time como uma string ISO 8601 ou no formato yyyy-MM-dd'T'HH:mm:ss:SSSZ. Se o campo time não estiver presente, a Braze usa o valor da coluna UPDATED_AT como horário do evento. Os demais campos, incluindo app_id, quantity e properties, são opcionais.

Você pode sincronizar um evento de compra por linha.

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

{
    "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
    "product_id" : "Completed Order",
    "currency" : "USD",
    "price" : 219.98,
    "time" : "2013-07-16T19:20:30+01:00",
    "properties" : {
        "products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99 },
        { "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99 }
        ]
    }
}

Antes de criar uma sincronização de catálogo, crie o catálogo de destino na Braze. Para ver o fluxo completo de catálogos, consulte Sincronizar e excluir dados de catálogo.

1
2
3
4
5
6
7

CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CATALOGS_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp,
  id STRING,
  payload JSON,
  deleted BOOLEAN
);

Nome do campo	Tipo	Modo
UPDATED_AT	TIMESTAMP	REQUIRED
PAYLOAD	JSON	REQUIRED
ID	STRING	REQUIRED
DELETED	BOOLEAN	OPTIONAL

O nome da integração deve ser exatamente igual ao nome do catálogo que você criou na Braze.

A Braze recomenda criar uma visualização a partir dos dados do seu catálogo para que a tabela de origem seja totalmente atualizada a cada sincronização. Por exemplo, se você tiver uma tabela de dados de produtos (product_catalog_1) com product_id e mais três atributos, poderá sincronizar a seguinte visualização:

1
2
3
4
5
6
7
8
9
10
11

CREATE view IF NOT EXISTS BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS (SELECT
    last_updated as UPDATED_AT,
    product_id as ID,
    TO_JSON(
      STRUCT(
      attribute_1,
      attribute_2,
      attribute_3,
      )
    ) as PAYLOAD
  FROM `BRAZE_CLOUD_PRODUCTION.INGESTION.product_catalog_1`);

Os gatilhos do 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 zero-copy.

1
2
3
4
5
6
7
8
9
10

CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CANVAS_TRIGGERS_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp,
  --At least one of external_id or alias_name and alias_label is required
  external_id STRING,
  --If using user alias, both alias_name and alias_label are required
  alias_name STRING,
  alias_label STRING,
  properties JSON
);

Nome do campo	Tipo	Obrigatório?
UPDATED_AT	TIMESTAMP	Sim
PROPERTIES	JSON	Sim
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE

As sincronizações de disparo de Canvas diferem de outras sincronizações de dados de usuários de três maneiras:

• Só há suporte para os identificadores ID externo ou alias de usuário. E-mail e números de telefone não são identificadores compatíveis.
• Só é possível sincronizar usuários que já existem na Braze. Não é possível criar novos usuários.
• PROPERTIES substitui a coluna PAYLOAD. Essa coluna é uma string JSON com os campos que você quer usar como propriedades de entrada no Canvas para personalização.

Sua tabela de disparos de Canvas precisa das seguintes colunas:

• UPDATED_AT - O momento em que essa linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. As linhas com o timestamp exatamente no limite podem ser sincronizadas novamente se novas linhas tiverem esse mesmo timestamp.
• EXTERNAL_ID ou ALIAS_NAME e ALIAS_LABEL como coluna de identificador de usuário. Essas colunas identificam os usuários para os quais você quer disparar o envio de mensagens do Canvas.
  • EXTERNAL_ID - Identifica o usuário que vai entrar no Canvas. Esse valor deve corresponder ao valor de external_id usado na Braze.
  • ALIAS_NAME e ALIAS_LABEL - Essas colunas criam um objeto de alias de usuário. alias_name deve ser um identificador único, 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 - Uma string JSON com os campos que ficarão disponíveis como propriedades de personalização no seu Canvas. Ela deve conter informações específicas do usuário.

Nota

As propriedades não são obrigatórias para todas as linhas ou usuários. No entanto, os valores das propriedades precisam ser uma string JSON válida. Insira uma string vazia {} se não houver propriedades para a linha.

Para começar, selecione o tipo de dado Gatilhos do Canvas ao criar uma nova sincronização.

As tabelas de origem para exclusões de usuários devem incluir um ou mais tipos de identificador de usuário e um carimbo de data/hora UPDATED_AT. Colunas de carga útil não são compatíveis com dados de exclusão de usuários.

• UPDATED_AT - O momento em que esta linha foi atualizada ou adicionada à tabela. A Braze sincroniza as linhas em que UPDATED_AT é posterior ao último valor sincronizado. As linhas que estiverem exatamente no carimbo de data/hora limite podem ser sincronizadas novamente se novas linhas tiverem esse mesmo carimbo de data/hora.
• Colunas de identificador de usuário - Cada linha deve conter apenas um identificador: external_id, a combinação de alias_name e alias_label, ou braze_id. Uma tabela de origem pode conter colunas para um, dois ou todos os três tipos de identificador.
  • EXTERNAL_ID - Identifica o usuário que você deseja atualizar. Deve corresponder ao valor de 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 por meio da ingestão de dados na nuvem. Para criar novos usuários, especifique um ID de usuário externo ou um alias de usuário.

Importante

Não inclua uma coluna PAYLOAD na sua tabela para remoção de usuários. Para evitar a remoção acidental e permanente de usuários, a sincronização falha se uma coluna de carga útil for fornecida na tabela de origem. Quaisquer outras colunas são permitidas, mas são ignoradas pela Braze.

Crie uma tabela com os seguintes campos:

Nome do campo	Tipo	Modo
UPDATED_AT	TIMESTAMP	REQUIRED
EXTERNAL_ID	STRING	NULLABLE
ALIAS_NAME	STRING	NULLABLE
ALIAS_LABEL	STRING	NULLABLE
BRAZE_ID	STRING	NULLABLE

Na página Criar sincronização de importação, defina o Tipo de dado como Excluir usuários para que as ações corretas sejam executadas durante a integração. Para saber mais, consulte Excluir usuários com a ingestão de dados na nuvem.

Aviso

A exclusão de perfis de usuário não pode ser desfeita. A ação de exclusão remove os usuários permanentemente, o que pode causar discrepâncias nos seus dados. Para mais detalhes, consulte Efeitos da exclusão de perfis de usuário.

Etapa 2: Crie uma conta de serviço e conceda permissões

Crie uma conta de serviço no GCP para que a Braze a use para se conectar e ler os dados das suas tabelas. A conta de serviço deve ter as seguintes permissões:

• BigQuery Connection User: Permite que a Braze faça conexões
• BigQuery User: Dá à Braze acesso para executar consultas, ler metadados dos conjuntos de dados e listar tabelas.
• BigQuery Data Viewer: Dá à Braze acesso para visualizar os conjuntos de dados e seu conteúdo.
• BigQuery Job User: Dá à Braze acesso para executar jobs

Etapa 3: Configure 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 BigQuery quanto do Google Cloud Storage. Se você já concluiu essas etapas para uma fonte do Google Cloud Storage, 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 BigQuery 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.

Etapa 4: Permita o acesso dos IPs da Braze

Se você tiver políticas de rede em vigor, precisa conceder à Braze acesso de rede à sua instância do BigQuery. Permita o acesso dos seguintes IPs, de acordo com a região do seu dashboard da Braze.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

Etapa 5: Crie uma nova fonte no dashboard da Braze

No dashboard da Braze, acesse Configurações de dados > Ingestão de dados na nuvem > Fontes, selecione Adicionar fonte de dados e, em seguida, selecione Google BigQuery.

Etapa 5.1: Adicione as informações de conexão do BigQuery e a tabela de origem

Insira um nome para a sua fonte e, em seguida, informe suas credenciais e configurações do BigQuery:

• Em Nome da credencial, insira um rótulo que ajude você a identificar essas credenciais na Braze.
• Para o método de autenticação, selecione o método que você configurou na Etapa 3 e insira as credenciais correspondentes. 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.

Depois, preencha os demais campos de configuração.

Etapa 5.2: Teste a conexão e conecte-se à fonte

Em seguida, selecione Testar conexão. Se der certo, conclua as configurações restantes e clique em Conectar à fonte. Se a conexão falhar, uma mensagem de erro aparece para ajudar a solucionar o problema.

Etapa 6: Crie uma nova sincronização no dashboard da Braze

Acesse Configurações de dados > Ingestão de dados na nuvem > Sincronizações e selecione Criar sincronização de dados.

Configure os detalhes da sincronização e defina seus dados

Insira um nome para a sua sincronização. Depois, selecione uma fonte ativa e um tipo de dado de sincronização. Em seguida, selecione Visual ou Tabela e insira sua tabela de origem, ou selecione SQL para escrever uma consulta SQL personalizada. Por fim, selecione Prévia e validação.

Depois que a validação for concluída com sucesso, aparece uma prévia dos dados. Selecione Próximo: Notificações para continuar. Se a validação falhar, uma mensagem de erro aparece para ajudar a solucionar o problema.

Nota

Você precisa validar a sincronização com sucesso antes de avançar para as próximas etapas. Se precisar fechar a página de criação da sincronização, selecione Salvar como rascunho para manter o trabalho em andamento.

Adicionar preferências de notificação

Insira um ou mais e-mails de contato para receber notificações de erros de sincronização. A Braze usa essas informações de contato para enviar notificações sobre erros de integração, como a perda inesperada de acesso a uma tabela.

Os e-mails de contato recebem apenas notificações de erros globais ou no nível da sincronização, como tabelas ausentes, problemas de permissões e outros. Eles não recebem notificações de problemas no nível da linha. Os erros globais indicam problemas críticos na conexão que impedem a execução das sincronizações.

Esses problemas podem incluir:

• Problemas de conectividade
• Falta de recursos
• Problemas de permissões
• O nível do catálogo está sem espaço (somente sincronizações de catálogo)

Definir o cronograma

Por fim, configure a sincronização como não recorrente ou recorrente.

As sincronizações não recorrentes são executadas somente quando você seleciona Sincronizar agora no dashboard ou chama o endpoint Disparar uma sincronização.

As sincronizações recorrentes podem ser executadas com frequência de até uma vez a cada 5 minutos ou com intervalo de até uma vez por mês. Por padrão, o intervalo mais curto que você pode definir no dashboard é de 15 minutos. Isso ajuda a gerenciar os custos de computação e o volume de solicitações do seu data warehouse. Para sincronizar a cada 5 minutos, entre em contato com o suporte da Braze ou com seu gerente de sucesso do cliente. A Braze agenda as sincronizações recorrentes em UTC.

Nota

Você precisa validar uma integração com sucesso antes que ela possa passar do status Rascunho para Ativo. Se você fechar a página de criação, sua integração é salva, e você pode voltar à página de detalhes para fazer alterações e validá-la.

Execute a sincronização

Depois de ativada, sua sincronização é executada de acordo com o cronograma definido durante a configuração. Se quiser executar a sincronização fora do cronograma ou buscar os dados mais recentes, selecione Sincronizar agora. Essa execução não afeta as próximas sincronizações agendadas. Para iniciar uma sincronização automaticamente quando seus dados forem atualizados, chame o endpoint Disparar uma sincronização a partir do seu pipeline.

Configure integrações ou usuários adicionais (opcional)

Você pode configurar várias integrações com a Braze. Ao criar sincronizações adicionais, você pode reutilizar credenciais existentes se for se conectar à mesma conta do BigQuery.

Se você reutilizar o mesmo usuário em várias integrações, não será possível excluí-lo no dashboard da Braze até que ele seja removido de todas as sincronizações ativas.

Use o BigQuery como fonte conectada

Uma fonte conectada é uma alternativa sem cópia de dados (zero-copy) à sincronização de dados com a Braze. A Braze consulta sua instância do BigQuery diretamente para criar segmentos de CDI, sem copiar os dados subjacentes. Para conhecer os conceitos, as limitações e as implicações de custo, consulte Fontes conectadas.

Etapa 1: Crie uma conta de serviço e conceda permissões

Crie uma conta de serviço no GCP para que a Braze a use para se conectar e ler os dados das suas tabelas. A conta de serviço deve ter as seguintes permissões:

• BigQuery Connection User: Permite que a Braze faça conexões.
• BigQuery User: Dá à Braze acesso para executar consultas, ler metadados dos conjuntos de dados e listar tabelas.
• BigQuery Data Viewer: Dá à Braze acesso para visualizar os conjuntos de dados e seu conteúdo.
• BigQuery Job User: Dá à Braze acesso para executar jobs.
• bigquery.tables.create: Dá à Braze acesso para criar tabelas temporárias durante a atualização de segmentos.

Essa conta de serviço é usada para gerar a lista de tabelas disponíveis nas suas extensões de segmento de CDI e para consultar as tabelas de origem ao criar novos segmentos. Depois que a fonte conectada é criada, a Braze descobre os nomes e as descrições de todas as tabelas disponíveis para o usuário no esquema de origem.

Você pode conceder acesso a todas as tabelas de um conjunto de dados ou conceder privilégios apenas a tabelas específicas. Todas as tabelas às quais a função da Braze tiver acesso ficam disponíveis para consulta na extensão de segmento de CDI.

A permissão create table é necessária para que a Braze possa criar uma tabela com os resultados da consulta da sua extensão de segmento de CDI antes de atualizar o segmento na Braze. A Braze cria uma tabela temporária por segmento, e essa tabela só existe enquanto a Braze está atualizando o segmento.

Depois de criar a conta de serviço e conceder as permissões, configure como a Braze a acessa com um dos métodos da Etapa 3: Configure a autenticação. Se você já configurou a federação de identidade da carga de trabalho (Workload Identity Federation) para esse projeto, pode reutilizá-la. Conceda à conta de serviço existente as permissões desta etapa.

A configuração do acesso de rede é a mesma da Etapa 4.

Etapa 2: Crie a fonte conectada na Braze

Acesse Configurações de dados > Ingestão de dados na nuvem > Fontes conectadas, selecione Adicionar fonte de dados e, em seguida, selecione Google BigQuery.

Em Configurar fonte, informe o seguinte:

• Credenciais: Nome da credencial e os campos do seu método de autenticação. 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.
• Configuração: Projeto e Conjunto de dados

Escolha um nome para a fonte conectada. Esse nome aparece na lista de fontes disponíveis quando você cria uma nova extensão de segmento de CDI.

Configure um tempo máximo de execução para essa fonte. A Braze interrompe automaticamente todas as consultas que excederem esse tempo. O tempo máximo de execução permitido é de 60 minutos; um tempo menor reduz os custos gerados na sua conta do BigQuery. Essa configuração se aplica às consultas executadas por essa fonte, incluindo sincronizações e extensões de segmento de CDI que a utilizam.

Selecione Testar conexão para verificar se a lista de tabelas visíveis para o usuário é a esperada e, em seguida, selecione Concluído. Sua fonte conectada está criada e pronta para uso nas extensões de segmento de CDI.

Você pode configurar várias fontes conectadas com a Braze, mas cada fonte deve se conectar a um conjunto de dados diferente. Ao criar fontes adicionais, você pode reutilizar credenciais existentes se for se conectar à mesma conta do BigQuery.

Formate uma carga útil a partir de colunas existentes

Se você preferir armazenar cada atributo em sua própria coluna internamente, precisa converter essas colunas em uma string JSON para preencher a sincronização com a Braze. Use esta consulta no BigQuery para formatar as colunas de origem nos campos da CDI.

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

CREATE OR REPLACE TABLE BRAZE.EXAMPLE_USER_DATA (attribute_1 string,
     attribute_2 STRING,
     attribute_3 NUMERIC,
     my_user_id STRING);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
      STRUCT(
        'attribute_1' AS attribute_1,
        'attribute_2'AS attribute_2,
        'yet_another_attribute'AS attribute_3
      )
    ) as PAYLOAD
  FROM BRAZE.EXAMPLE_USER_DATA;

Para mais orientações de otimização, consulte Práticas recomendadas da ingestão de dados na nuvem.

Solução de problemas

O teste de conexão está lento

O teste de conexão é executado no seu data warehouse, então aumentar a capacidade do warehouse pode deixá-lo mais rápido. Usar uma instância SQL serverless reduz o tempo de inicialização e melhora a vazão das consultas, mas pode gerar custos de integração um pouco maiores.

O usuário não tem permissão para consultar a tabela

Se você receber esse erro, adicione permissões de usuário para consultar a tabela.

Seu uso excedeu a cota personalizada

Se você receber esse erro, sua cota precisa ser atualizada para que você possa continuar sincronizando na taxa atual.

A tabela não foi encontrada no local {region}

Se você receber esse erro, verifique se a sua tabela está no projeto e no conjunto de dados corretos.

Assinatura JWT inválida

Se você receber esse erro, verifique se o serviço da API do BigQuery está ativado na sua conta.

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.

Onde executar verificações SQL

Execute as verificações de validação diretamente no espaço de trabalho SQL do BigQuery Studio, na mesma tabela ou visualização usada pela sua integração de CDI. Para saber mais, consulte a introdução ao BigQuery Studio.

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