Passer au contenu

Ingestion de données cloud pour Google BigQuery

Cette page couvre tout ce dont vous avez besoin pour synchroniser des données de Google BigQuery vers Braze grâce à l’ingestion de données cloud (CDI) : les ressources à créer dans Google Cloud, la connexion de la source et la création d’une synchronisation dans Braze, la table source pour chaque type de données, ainsi que la résolution des problèmes propres à BigQuery.

Aperçu de la configuration

  1. Dans votre compte BigQuery, configurez les tables ou les vues que vous souhaitez synchroniser avec Braze.
  2. Créez un compte de service et autorisez l’accès aux projets et jeux de données BigQuery qui contiennent les données à synchroniser.
  3. Configurez la manière dont Braze accède au compte de service, en utilisant l’une des méthodes d’authentification prises en charge.
  4. Créez une nouvelle source et une nouvelle synchronisation dans le tableau de bord de Braze.
  5. Validez l’intégration et lancez la synchronisation.

Étape 1 : Configurer votre table source

Les étapes de cette section créent une table avec une colonne payload. Si vous prévoyez de mapper des colonnes avec Visuel ou d’écrire une requête avec SQL à l’étape Définition des données, vous pouvez plutôt utiliser une table ou une vue existante. Ignorez l’étape de création de la table et accordez à Braze un accès en lecture aux tables ou aux vues que vous souhaitez synchroniser. Pour comparer les options, consultez Choisir une option de définition des données.

Vous pouvez nommer le projet, le jeu de données et la table comme vous le souhaitez, mais les noms des colonnes doivent correspondre aux définitions des onglets suivants. Vous pouvez également utiliser une vue ou une vue matérialisée à la place d’une table.

Si vous le souhaitez, configurez un nouveau projet ou jeu de données pour héberger votre table source :




CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Sélectionnez l’onglet correspondant au type de données que vous souhaitez synchroniser.

Les attributs utilisateur, les événements personnalisés et les événements d’achat utilisent tous la même structure de table source. Seul le contenu de payload diffère.




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
);
Nom du champ Type Mode
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 - L’heure à laquelle cette ligne a été mise à jour ou ajoutée à la table. Braze synchronise les lignes dont la valeur UPDATED_AT est postérieure à la dernière valeur synchronisée. Les lignes situées exactement à l’horodatage limite peuvent être resynchronisées si de nouvelles lignes partagent ce même horodatage.
  • Colonnes d’identifiant utilisateur - Votre table peut contenir une ou plusieurs colonnes d’identifiant utilisateur. Chaque ligne ne doit contenir qu’un seul identifiant (soit external_id, soit la combinaison de alias_name et alias_label, soit braze_id, email ou phone). Une table source peut comporter des colonnes pour un, deux, trois, quatre ou les cinq types d’identifiants.
    • EXTERNAL_ID - Identifie l’utilisateur que vous souhaitez mettre à jour. Cette valeur doit correspondre à la valeur external_id utilisée dans Braze.
    • ALIAS_NAME et ALIAS_LABEL - Ces deux colonnes créent un objet alias d’utilisateur. alias_name doit être un identifiant unique, et alias_label indique le type d’alias. Les utilisateurs peuvent avoir plusieurs alias avec des libellés différents, mais un seul alias_name par alias_label.
    • BRAZE_ID - L’identifiant utilisateur Braze. Il est généré par le SDK de Braze, et il n’est pas possible de créer de nouveaux utilisateurs à l’aide d’un ID Braze via l’ingestion de données cloud. Pour créer de nouveaux utilisateurs, indiquez un ID utilisateur externe ou un alias d’utilisateur.
    • EMAIL - L’adresse e-mail de l’utilisateur. Si plusieurs profils partagent la même adresse e-mail, le profil mis à jour le plus récemment est prioritaire pour les mises à jour. Si vous incluez à la fois l’e-mail et le numéro de téléphone, l’e-mail sert d’identifiant principal.
    • PHONE - Le numéro de téléphone de l’utilisateur. Si plusieurs profils partagent le même numéro de téléphone, le profil mis à jour le plus récemment est prioritaire pour les mises à jour.
  • payload - Il s’agit d’une chaîne de caractères JSON contenant les champs que vous souhaitez synchroniser avec l’utilisateur dans Braze.

Pour les synchronisations d’attributs, payload suit le format de l’objet des attributs utilisateur. Vous pouvez inclure des attributs personnalisés imbriqués, des tableaux d’objets et des statuts de groupe d’abonnement. Pour des exemples de payloads, consultez Configuration de la table.

Les événements personnalisés utilisent la même table source que les attributs utilisateur. Créez la table présentée dans l’onglet Attributs utilisateur, puis renseignez payload avec un objet d’événement.

Pour synchroniser des événements, un nom d’événement est obligatoire. Formatez le champ time sous forme de chaîne de caractères ISO 8601 ou au format yyyy-MM-dd'T'HH:mm:ss:SSSZ. Si le champ time est absent, Braze utilise la valeur de la colonne UPDATED_AT comme heure de l’événement. Les autres champs, notamment app_id et properties, sont facultatifs.

