Passer au contenu

Ingestion de données cloud pour Google Cloud Storage

Cette page présente tout ce dont vous avez besoin pour synchroniser des données de Google Cloud Storage (GCS) vers Braze à l’aide de l’ingestion de données cloud (CDI) : les ressources Google Cloud à créer, la connexion de la source et la création d’une synchronisation dans Braze, le format de fichier pour chaque type de données et la résolution des problèmes propres à GCS.

Fonctionnement

Les intégrations Google Cloud Storage sont pilotées par les événements plutôt que planifiées. Lorsque de nouveaux fichiers sont finalisés dans le compartiment, GCS publie une notification OBJECT_FINALIZE dans un sujet Pub/Sub. Braze consomme ces notifications à partir d’un abonnement Pub/Sub pour ingérer le nouveau fichier.

L’intégration nécessite les ressources suivantes :

  • Un compartiment Cloud Storage pour le stockage des données
  • Un sujet et un abonnement Pub/Sub pour les notifications de nouveaux fichiers
  • Un compte de service auquel Braze accède via l’une des méthodes d’authentification prises en charge

Définitions GCP

Terme Définition
Projet Google Cloud Un projet organise toutes vos ressources Google Cloud et est identifié par un ID de projet et un numéro de projet uniques.
Compartiment Cloud Storage Un compartiment est le conteneur qui héberge les fichiers de données que Braze doit ingérer.
Sujet Pub/Sub Un sujet est la ressource nommée qui reçoit les notifications de nouveaux fichiers provenant de votre compartiment Cloud Storage.
Abonnement Pub/Sub Un abonnement est rattaché à un sujet et distribue ses messages. Braze consomme les notifications de nouveaux fichiers à partir d’un abonnement pull.
Compte de service Un compte de service est une identité non humaine que Braze utilise pour accéder à votre compartiment et à votre abonnement. Braze en usurpe l’identité via la fédération d’identité de charge de travail, ou utilise une clé JSON que vous téléversez.
Fédération d’identité de charge de travail La fédération d’identité de charge de travail (WIF) permet à Braze d’usurper l’identité de votre compte de service avec une identité à courte durée de vie, sans que vous ayez à créer ou téléverser de clé.
Rôle IAM Un rôle IAM (Identity and Access Management) est un ensemble d’autorisations que vous attribuez au compte de service sur votre compartiment et votre abonnement.

Configurer l’ingestion de données cloud dans Google Cloud

Étape 1 : Créer un compartiment Cloud Storage

Dans la console Google Cloud, accédez à Cloud Storage > Buckets > Créer. Notez l’ID du projet et le nom du compartiment : vous en aurez besoin pour configurer la source dans Braze. Braze recommande d’activer l’accès uniforme au niveau du compartiment afin que les autorisations soient gérées avec IAM.

Étape 2 : Créer un sujet et un abonnement Pub/Sub

Dans la console Google Cloud, accédez à Pub/Sub > Sujets > Créer un sujet. Vous pouvez laisser Google créer un abonnement par défaut ou en créer un séparément. Créez ensuite un abonnement pull sur ce sujet.

Notez l’ID de l’abonnement. Braze a besoin de l’abonnement (et non du sujet) lorsque vous créez la synchronisation. L’abonnement doit être de type pull.

Étape 3 : Envoyer les notifications du compartiment vers le sujet

Commencez par autoriser l’agent de service Cloud Storage à publier dans le sujet, puis créez la notification pour OBJECT_FINALIZE. L’événement OBJECT_FINALIZE se déclenche chaque fois qu’un nouvel objet est créé ou finalisé dans le compartiment.




# 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

Remplacez YOUR-PROJECT-ID, YOUR-BUCKET-NAME et YOUR-TOPIC par vos propres valeurs. YOUR-PROJECT-NUMBER est l’identifiant numérique figurant dans l’adresse e-mail de l’agent de service ; il diffère de l’ID du projet. Vous le trouverez dans le Tableau de bord de la console Google Cloud, ou en exécutant gcloud projects describe YOUR-PROJECT-ID --format="value(projectNumber)".

Étape 4 : Créer un compte de service

