Ingestion de données cloud pour Databricks

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

Aperçu de la configuration

1. Dans votre compte Databricks, configurez les tables ou les vues que vous souhaitez synchroniser avec Braze.
2. Créez des identifiants pour Braze avec l’une des méthodes d’authentification prises en charge, et autorisez l’accès aux catalogues et schémas Databricks qui contiennent les données à synchroniser.
3. Créez une nouvelle source et une nouvelle synchronisation dans le tableau de bord de Braze.
4. Validez l’intégration et lancez la synchronisation.

Important

Un temps de préchauffage de deux à cinq minutes peut être nécessaire lorsque Braze se connecte aux instances SQL Classic et Pro, ce qui peut entraîner des retards lors de la configuration et du test de la connexion, ainsi qu’au début des synchronisations planifiées. 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.

É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 vues que vous souhaitez synchroniser. Pour comparer les options, consultez Choisir une option de définition des données.

Vous pouvez nommer le schéma et la table comme vous le souhaitez, mais les noms de colonnes doivent correspondre aux définitions des onglets suivants. Vous pouvez également utiliser une vue ou une vue matérialisée au lieu d’une table.

Si vous le souhaitez, configurez un nouveau catalogue ou schéma pour héberger votre table source :

1

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

Remarque

Si vous utilisez une colonne payload, votre table ou vue source peut inclure des colonnes qui ne figurent pas dans les onglets suivants (par exemple, pour l’audit ou le hachage). Braze lit uniquement les colonnes décrites dans ces onglets ; les autres colonnes ne sont pas utilisées lors des synchronisations de l’ingestion de données cloud.

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

• attributs utilisateur
• événements personnalisés
• événements d’achat
• articles de catalogue
• déclencheurs canvas
• suppressions d’utilisateurs

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.

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 STRING, STRUCT, or MAP
);

Nom du champ	Type	Mode
UPDATED_AT	TIMESTAMP	REQUIRED
payload	STRING, STRUCT ou MAP	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 ou d’une structure 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 requis. 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.

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

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

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

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.

1
2
3
4
5
6
7

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

Nom du champ	Type	Mode
UPDATED_AT	TIMESTAMP	REQUIRED
payload	STRING, STRUCT ou MAP	REQUIRED
ID	STRING	REQUIRED
DELETED	BOOLEAN	NULLABLE

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 :

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

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.

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 STRING, STRUCT, or MAP
);

Nom du champ	Type	Requis
UPDATED_AT	TIMESTAMP	Oui
PROPERTIES	STRING, STRUCT ou MAP	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.

Remarque

Les propriétés ne sont pas obligatoires pour chaque ligne ou chaque utilisateur. En revanche, leurs valeurs doivent être une chaîne de caractères JSON valide. Si la ligne ne comporte aucune propriété, saisissez une chaîne vide {}.

Pour commencer, sélectionnez le type de données Déclencheurs 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.

Important

N’incluez pas de colonne payload dans votre table pour la suppression d’utilisateurs. Pour éviter toute suppression accidentelle et définitive d’utilisateurs, la synchronisation échoue si une colonne de payload est présente dans la table source. Toutes les autres colonnes sont autorisées, mais Braze les ignore.

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.

Avertissement

La suppression de profils utilisateurs est irréversible. L’action de suppression retire définitivement les utilisateurs, ce qui peut entraîner des incohérences dans vos données. Pour plus de détails, consultez Effets de la suppression de profils utilisateurs.

Étape 2 : Configurer l’authentification

Braze peut se connecter à Databricks avec l’une des méthodes d’authentification suivantes :

OAuth M2M

Braze se connecte à votre espace de travail Databricks en tant que principal de service grâce à l’authentification OAuth machine à machine (M2M). Databricks recommande OAuth M2M pour les connexions sans intervention humaine, comme l’ingestion de données cloud. Créez un nouveau principal de service que Braze utilisera, puis accordez-lui l’accès à votre entrepôt SQL et à vos tables sources. Pour se connecter, Braze a besoin des informations suivantes :