Vous pouvez synchroniser un événement par ligne.




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

Les événements d’achat utilisent la même table source que les attributs utilisateur. Créez la table présentée dans l’onglet Attributs utilisateur, puis renseignez payload avec un objet d’achat.

Pour synchroniser des événements d’achat, product_id, currency et price sont obligatoires. Formatez le champ facultatif time sous forme de chaîne de caractères ISO 8601 ou au format yyyy-MM-dd'T'HH:mm:ss:SSSZ. Si le champ time est absent, Braze utilise la valeur de la colonne UPDATED_AT comme heure de l’événement. Les autres champs, notamment app_id, quantity et properties, sont facultatifs.

Vous pouvez synchroniser un événement d’achat par ligne.




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

Avant de créer une synchronisation de catalogue, créez le catalogue cible dans Braze. Pour le flux de travail complet des catalogues, consultez Synchroniser et supprimer des données de catalogue.




CREATE TABLE `BRAZE-CLOUD-PRODUCTION.INGESTION.CATALOGS_SYNC`
(
  updated_at TIMESTAMP DEFAULT current_timestamp,
  id STRING,
  payload JSON,
  deleted BOOLEAN
);
Nom du champ Type Mode
UPDATED_AT TIMESTAMP REQUIRED
payload JSON REQUIRED
ID STRING REQUIRED
DELETED BOOLEAN OPTIONAL

Le nom de l’intégration doit correspondre exactement au nom du catalogue que vous avez créé dans Braze.