Dans la console Google Cloud, accédez à IAM et administration > Comptes de service > Créer un compte de service. Cet exemple utilise braze-cdi-gcs comme nom de compte.

Étape 5 : Attribuer les autorisations

Le connecteur a besoin exactement des autorisations suivantes : storage.buckets.get, storage.objects.get et storage.objects.list sur le compartiment, et pubsub.subscriptions.consume sur l’abonnement. Vous pouvez les attribuer avec un rôle personnalisé ou avec des rôles prédéfinis.

Rôle personnalisé : Créez un rôle personnalisé avec exactement ces autorisations et associez-le au compartiment et à l’abonnement :




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"

Rôles prédéfinis : Au lieu d’un rôle personnalisé, attribuez roles/storage.objectViewer et roles/storage.legacyBucketReader sur le compartiment, et roles/pubsub.subscriber sur l’abonnement. Le rôle objectViewer fournit storage.objects.get et storage.objects.list, et legacyBucketReader fournit storage.buckets.get.

Étape 6 : 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 Google Cloud Storage et BigQuery. Si vous avez déjà effectué ces étapes pour une source BigQuery, 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 Google Cloud Storage 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.

Configurer l’ingestion de données cloud dans Braze

  1. Dans 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 Cloud Storage.

L’écran « Ajouter une nouvelle source » avec Google Cloud Storage sélectionné dans la liste des sources de données.

  1. Renseignez les champs de la source :
    • Compartiment : le nom de votre compartiment
    • ID du projet : l’ID de votre projet GCP
    • Identifiant : attribuez un nom à l’identifiant et sélectionnez la méthode d’authentification configurée à l’étape 6. 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.

Le formulaire de source Google Cloud Storage avec les champs Compartiment, ID du projet et téléversement de l’identifiant.

  1. Sélectionnez Tester la connexion, puis Se connecter à la source.
  2. Créez une synchronisation. Accédez à Paramètres des données > Ingestion de données cloud > Synchronisations et sélectionnez Créer une synchronisation des données. Choisissez un nom de synchronisation et un Type de données (par exemple Attributs utilisateur, Événements personnalisés, Événements d’achat, Catalogue ou Supprimer des utilisateurs), puis sélectionnez Suivant.
  3. À l’étape Définition des données, sélectionnez votre source GCS, puis indiquez les éléments suivants :

Le formulaire de synchronisation Google Cloud Storage avec les champs ID de l’abonnement Pub/Sub et chemin du dossier.

  1. Sélectionnez Prévisualiser et valider pour vérifier que Braze peut atteindre l’abonnement et lister les fichiers disponibles pour l’ingestion. Un test réussi liste les fichiers existants dans le compartiment, mais ces fichiers ne sont pas synchronisés automatiquement.
  2. Ajoutez des adresses e-mail de contact pour les notifications d’erreur. Les synchronisations Google Cloud Storage sont pilotées par les événements : aucune planification n’est donc nécessaire. Braze ingère les nouveaux fichiers dès leur téléversement. Vérifiez le récapitulatif, puis sélectionnez Créer une synchronisation.

Synchroniser un dossier dans un compartiment partagé

Vous pouvez réutiliser un même compartiment pour plusieurs synchronisations, mais chaque synchronisation doit cibler un dossier distinct et disposer de son propre abonnement Pub/Sub dédié.

Pour chaque dossier à synchroniser dans un compartiment partagé :

  1. Définissez le champ Dossier de la synchronisation sur le préfixe de chemin (par exemple, attributes/). Braze ne liste et n’ingère que les objets dont le chemin commence par ce préfixe.

  2. Créez un sujet dédié et une notification limitée au préfixe de ce dossier, puis créez un abonnement sur ce sujet :

    


     # 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. Accordez au compte de service Braze l’autorisation de consommation sur cet abonnement, comme à l’étape 5 :

    


     gcloud pubsub subscriptions add-iam-policy-binding YOUR-ATTRIBUTES-SUBSCRIPTION \
   --project=YOUR-PROJECT-ID \
   --member="serviceAccount:[email protected]" \
   --role="roles/pubsub.subscriber"

    Si vous avez créé le rôle personnalisé à l’étape 5, utilisez plutôt --role="projects/YOUR-PROJECT-ID/roles/brazeCdiGcs".

  4. Lorsque vous créez la synchronisation dans Braze, saisissez le nouvel ID de l’abonnement Pub/Sub et le Chemin du dossier de ce dossier afin que la synchronisation n’ingère que les fichiers de ce dossier.