• L’ID client (également appelé ID d’application) du principal de service
• Le secret client qui permet à Braze de s’authentifier

Créer le principal de service

1. Dans votre espace de travail Databricks, sélectionnez votre nom d’utilisateur dans la barre supérieure, puis sélectionnez Settings.
2. Accédez à Identity and access, puis sélectionnez Manage à côté de Service principals.
3. Sélectionnez Add service principal > Add new.
4. Saisissez un nom qui vous permet d’identifier le principal de service, par exemple « Braze CDI », puis sélectionnez Add.
5. Sélectionnez le principal de service que vous avez créé. Dans l’onglet Configurations, vérifiez que l’option Databricks SQL access est sélectionnée.

Générer un secret client

1. Sur la page du principal de service, sélectionnez l’onglet Secrets, puis sélectionnez Generate secret.
2. Saisissez la durée de vie du secret, en jours. Databricks autorise une durée de vie maximale de 730 jours.
3. Sélectionnez Generate.
4. Copiez les valeurs Secret et Client ID, puis sélectionnez Done.

Conservez l’ID client et le secret en lieu sûr jusqu’à ce que vous deviez les saisir dans le tableau de bord de Braze, lors de l’étape de création des identifiants. Databricks n’affiche le secret qu’une seule fois.

Remarque

Databricks n’autorise pas de durée de vie illimitée pour les secrets des principaux de service. Pensez à remplacer le secret avant son expiration pour assurer la continuité du flux de données vers Braze. Pour connaître la marche à suivre, consultez Mettre à jour le secret client.

Accorder l’accès à l’entrepôt SQL

Braze a besoin de l’autorisation d’exécuter des requêtes sur votre entrepôt SQL, mais pas d’un accès administrateur à l’espace de travail.

1. Dans la barre latérale, sélectionnez SQL Warehouses, puis sélectionnez l’entrepôt que Braze doit utiliser.
2. Sélectionnez Permissions.
3. Recherchez et sélectionnez le principal de service que vous avez créé.
4. Dans le menu déroulant des autorisations, sélectionnez Can use, puis sélectionnez Add.

Accorder l’accès aux tables sources

Accordez au principal de service un accès en lecture au catalogue, au schéma et aux tables que vous avez configurés à l’étape 1. Utilisez l’ID d’application du principal de service (la même valeur que l’ID client) comme bénéficiaire.

1
2
3

GRANT USE CATALOG ON CATALOG `BRAZE-CLOUD-PRODUCTION` TO `APPLICATION_ID`;
GRANT USE SCHEMA ON SCHEMA `BRAZE-CLOUD-PRODUCTION`.INGESTION TO `APPLICATION_ID`;
GRANT SELECT ON TABLE `BRAZE-CLOUD-PRODUCTION`.INGESTION.USERS_ATTRIBUTES_SYNC TO `APPLICATION_ID`;

Remplacez APPLICATION_ID par l’ID d’application de votre principal de service. Modifiez les autres noms si nécessaire, mais les autorisations doivent correspondre à l’exemple ci-dessus.

Mettre à jour le secret client

Braze enregistre un seul secret client par identifiant. Lorsque vous le mettez à jour, toutes les sources et synchronisations qui utilisent cet identifiant basculent sur le nouveau secret. Pour remplacer le secret :

1. Dans Databricks, générez un nouveau secret pour le principal de service en suivant les étapes de la section Générer un secret client. Conservez l’ancien secret jusqu’à l’étape 6.
2. Dans le tableau de bord de Braze, accédez à Paramètres des données > Ingestion de données cloud > Identifiants, puis sélectionnez votre identifiant OAuth M2M. La section Utilisé par répertorie toutes les sources et synchronisations qui utilisent cet identifiant.
3. Mettez en pause les synchronisations qui utilisent cet identifiant, ou prévoyez la mise à jour à un moment où aucune d’entre elles n’est planifiée. Vous évitez ainsi qu’une synchronisation démarre pendant la mise à jour de l’identifiant.
4. Sélectionnez Modifier l’identifiant, saisissez le nouveau secret client, puis sélectionnez Enregistrer. La modification s’applique à toutes les sources et synchronisations qui utilisent cet identifiant.
5. Reprenez les synchronisations que vous avez mises en pause.
6. Une fois que Braze a enregistré le nouveau secret, supprimez l’ancien secret dans Databricks.