Braze recommande de créer une vue à partir de vos données de catalogue afin que la table source soit entièrement actualisée à chaque exécution d’une synchronisation. Par exemple, si vous disposez d’une table de données produits (product_catalog_1) avec product_id et trois attributs supplémentaires, vous pouvez synchroniser la vue suivante :




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`);

Les déclencheurs de Canvas alimentent la personnalisation zero-copy. Pour la configuration du Canvas de destination et les points à prendre en compte, consultez Personnalisation zero-copy.




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
);
Nom du champ Type Obligatoire ?
UPDATED_AT TIMESTAMP Oui
PROPERTIES JSON Oui
EXTERNAL_ID STRING NULLABLE
ALIAS_NAME STRING NULLABLE
ALIAS_LABEL STRING NULLABLE

Les synchronisations de déclencheurs Canvas diffèrent des autres synchronisations de données utilisateur sur trois points :

  • Seuls les identifiants de type ID externe ou alias d’utilisateur sont pris en charge. Les adresses e-mail et les numéros de téléphone ne sont pas des identifiants pris en charge.
  • Seuls les utilisateurs Braze existants peuvent être synchronisés. Il n’est pas possible de créer de nouveaux utilisateurs.
  • PROPERTIES remplace la colonne payload. Il s’agit d’une chaîne de caractères JSON contenant les champs que vous souhaitez utiliser comme propriétés d’entrée du Canvas pour la personnalisation.

Votre table de déclencheurs Canvas doit contenir les colonnes suivantes :

  • UPDATED_AT - Le moment où cette ligne a été mise à jour ou ajoutée à la table. Braze synchronise les lignes dont la valeur UPDATED_AT est postérieure à la dernière valeur synchronisée. Les lignes situées exactement à l’horodatage limite peuvent être resynchronisées si de nouvelles lignes partagent ce même horodatage.
  • Soit EXTERNAL_ID, soit ALIAS_NAME et ALIAS_LABEL comme colonne d’identifiant utilisateur. Ces colonnes identifient les utilisateurs pour lesquels vous souhaitez déclencher des messages Canvas.
    • EXTERNAL_ID - Identifie l’utilisateur à faire entrer dans le Canvas. Cette valeur doit correspondre à la valeur external_id utilisée dans Braze.
    • ALIAS_NAME et ALIAS_LABEL - Ces colonnes créent un objet alias d’utilisateur. alias_name doit être un identifiant unique, et alias_label indique le type d’alias. Les utilisateurs peuvent avoir plusieurs alias avec des libellés différents, mais un seul alias_name par alias_label.
  • PROPERTIES - Une chaîne de caractères JSON contenant les champs à rendre disponibles comme propriétés de personnalisation dans votre Canvas. Elle doit contenir des informations propres à chaque utilisateur.

Pour commencer, sélectionnez le type de données Déclencheurs de Canvas lors de la création d’une nouvelle synchronisation.

Les tables sources pour les suppressions d’utilisateurs doivent inclure un ou plusieurs types d’identifiants utilisateur ainsi qu’un horodatage UPDATED_AT. Les colonnes de payload ne sont pas prises en charge pour les données de suppression d’utilisateurs.

  • UPDATED_AT - L’heure à laquelle cette ligne a été mise à jour ou ajoutée à la table. Braze synchronise les lignes dont la valeur UPDATED_AT est postérieure à la dernière valeur synchronisée. Les lignes situées exactement à l’horodatage limite peuvent être resynchronisées si de nouvelles lignes partagent ce même horodatage.
  • Colonnes d’identifiant utilisateur - Chaque ligne ne doit contenir qu’un seul identifiant : soit external_id, soit la combinaison de alias_name et alias_label, soit braze_id. Une table source peut contenir des colonnes pour un, deux ou les trois types d’identifiants.
    • EXTERNAL_ID - Identifie l’utilisateur que vous souhaitez mettre à jour. Cette valeur doit correspondre à la valeur external_id utilisée dans Braze.
    • ALIAS_NAME et ALIAS_LABEL - Ces deux colonnes créent un objet alias d’utilisateur. alias_name doit être un identifiant unique, et alias_label indique le type d’alias. Les utilisateurs peuvent avoir plusieurs alias avec des libellés différents, mais un seul alias_name par alias_label.
    • BRAZE_ID - L’identifiant utilisateur Braze. Il est généré par le SDK de Braze, et il n’est pas possible de créer de nouveaux utilisateurs à l’aide d’un ID Braze via Cloud Data Ingestion. Pour créer de nouveaux utilisateurs, indiquez un ID utilisateur externe ou un alias d’utilisateur.

Créez une table avec les champs suivants :

Nom du champ Type Mode
UPDATED_AT TIMESTAMP REQUIRED
EXTERNAL_ID STRING NULLABLE
ALIAS_NAME STRING NULLABLE
ALIAS_LABEL STRING NULLABLE
BRAZE_ID STRING NULLABLE

Sur la page Créer une synchronisation d’importation, définissez le Type de données sur Supprimer des utilisateurs afin que les actions appropriées soient effectuées lors de l’exécution de l’intégration. Pour plus d’informations, consultez Supprimer des utilisateurs avec l’ingestion de données cloud.

Étape 2 : Créer un compte de service et accorder les autorisations

Créez dans GCP un compte de service que Braze utilisera pour se connecter à vos tables et en lire les données. Le compte de service doit disposer des autorisations suivantes :

  • BigQuery Connection User : permet à Braze d’établir des connexions
  • BigQuery User : permet à Braze d’exécuter des requêtes, de lire les métadonnées des jeux de données et de répertorier les tables.
  • BigQuery Data Viewer : permet à Braze de consulter les jeux de données et leur contenu.
  • BigQuery Job User : permet à Braze d’exécuter des jobs

Étape 3 : Configurer l’authentification

Braze peut accéder au compte de service avec l’une des méthodes d’authentification suivantes :

Méthode Mode d’authentification de Braze Informations à saisir dans Braze
Workload Identity Federation Braze impersonates your service account with a short-lived identity, so you don’t create or upload a key. Project number, Workload identity pool ID, Provider ID, and Service account email
Service account key Braze authenticates with a JSON key that you create for your service account. JSON key file for the service account

Workload Identity Federation

Avec Workload Identity Federation (WIF), Braze s’authentifie auprès de Google Cloud à l’aide d’une identité éphémère provenant de son propre environnement AWS, puis usurpe l’identité du compte de service que vous avez créé pour Braze. Vous configurez votre projet pour qu’il fasse confiance à cette identité uniquement pour votre espace de travail. Vous ne créez ni ne partagez de clé de compte de service.

Vous configurez WIF une seule fois par projet Google Cloud. Un seul identifiant WIF dessert à la fois les sources BigQuery et Google Cloud Storage. Si vous avez déjà effectué ces étapes pour une source Google Cloud Storage, accordez au compte de service existant les autorisations pour cette source et ignorez le reste de cette section.

Conditions préalables

Pour effectuer ces étapes dans la console Google Cloud, vous devez disposer de l’autorisation de créer des pools d’identités de charge de travail et de gérer les stratégies Identity and Access Management (IAM) sur le compte de service et sur vos données. Vous pouvez par exemple utiliser les rôles Workload Identity Pool Admin (roles/iam.workloadIdentityPoolAdmin) et Service Account Admin (roles/iam.serviceAccountAdmin).

Faire confiance uniquement au principal de votre espace de travail

Tous les espaces de travail Braze d’une même instance Braze présentent le même rôle AWS. Seul le nom de session à la fin de l’ARN du principal, qui correspond à l’ID de votre espace de travail, vous est propre.

Le mappage d’attributs par défaut de Google pour les fournisseurs AWS définit aws_role sur l’ARN du rôle sans le nom de session. Par conséquent, accorder l’accès aux identités correspondant à une valeur aws_role, comme principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_ARN, revient à faire confiance à tous les espaces de travail Braze de votre instance, y compris le vôtre.

Pour limiter l’accès à vos données à votre seul espace de travail :

  • Accordez l’accès uniquement aux identités dont le subject correspond à l’ARN complet de votre principal Braze. Il s’agit du principal principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/BRAZE_PRINCIPAL_ARN.
  • N’accordez pas l’accès à All identities in the pool, ni aux identités filtrées par aws_role ou account.
  • N’écrivez pas de condition d’attribut qui vérifie uniquement le compte ou le rôle AWS.
  • Conservez le mappage d’attributs par défaut pour google.subject, à savoir assertion.arn.

L’ARN du principal Braze diffère pour chaque espace de travail et chaque instance Braze, et Braze utilise un rôle AWS pour les sources Google distinct de celui des autres sources, comme Snowflake. Copiez toujours la valeur depuis un formulaire d’identifiants BigQuery ou Google Cloud Storage dans l’espace de travail que vous connectez.

Copier l’ARN du principal Braze

Dans Braze, commencez à créer votre source BigQuery et sélectionnez Workload Identity Federation comme méthode d’authentification. Copiez la valeur indiquée à l’étape 1 du formulaire d’identifiants, Copy the Braze principal ARN, et laissez le formulaire ouvert.

Si le champ affiche Unavailable, WIF n’est pas disponible pour votre instance Braze. Utilisez plutôt une clé de compte de service.

Activer les API requises

Dans la console Google Cloud, accédez à APIs & Services > Library, puis activez les API suivantes pour votre projet :

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

Créer le pool d’identités de charge de travail et le fournisseur

  1. Accédez à IAM & Admin > Workload Identity Federation, puis sélectionnez Create pool.
  2. Saisissez un nom pour le pool, par exemple « Braze CDI ». Notez le Pool ID, puis sélectionnez Continue.
  3. Pour Select a provider, sélectionnez AWS.
  4. Saisissez un nom de fournisseur, par exemple « Braze AWS », et notez le Provider ID.
  5. Pour AWS account ID, saisissez le nombre à 12 chiffres qui suit arn:aws:sts:: dans l’ARN du principal Braze, puis sélectionnez Continue.
  6. Sous Configure provider attributes, conservez le mappage par défaut, y compris google.subject = assertion.arn.
  7. Sélectionnez Save.

Les ID de pool et de fournisseur doivent comporter entre 4 et 32 caractères, composés de lettres minuscules, de chiffres et de traits d’union.

Restreindre le fournisseur à votre principal (facultatif)

Pour une défense en profondeur, ajoutez une condition d’attribut afin que le fournisseur n’accepte que le principal de votre espace de travail. Google rejette alors toute autre identité dès l’échange de jetons, avant même de vérifier les autorisations du compte de service.

  1. Dans le pool, sélectionnez le fournisseur, puis Edit.
  2. Sous Attribute conditions, sélectionnez Add condition.

  3. Saisissez la condition suivante, en remplaçant BRAZE_PRINCIPAL_ARN par la valeur complète copiée depuis le formulaire d’identifiants :

    


     assertion.arn == 'BRAZE_PRINCIPAL_ARN'
  4. Sélectionnez Save.

Cette condition dédie le fournisseur à un seul espace de travail Braze. Pour connecter un autre espace de travail, créez un fournisseur distinct pour celui-ci, ou listez les deux principaux, comme dans assertion.arn in ['FIRST_BRAZE_PRINCIPAL_ARN', 'SECOND_BRAZE_PRINCIPAL_ARN'].

Lier le principal Braze au compte de service

Accordez au principal de votre espace de travail l’autorisation d’usurper l’identité du compte de service :

  1. Accédez à IAM & Admin > Workload Identity Federation, puis sélectionnez votre pool.
  2. Sélectionnez Grant access, puis Grant access using service account impersonation.
  3. Pour Service account, sélectionnez le compte de service que vous avez créé pour Braze.
  4. Sous Select principals, sélectionnez Only identities matching the filter.
  5. Pour Attribute name, sélectionnez subject. Pour Attribute value, collez l’ARN complet du principal Braze issu du formulaire d’identifiants.
  6. Sélectionnez Save. Si Google vous propose de télécharger un fichier de configuration de bibliothèque cliente, sélectionnez Dismiss. Braze n’en a pas besoin.

Cela accorde le rôle Workload Identity User (roles/iam.workloadIdentityUser) sur le compte de service à un principal de la forme suivante :




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

Pour vérifier, ouvrez le compte de service et sélectionnez l’onglet Permissions. Le rôle Workload Identity User doit afficher ce principal, qui se termine par l’ARN complet de votre principal Braze.

Accordez ce rôle uniquement sur le compte de service. Une autorisation au niveau du projet permet au principal d’usurper l’identité de tous les comptes de service du projet.

Les modifications IAM peuvent prendre quelques minutes avant d’être effectives. Si un test de connexion échoue juste après l’octroi de l’accès, patientez quelques minutes et réessayez.

Le compte de service doit également avoir accès à vos données. Assurez-vous de lui avoir accordé les autorisations pour cette source. Si vous utilisez un seul identifiant pour BigQuery et Google Cloud Storage, accordez les deux ensembles d’autorisations au même compte de service.

Saisir les valeurs dans Braze

Revenez au formulaire d’identifiants de Braze et saisissez les valeurs suivantes, issues de la console Google Cloud :

Champ Braze Où le trouver
Project number La fiche Project info du Dashboard de la console. Utilisez le numéro de projet numérique plutôt que l’ID du projet.
Workload identity pool ID Le Pool ID du pool que vous avez créé
Provider ID Le Provider ID du fournisseur que vous avez créé
Service account email L’Email du compte de service sur la page Service Accounts

Braze combine le numéro de projet, l’ID du pool et l’ID du fournisseur pour former l’audience, qui indique à Google quel fournisseur valide la requête provenant de Braze. Par défaut, un fournisseur accepte son propre nom de ressource comme audience. Si vous définissez des audiences autorisées personnalisées sur votre fournisseur, incluez le nom de ressource complet du fournisseur.

Comment Braze teste la connexion

Lorsque vous testez la connexion dans Braze, Braze vérifie également que votre configuration ne fait confiance qu’à votre espace de travail. Pendant le test, Braze tente le même échange avec un nom de session de test composé uniquement de zéros, sous la forme suivante :




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

Votre configuration doit rejeter cette identité, soit lors de l’échange de jetons, soit lorsqu’elle tente d’usurper l’identité de votre compte de service. Si les deux étapes réussissent, le test échoue, car votre configuration fait confiance à des identités autres que le principal de votre espace de travail. Pour corriger ce problème, consultez Votre configuration fait confiance à des identités autres que votre espace de travail.

Si vous avez défini la condition d’attribut facultative, Google rejette l’identité de test lors de l’échange de jetons. Sinon, Google la rejette lorsqu’elle tente d’usurper l’identité de votre compte de service. Dans les deux cas, le test réussit.

Cette tentative rejetée peut apparaître dans vos journaux d’audit Google Cloud à chaque test de connexion. Ce comportement est normal : la tentative provient de la vérification de Braze et ne donne à personne l’accès à vos données.

N’ajoutez pas de condition qui rejette uniquement cette session de test. Une telle condition fait réussir le test alors que votre configuration fait toujours confiance à d’autres espaces de travail Braze.

Retirer l’accès de Braze

Pour empêcher Braze d’accéder à vos données, retirez le rôle Workload Identity User du principal Braze dans l’onglet Permissions du compte de service, ou supprimez le fournisseur.

Configurer avec la CLI gcloud

Si vous préférez la ligne de commande, les commandes suivantes activent les API, créent le pool et le fournisseur, puis lient le principal Braze à votre compte de service. Remplacez les valeurs du premier bloc et collez l’ARN du principal Braze exactement tel que vous l’avez copié.




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

Braze s’authentifie à l’aide d’une clé JSON associée à votre compte de service. Les identifiants existants basés sur une clé de compte de service continuent de fonctionner, et vous n’avez pas besoin de les migrer.

Dans la console Google Cloud, ouvrez le compte de service, accédez à Clés > Ajouter une clé > Créer une clé, puis sélectionnez JSON. Téléchargez le fichier de clé. Vous l’importerez dans Braze lors de la création de la source.

Vous pouvez également utiliser gcloud :




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

Remplacez SERVICE_ACCOUNT_EMAIL par l’adresse e-mail du compte de service. Pour plus d’informations, consultez Créer et supprimer des clés de compte de service.

Étape 4 : Autoriser l’accès aux IP de Braze

Si vous avez mis en place des politiques réseau, vous devez accorder à Braze un accès réseau à votre instance BigQuery. Autorisez l’accès depuis les IP suivantes, correspondant à la région de votre tableau de bord de Braze.

Pour les instances US-01, US-02, US-03, US-04, US-05, US-06, US-07, voici les adresses IP correspondantes :

  • 23.21.118.191
  • 34.206.23.173
  • 50.16.249.9
  • 52.4.160.214
  • 54.87.8.34
  • 54.156.35.251
  • 52.54.89.238
  • 18.205.178.15

Pour l’instance US-08, voici les adresses IP correspondantes :

  • 52.151.246.51
  • 52.170.163.182
  • 40.76.166.157
  • 40.76.166.170
  • 40.76.166.167
  • 40.76.166.161
  • 40.76.166.156
  • 40.76.166.166
  • 40.76.166.160
  • 40.88.51.74
  • 52.154.67.17
  • 40.76.166.80
  • 40.76.166.84
  • 40.76.166.85
  • 40.76.166.81
  • 40.76.166.71
  • 40.76.166.144
  • 40.76.166.145

Pour l’instance US-10, voici les adresses IP correspondantes :

  • 100.25.232.164
  • 35.168.86.179
  • 52.7.44.117
  • 3.92.153.18
  • 35.172.3.129
  • 50.19.162.19

Pour les instances EU-01 et EU-02, voici les adresses IP correspondantes :

  • 52.58.142.242
  • 52.29.193.121
  • 35.158.29.228
  • 18.157.135.97
  • 3.123.166.46
  • 3.64.27.36
  • 3.65.88.25
  • 3.68.144.188
  • 3.70.107.88

Pour l’instance AU-01, voici les adresses IP correspondantes :

  • 13.210.1.145
  • 13.211.70.159
  • 13.238.45.54
  • 52.65.73.167
  • 54.153.242.239
  • 54.206.45.213

Pour l’instance ID-01, voici les adresses IP correspondantes :

  • 108.136.157.246
  • 108.137.30.207
  • 16.78.128.71
  • 16.78.14.134
  • 16.78.162.208
  • 43.218.73.35

Pour l’instance JP-01, voici les adresses IP correspondantes :

  • 13.159.155.212
  • 54.199.221.241
  • 13.192.23.16
  • 54.250.120.139
  • 18.181.114.232
  • 3.114.38.100

Pour l’instance KR-01, voici les adresses IP correspondantes :

  • 43.200.215.4
  • 52.79.67.175
  • 52.79.113.60
  • 3.34.212.92
  • 54.116.134.231
  • 3.37.197.225

Étape 5 : Créer une nouvelle source dans le tableau de bord de Braze

Dans le tableau de bord de Braze, accédez à Paramètres des données > Ingestion de données cloud > Sources, sélectionnez Ajouter une source de données, puis sélectionnez Google BigQuery.

Étape 5.1 : Ajouter les informations de connexion BigQuery et la table source

Saisissez un nom pour votre source, puis renseignez vos identifiants et votre configuration BigQuery :

  • Pour Nom de l’identifiant, saisissez un libellé qui vous aide à reconnaître ces identifiants dans Braze.
  • Pour la méthode d’authentification, sélectionnez celle que vous avez configurée à l’étape 3, puis saisissez ses identifiants. Pour Workload Identity Federation, saisissez Project number, Workload identity pool ID, Provider ID, and Service account email. Pour Service account key, saisissez JSON key file for the service account.

Renseignez ensuite les champs de configuration restants.

Étape 5.2 : Tester la connexion et se connecter à la source

Sélectionnez ensuite Tester la connexion. Une fois le test réussi, finalisez les paramètres restants et cliquez sur Se connecter à la source. Si la connexion échoue, un message d’erreur s’affiche pour vous aider à résoudre le problème.

Étape 6 : Créer une nouvelle synchronisation dans le tableau de bord de Braze

Accédez à Paramètres des données > Ingestion de données cloud > Synchronisations, puis sélectionnez Créer une synchronisation de données.

Configurer les détails de la synchronisation et définir vos données

Saisissez un nom pour votre synchronisation. Sélectionnez ensuite une source active et un type de données de synchronisation. Puis, sélectionnez Visuel ou Table et saisissez votre table source, ou sélectionnez SQL pour écrire une requête SQL personnalisée. Enfin, sélectionnez Prévisualiser et valider.

Une fois la validation réussie, un aperçu des données s’affiche. Sélectionnez Suivant : Notifications pour continuer. Si la validation échoue, un message d’erreur s’affiche pour vous aider à résoudre le problème.

Ajouter des préférences de notification

Saisissez une ou plusieurs adresses e-mail de contact pour recevoir les notifications d’erreurs de synchronisation. Braze utilise ces coordonnées pour vous informer des erreurs d’intégration, comme une perte inattendue de l’accès à une table.

Les adresses e-mail de contact reçoivent uniquement les notifications d’erreurs globales ou au niveau de la synchronisation, par exemple des tables manquantes ou des problèmes d’autorisations. Elles ne sont pas notifiées des problèmes au niveau des lignes. Les erreurs globales signalent des problèmes critiques de connexion qui empêchent l’exécution des synchronisations.

Il peut notamment s’agir des problèmes suivants :

  • Problèmes de connectivité
  • Manque de ressources
  • Problèmes d’autorisations
  • Espace insuffisant pour le niveau de catalogue (synchronisations de catalogues uniquement)

Définir la planification

Enfin, configurez votre synchronisation comme ponctuelle ou récurrente.

Les synchronisations ponctuelles s’exécutent uniquement lorsque vous sélectionnez Synchroniser maintenant dans le tableau de bord ou que vous appelez l’endpoint Déclencher une synchronisation.

Les synchronisations récurrentes peuvent s’exécuter aussi souvent que toutes les 5 minutes ou aussi rarement qu’une fois par mois. Par défaut, l’intervalle le plus court que vous pouvez définir dans le tableau de bord est de 15 minutes, ce qui vous aide à maîtriser les coûts de calcul de votre entrepôt de données et le volume de requêtes. Pour synchroniser jusqu’à toutes les 5 minutes, contactez le support Braze ou votre gestionnaire de la satisfaction client. Braze planifie les synchronisations récurrentes en UTC.

Exécuter la synchronisation

Une fois activée, votre synchronisation s’exécute selon la planification définie lors de la configuration. Si vous souhaitez exécuter la synchronisation en dehors de sa planification ou récupérer les données les plus récentes, sélectionnez Synchroniser maintenant. Cette exécution n’a aucune incidence sur les synchronisations futures planifiées. Pour lancer automatiquement une synchronisation lorsque vos données sont mises à jour, appelez l’endpoint Déclencher une synchronisation depuis votre pipeline.

Configurer des intégrations ou des utilisateurs supplémentaires (facultatif)

Vous pouvez configurer plusieurs intégrations avec Braze. Lors de la création de synchronisations supplémentaires, vous pouvez réutiliser des identifiants existants si vous vous connectez au même compte BigQuery.

Si vous réutilisez le même utilisateur dans plusieurs intégrations, vous ne pourrez pas le supprimer du tableau de bord de Braze tant qu’il n’aura pas été retiré de toutes les synchronisations actives.

Utiliser BigQuery comme source connectée

Une source connectée est une alternative zero-copy à la synchronisation des données dans Braze. Braze interroge directement votre instance BigQuery pour créer des segments CDI, sans copier les données sous-jacentes. Pour les concepts, les limites et les implications en matière de coûts, consultez Sources connectées.

Étape 1 : Créer un compte de service et accorder les autorisations

Créez dans GCP un compte de service que Braze utilisera pour se connecter à vos tables et en lire les données. Le compte de service doit disposer des autorisations suivantes :

  • BigQuery Connection User : permet à Braze d’établir des connexions.
  • BigQuery User : permet à Braze d’exécuter des requêtes, de lire les métadonnées des jeux de données et de répertorier les tables.
  • BigQuery Data Viewer : permet à Braze de consulter les jeux de données et leur contenu.
  • BigQuery Job User : permet à Braze d’exécuter des jobs.
  • bigquery.tables.create : permet à Braze de créer des tables temporaires lors de l’actualisation des segments.

Ce compte de service sert à générer la liste des tables disponibles dans vos extensions de segments CDI et à interroger les tables sources pour créer de nouveaux segments. Une fois la source connectée créée, Braze découvre les noms et les descriptions de toutes les tables accessibles à l’utilisateur dans le schéma source.

Vous pouvez choisir d’accorder l’accès à toutes les tables d’un jeu de données, ou d’accorder des privilèges uniquement sur certaines tables. Toutes les tables auxquelles le rôle Braze a accès peuvent être interrogées dans l’extension de segments CDI.

L’autorisation create table est nécessaire pour que Braze puisse créer une table contenant les résultats de la requête de votre extension de segments CDI avant de mettre à jour le segment dans Braze. Braze crée une table temporaire par segment, et cette table n’est conservée que pendant la mise à jour du segment par Braze.

Après avoir créé le compte de service et accordé les autorisations, configurez la manière dont Braze y accède à l’aide de l’une des méthodes décrites à l’étape 3 : Configurer l’authentification. Si vous avez déjà configuré la fédération d’identité de charge de travail (Workload Identity Federation) pour ce projet, vous pouvez la réutiliser. Accordez au compte de service existant les autorisations indiquées dans cette étape.

La configuration de l’accès réseau est identique à celle de l’étape 4.

Étape 2 : Créer la source connectée dans Braze

Accédez à Paramètres des données > Ingestion de données cloud > Sources connectées, sélectionnez Ajouter une source de données, puis sélectionnez Google BigQuery.

Dans Configurer la source, renseignez les éléments suivants :

  • Identifiants : Nom de l’identifiant et les champs correspondant à votre méthode d’authentification. Pour Workload Identity Federation, saisissez Project number, Workload identity pool ID, Provider ID, and Service account email. Pour Service account key, saisissez JSON key file for the service account.
  • Configuration : Projet et Jeu de données

Choisissez un nom pour la source connectée. Ce nom apparaît dans la liste des sources disponibles lorsque vous créez une nouvelle extension de segments CDI.

Configurez une durée d’exécution maximale pour cette source. Braze interrompt automatiquement toute requête qui dépasse cette durée. La durée d’exécution maximale autorisée est de 60 minutes ; une durée plus courte réduit les coûts engagés sur votre compte BigQuery. Ce paramètre s’applique aux requêtes exécutées via cette source, y compris les synchronisations et les extensions de segments CDI qui l’utilisent.

Sélectionnez Tester la connexion pour vérifier que la liste des tables visibles par l’utilisateur correspond à vos attentes, puis sélectionnez Terminé. Votre source connectée est désormais créée et prête à être utilisée dans les extensions de segments CDI.

Vous pouvez configurer plusieurs sources connectées avec Braze, mais chaque source doit être configurée pour se connecter à un jeu de données différent. Lors de la création de sources supplémentaires, vous pouvez réutiliser des identifiants existants si vous vous connectez au même compte BigQuery.

Formater un payload à partir de colonnes existantes

Si vous préférez stocker chaque attribut dans sa propre colonne en interne, vous devez convertir ces colonnes en chaîne de caractères JSON pour alimenter la synchronisation avec Braze. Utilisez cette requête dans BigQuery pour formater les colonnes sources en champs CDI.




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;

Pour d’autres conseils d’optimisation, consultez Bonnes pratiques de l’ingestion de données cloud.

Résolution des problèmes

Le test de connexion est lent

Le test de connexion s’exécute sur votre entrepôt de données ; augmenter la capacité de l’entrepôt peut donc en améliorer la vitesse. L’utilisation d’une instance SQL serverless réduit le temps de préchauffage et améliore le débit des requêtes, mais peut entraîner des coûts d’intégration légèrement plus élevés.

L’utilisateur n’a pas l’autorisation d’interroger la table

Si vous recevez cette erreur, ajoutez des autorisations utilisateur permettant d’interroger la table.

Votre utilisation a dépassé le quota personnalisé

Si vous recevez cette erreur, votre quota doit être mis à jour pour que vous puissiez continuer à synchroniser à votre rythme actuel.

La table est introuvable dans l’emplacement {region}

Si vous recevez cette erreur, vérifiez que votre table se trouve dans le bon projet et le bon jeu de données.

Signature JWT non valide

Si vous recevez cette erreur, vérifiez que le service API BigQuery est activé pour votre compte.

Votre configuration fait confiance à des identités autres que votre espace de travail

Si vous utilisez la fédération d’identité de charge de travail, le test de connexion peut échouer avec l’erreur suivante :

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.

Cela signifie que Google a accepté l’identité de test de Braze à la fois lors de l’échange de jetons et lors de l’usurpation d’identité du compte de service, comme décrit dans Comment Braze teste la connexion. Cette erreur se produit généralement lorsque le compte de service accorde l’accès à toutes les identités du pool, ou à des identités filtrées par aws_role.

Pour corriger cette erreur :

  1. Dans la console Google Cloud, ouvrez le compte de service et sélectionnez l’onglet Autorisations.
  2. Repérez chaque compte principal disposant du rôle Utilisateur Workload Identity qui commence par principalSet:// et fait référence à votre pool. Retirez le rôle de chacun d’eux.
  3. Assurez-vous que votre compte principal complet dispose du rôle, comme décrit dans Associer le compte principal Braze au compte de service.
  4. Accédez à IAM et administration > IAM et recherchez les attributions du rôle Utilisateur Workload Identity au niveau du projet pour votre pool. Supprimez-les.
  5. Testez à nouveau la connexion.

Vous pouvez également restreindre la condition d’attribut du fournisseur à votre compte principal complet, comme décrit dans Restreindre le fournisseur à votre compte principal (facultatif). Google rejette alors toutes les autres identités lors de l’échange de jetons. Nous vous recommandons tout de même de n’accorder l’accès qu’à votre compte principal complet.

Braze n’a pas pu confirmer que votre pool fait uniquement confiance à cet espace de travail

Si vous utilisez la fédération d’identité de charge de travail, le test de connexion peut échouer avec l’erreur suivante :

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.

La vérification de Braze décrite dans Comment Braze teste la connexion n’a pas abouti. Par exemple, une erreur réseau ou une erreur temporaire de Google Cloud a interrompu la vérification. Cette erreur ne signifie pas que votre configuration est trop permissive. Testez à nouveau la connexion. Si l’erreur persiste, contactez l’assistance Braze.

Autorisation refusée lorsque Braze usurpe l’identité du compte de service

Si vous utilisez la fédération d’identité de charge de travail et que le test de connexion échoue avec une erreur d’autorisation sur iam.serviceAccounts.getAccessToken, vérifiez les points suivants :

  • L’onglet Autorisations du compte de service indique le rôle Utilisateur Workload Identity pour un compte principal se terminant par l’ARN complet de votre compte principal Braze, copié depuis un formulaire d’identifiants BigQuery ou Google Cloud Storage du même espace de travail.
  • L’API IAM Service Account Credentials est activée.
  • Vous avez attendu quelques minutes après avoir accordé l’accès.

L’échange de jetons est rejeté

Si vous utilisez la fédération d’identité de charge de travail et que le test de connexion échoue lors de l’échange de jetons avec Google Security Token Service, vérifiez les points suivants :

  • Le numéro de projet, l’ID du pool et l’ID du fournisseur que vous avez saisis dans Braze correspondent à votre configuration Google Cloud.
  • L’ID de compte AWS du fournisseur correspond à l’ID de compte figurant dans l’ARN du compte principal Braze.
  • Si vous avez défini une condition d’attribut, elle contient l’ARN complet de votre compte principal, exactement tel que copié.
  • Si vous avez défini des audiences autorisées personnalisées, elles incluent le nom de ressource complet du fournisseur.
  • Le pool et le fournisseur sont activés.

Où exécuter les vérifications SQL

Exécutez les vérifications de validation directement dans l’espace de travail SQL de BigQuery Studio, sur la même table ou vue que celle utilisée par votre intégration CDI. Pour plus d’informations, consultez Présentation de BigQuery Studio.

Documentation pour la plateforme d'engagement client Braze.

Ressources
Mentions légales
Entreprise
© 2026 Braze, Inc. Tous droits réservés.
Vérification du statut Braze
New Stuff!