Formats de fichier requis

Cloud Data Ingestion prend en charge les fichiers JSON, CSV et Parquet. Les colonnes requises dépendent du type de données. Braze n’impose aucune exigence supplémentaire concernant les noms de fichiers, au-delà de celles de votre fournisseur de stockage de fichiers. Les noms de fichiers doivent être uniques, et l’ajout d’un horodatage permet de garantir cette unicité.

Pour consulter des exemples de tous les types de fichiers pris en charge, reportez-vous aux fichiers d’exemple dans braze-examples.

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

Chaque ligne nécessite exactement un identifiant utilisateur et une colonne payload. Un fichier source peut contenir des lignes avec différents types d’identifiants, mais chaque ligne ne doit en utiliser qu’un seul.

Identifiant Description
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.
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 téléphone, Braze utilise l’e-mail comme 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.

La colonne payload contient une chaîne de caractères JSON des champs que vous souhaitez synchroniser avec l’utilisateur dans Braze, selon le format de l’objet attributs utilisateur.

Exemple JSON




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

Exemple CSV




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

Les événements personnalisés utilisent les mêmes colonnes d’identifiant utilisateur que les attributs utilisateur. La colonne payload suit le format de l’objet événements.




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

Les événements d’achat utilisent les mêmes colonnes d’identifiant utilisateur que les attributs utilisateur. La colonne payload suit le format de l’objet achats.




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

Les fichiers de catalogue utilisent des identifiants différents de ceux des fichiers de données utilisateur. Avant de créer une synchronisation de catalogue, créez le catalogue cible dans Braze. Pour connaître le processus complet relatif aux catalogues, consultez Synchroniser et supprimer des données de catalogue.

Colonne Requis Description
ID Oui L’identifiant unique de l’article de catalogue. Il sert à créer, mettre à jour ou supprimer l’article dans Braze.
payload Oui Une chaîne de caractères JSON des champs et valeurs de catalogue à synchroniser. Elle doit correspondre au schéma de votre catalogue dans Braze.
DELETED Non Lorsque la valeur est true, l’article de catalogue correspondant à l’ID est retiré du catalogue dans Braze. Omettez cette colonne ou définissez-la sur false pour les opérations de création ou de mise à jour.

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

Exemple CSV avec la colonne DELETED




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

Exemple CSV sans la colonne DELETED




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

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

Champ Requis Description
EXTERNAL_ID Oui, l’un des deux : external_id ou alias_name et alias_label 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 Oui, l’un des deux : external_id ou 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.
PROPERTIES Oui Chaîne de caractères JSON des champs à rendre disponibles en tant que propriétés de personnalisation dans votre Canvas. Elle doit contenir des informations propres à l’utilisateur.

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

Pour supprimer des profils utilisateur dans Braze à l’aide de fichiers présents dans votre compartiment source :

  1. Créez une nouvelle synchronisation Cloud Data Ingestion, avec la même configuration que pour les autres synchronisations.
  2. Lors de la configuration de la synchronisation dans Braze, définissez Type de données sur Supprimer des utilisateurs.
  3. Importez dans votre compartiment source des fichiers contenant uniquement des colonnes d’identifiant utilisateur. N’incluez pas de colonne payload : la synchronisation échoue si un payload est présent, afin d’éviter les suppressions accidentelles.

Chaque ligne du fichier doit identifier exactement un utilisateur à l’aide de l’un des identifiants suivants :

Identifiant Description
EXTERNAL_ID Correspond à l’external_id utilisé dans Braze.
ALIAS_NAME et ALIAS_LABEL Ces deux colonnes identifient ensemble l’utilisateur par son alias.
BRAZE_ID ID utilisateur généré par Braze (utilisateurs existants uniquement).

Exemple JSON

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

Exemple CSV




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