Personal access token

Braze s’authentifie à l’aide d’un jeton d’accès personnel généré dans votre espace de travail Databricks. Les identifiants existants basés sur un jeton d’accès personnel continuent de fonctionner, et vous n’avez pas besoin de les migrer. Cependant, les jetons d’accès personnels expirent souvent selon une planification définie par l’administrateur de votre espace de travail, et les synchronisations s’arrêtent dès que le jeton expire. Pour faire passer une source existante à OAuth M2M, créez des identifiants OAuth M2M, puis sélectionnez-les lorsque vous modifiez la source.

Pour créer un jeton d’accès personnel :

1. Dans votre espace de travail Databricks, sélectionnez votre nom d’utilisateur Databricks dans la barre supérieure, puis sélectionnez User Settings dans le menu déroulant.
2. Dans l’onglet Access tokens, sélectionnez Generate new token.
3. Saisissez un commentaire qui vous aide à identifier ce jeton, par exemple « Braze CDI », et supprimez la durée de vie du jeton en laissant le champ Lifetime (days) vide.
4. Sélectionnez Generate.
5. Copiez le jeton affiché, puis sélectionnez Done.

Conservez le jeton en lieu sûr jusqu’à ce que vous deviez le saisir dans le tableau de bord de Braze lors de l’étape de création des identifiants.

Étape 3 : 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 Databricks. Autorisez l’accès depuis les IP suivantes, qui correspondent à la région de votre tableau de bord de Braze.

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

Étape 4 : 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 Databricks.

Étape 4.1 : Ajouter les informations de connexion Databricks et la table source

Saisissez un nom pour votre source, puis saisissez vos identifiants et votre configuration Databricks :

• Pour Nom des identifiants, saisissez un libellé qui vous aide à identifier ces identifiants dans Braze.
• Pour Méthode d’authentification, sélectionnez la méthode que vous avez configurée à l’étape 2, puis saisissez ses identifiants. Pour OAuth M2M, saisissez Client ID and Client secret. Pour Personal access token, saisissez Access token.

Passez ensuite à l’étape suivante.

Étape 4.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.

Remarque

Vous devez tester une source avec succès avant de pouvoir la créer. Si vous fermez la page de création, votre source n’est pas enregistrée.

Étape 5 : 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.

Remarque

Vous devez valider une synchronisation avec succès avant de passer aux étapes suivantes. Si vous devez fermer la page de création de la synchronisation, sélectionnez Enregistrer comme brouillon pour conserver votre travail en cours.

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.

Remarque

Vous devez valider une intégration avec succès avant qu’elle puisse passer de l’état Brouillon à l’état Actif. Si vous fermez la page de création, votre intégration est enregistrée, et vous pouvez revenir sur la page de détails pour apporter des modifications et la valider.

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. Lorsque vous créez des synchronisations supplémentaires, vous pouvez réutiliser des identifiants existants si vous vous connectez au même compte Databricks.

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

Utiliser Databricks comme source connectée

Une source connectée est une alternative zéro copie à la synchronisation de données dans Braze. Braze interroge directement votre instance Databricks 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.

Important

Un temps de préchauffage de deux à cinq minutes peut être nécessaire lorsque Braze se connecte aux instances SQL Classic et Pro, ce qui entraîne des retards lors de la configuration et du test de la connexion, ainsi que lors de la création et de l’actualisation des extensions de segments CDI. 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.

Étape 1 : Configurer l’authentification et accorder les autorisations