Lors de l’exécution de la synchronisation, Braze traite les nouveaux fichiers du compartiment et supprime les profils utilisateur correspondants.

Supprimer des éléments de catalogue

Pour supprimer des articles d’un catalogue à l’aide du stockage de fichiers :

  1. Utilisez la synchronisation que vous employez déjà pour synchroniser les données du catalogue (type de données Catalogues).
  2. Dans vos fichiers CSV ou JSON, ajoutez une colonne facultative deleted (ou DELETED).
  3. Définissez deleted sur true pour chaque article que vous souhaitez supprimer du catalogue dans Braze.

Chaque ligne doit toujours contenir ID et payload. Pour les lignes à supprimer, le payload peut être minimal : Braze supprime l’article en fonction de son ID.

Lors de l’exécution de la synchronisation, chaque ligne avec deleted: true entraîne la suppression de l’article de catalogue correspondant dans Braze. Pour en savoir plus sur le fonctionnement complet de la synchronisation et de la suppression des catalogues, consultez Synchroniser et supprimer des données de catalogue.

À savoir

  • Les fichiers ajoutés au compartiment ou au conteneur source ne doivent pas dépasser 512 Mo. Cette limite s’applique à Amazon S3, Google Cloud Storage et Azure Blob Storage. Les fichiers de plus de 512 Mo génèrent une erreur et ne sont pas synchronisés avec Braze. Azure Blob Storage accepte en soi des fichiers beaucoup plus volumineux, mais CDI applique la même limite de 512 Mo à toutes les sources de stockage de fichiers.
  • Bien qu’il n’y ait pas de limite supplémentaire sur le nombre de lignes par fichier, Braze recommande d’utiliser des fichiers plus petits pour accélérer vos synchronisations. Par exemple, l’ingestion d’un fichier de 500 Mo prendrait beaucoup plus de temps que celle de cinq fichiers distincts de 100 Mo.
  • Il n’y a pas de limite supplémentaire sur le nombre de fichiers importés sur une période donnée.
  • L’ordre n’est pas garanti au sein des fichiers ni entre eux. Si vous surveillez d’éventuelles conditions de concurrence, Braze recommande de regrouper périodiquement les mises à jour.
  • CDI ne traite que les fichiers ajoutés après la création de la synchronisation. Vous pouvez utiliser des fichiers existants pour vérifier que Braze peut accéder à votre compartiment et détecter les fichiers à ingérer, mais ils ne sont pas synchronisés avec Braze. Pour que CDI les traite, importez à nouveau dans le compartiment source les fichiers existants que vous souhaitez synchroniser.

Résolution des problèmes

Téléversement et traitement des fichiers

La CDI ne traite que les fichiers téléversés après la création de la synchronisation. Chaque nouvel objet déclenche un message OBJECT_FINALIZE dans votre sujet Pub/Sub. Pour ingérer des fichiers déjà présents dans le compartiment, téléversez-les à nouveau.

Gérer les erreurs de fichiers inattendues

Si des fichiers ne sont pas ingérés, vérifiez les points suivants :

  • La notification du compartiment existe. Listez les notifications du compartiment avec gcloud storage buckets notifications list gs://YOUR-BUCKET-NAME.
  • L’agent de service Cloud Storage dispose du rôle roles/pubsub.publisher sur le sujet.
  • Le compte de service Braze dispose de l’autorisation de consommation sur l’abonnement (pubsub.subscriptions.consume, attribuée via le rôle personnalisé ou roles/pubsub.subscriber).
  • Aucune file d’attente de lettres mortes n’est configurée sur l’abonnement. Braze ne prend pas en charge les files d’attente de lettres mortes pour les abonnements d’ingestion de données cloud.

Pour plus d’informations, consultez Notifications Pub/Sub pour Cloud Storage dans la documentation Google Cloud.

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.

Erreur « Incorrect Integration Object »

Cette erreur se produit lorsque deux espaces de travail ou plus ont des intégrations pointant vers le même compartiment ou dossier de stockage cloud. Chaque emplacement de stockage cloud ne peut être utilisé que par une seule intégration à la fois. Pour connaître la marche à suivre, consultez la FAQ.

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!