Configurez des identifiants pour Braze avec l’une des méthodes décrites à l’étape 2 : Configurer l’authentification. Quelle que soit la méthode choisie, Braze utilise ces identifiants pour générer la liste des tables disponibles dans vos extensions de segments CDI et pour interroger les tables sources afin de créer de nouveaux segments. Une fois la source connectée créée, Braze détecte les noms et les descriptions de toutes les tables accessibles à l’utilisateur dans le schéma source.

Vous pouvez accorder l’accès à toutes les tables d’un schéma ou accorder des privilèges uniquement sur des tables spécifiques. Toutes les tables auxquelles le rôle Braze a accès peuvent être interrogées dans l’extension de segment CDI.

L’autorisation CREATE TABLE est requise pour que Braze puisse créer une table contenant les résultats de la requête de votre extension de segment CDI avant de mettre à jour le segment dans Braze. Braze crée une table temporaire par segment, qui n’existe que pendant la mise à jour du segment par Braze.

• OAuth M2M : Accordez au principal de service l’accès au schéma utilisé pour la source connectée, y compris CREATE TABLE. Utilisez l’ID d’application du principal de service (la même valeur que l’ID client) comme bénéficiaire.

  
  1
  2
  3
  
    GRANT USE CATALOG ON CATALOG `BRAZE-CLOUD-PRODUCTION` TO `APPLICATION_ID`;
    GRANT USE SCHEMA, CREATE TABLE ON SCHEMA `BRAZE-CLOUD-PRODUCTION`.INGESTION TO `APPLICATION_ID`;
    GRANT SELECT ON SCHEMA `BRAZE-CLOUD-PRODUCTION`.INGESTION TO `APPLICATION_ID`;
  
  

  Remplacez APPLICATION_ID par l’ID d’application de votre principal de service.

• Jeton d’accès personnel : Assurez-vous que le compte de service dispose des privilèges CREATE TABLE sur le schéma utilisé pour la source connectée.

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

É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 Databricks.

Dans Configurer la source, saisissez les informations suivantes :

• Identifiants : Nom des identifiants, Méthode d’authentification, Nom d’hôte, Chemin HTTP et les champs correspondant à votre méthode d’authentification. Pour OAuth M2M, saisissez Client ID and Client secret. Pour Personal access token, saisissez Access token.
• Configuration : Catalogue et Schéma

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 segment 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 Databricks. 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 maintenant 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 schéma différent. Lorsque vous créez des sources supplémentaires, vous pouvez réutiliser des identifiants existants si vous vous connectez au même compte Databricks.

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 Databricks pour formater les colonnes sources en champs CDI.

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

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,
        attribute_2,
        attribute_3
      )
    ) as PAYLOAD
  FROM BRAZE.EXAMPLE_USER_DATA;

Pour plus de 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. Pour Databricks, un temps de préchauffage de deux à cinq minutes peut être nécessaire lorsque Braze se connecte aux instances SQL Classic et Pro, ce qui entraîne des retards lors de la configuration et du test de la connexion, ainsi qu’au début des synchronisations planifiées. 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.

Échec de la commande, car l’entrepôt était arrêté

Si vous recevez cette erreur, assurez-vous que l’entrepôt Databricks est en cours d’exécution.

Service: Amazon S3; Status Code: 403; Error Code: 403 Forbidden

Si vous recevez cette erreur, consultez Databricks : erreur Forbidden lors de l’accès aux données S3.

Où exécuter les vérifications SQL

Exécutez les vérifications de validation directement dans l’éditeur SQL de Databricks sur un entrepôt SQL, sur la même table ou vue que celle utilisée par votre intégration CDI. Pour plus d’informations, consultez Éditeur SQL de Databricks.

Pages connexes

• Configuration de la table pour connaître les colonnes requises et le formatage du payload
• Bonnes pratiques pour la planification des synchronisations et l’utilisation efficace des points de données
• Journaux de synchronisation et observabilité pour surveiller les exécutions de synchronisation
• FAQ pour les questions fréquentes communes à toutes les sources