Passer au contenu

Cette page a été traduite automatiquement et peut contenir des inexactitudes. Pour signaler une erreur de traduction, utilisez le module de commentaires en bas de la table des matières, à droite de la page.

Synchronisation et suppression des données du catalogue

Cette page explique comment synchroniser les données du catalogue.

Étape 1 : Créer un nouveau catalogue

Avant de créer une nouvelle intégration Cloud Data Ingestion (CDI) pour les catalogues, vous devez créer un nouveau catalogue ou identifier un catalogue existant à utiliser pour l’intégration. Il existe plusieurs façons de créer un nouveau catalogue, et chacune d’elles fonctionne pour l’intégration CDI :

Téléchargez un fichier CSV
Créez un catalogue dans le tableau de bord de Braze ou lors de la configuration de la CDI.
Créez un catalogue à l’aide de l’endpoint de création de catalogue

Toute modification du schéma du catalogue (par exemple, l’ajout de nouveaux champs ou la modification du type d’un champ) doit être effectuée dans le tableau de bord du catalogue avant que les données mises à jour ne soient synchronisées via la CDI. Nous vous recommandons d’effectuer ces mises à jour lorsque la synchronisation est en pause ou qu’aucune exécution n’est planifiée, afin d’éviter les conflits entre les données de votre entrepôt de données et le schéma dans Braze.

Étape 2 : Intégrer l’ingestion de données cloud avec les données de catalogue

La configuration d’une synchronisation de catalogue suit de près le processus des intégrations CDI de données utilisateur.

Configurez une table source dans Snowflake. Vous pouvez reprendre les noms de l’exemple suivant ou choisir vos propres noms de base de données, de schéma et de table. Vous pouvez également utiliser une vue ou une vue matérialisée au lieu d’une table.

 CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
 CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
 CREATE OR REPLACE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC (
      UPDATED_AT TIMESTAMP_NTZ(9) NOT NULL DEFAULT SYSDATE(),
      --ID of the catalog item to be created or updated
      ID VARCHAR(16777216) NOT NULL,
      --Catalog fields and values that should be added or updated
      payload VARCHAR(16777216) NOT NULL,
      --The catalog item associated with this ID should be deleted
      DELETED BOOLEAN
 );

Configurez un rôle, un entrepôt et un utilisateur, puis accordez les autorisations appropriées. Si vous disposez déjà d’identifiants issus d’une synchronisation existante, vous pouvez les réutiliser, mais veillez à étendre l’accès à la table source du catalogue.

 CREATE ROLE BRAZE_INGESTION_ROLE;

 GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
 GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
 GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC TO ROLE BRAZE_INGESTION_ROLE;

 CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
 GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;

 CREATE USER BRAZE_INGESTION_USER;
 GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

Dans cet exemple, l’instruction CREATE USER concerne l’authentification par paire de clés RSA. Pour la fédération d’identité de charge de travail (Workload Identity Federation), créez le rôle et l’entrepôt comme indiqué, puis créez l’utilisateur de service à partir du formulaire d’identifiants Snowflake. Les autorisations sur le rôle, l’entrepôt et la base de données restent les mêmes. Si votre compte utilise une politique réseau, la liste d’autorisation de l’étape suivante s’applique toujours. Pour connaître l’instruction et savoir où l’exécuter, consultez Configurer Snowflake pour la fédération d’identité de charge de travail.

Si votre compte Snowflake applique des politiques réseau, ajoutez les IP de Braze à la liste d’autorisation afin que le service CDI puisse se connecter. Pour obtenir la liste des IP, consultez la page Ingestion de données cloud.
Dans le tableau de bord de Braze, accédez à Partenaires technologiques > Snowflake, puis créez une nouvelle synchronisation.
Saisissez les informations de connexion (ou réutilisez des identifiants existants) ainsi que la table source.
Passez à l’étape 2 du flux de configuration, sélectionnez le type de synchronisation « Catalogues », puis saisissez le nom de l’intégration et la planification. Notez que le nom de l’intégration doit correspondre exactement au nom du catalogue que vous avez créé précédemment.
Choisissez une fréquence de synchronisation et passez à l’étape suivante.
Pour une paire de clés RSA, ajoutez la clé publique affichée dans le tableau de bord à l’utilisateur que vous avez créé pour permettre à Braze de se connecter à Snowflake. Pour réaliser cette étape, vous avez besoin d’une personne disposant d’un accès SECURITYADMIN ou supérieur dans Snowflake. Pour la fédération d’identité de charge de travail, vous avez déjà exécuté l’instruction depuis le formulaire d’identifiants.
Sélectionnez Tester la connexion pour vérifier que tout fonctionne comme prévu.
Enregistrez la synchronisation, puis utilisez les données de catalogue synchronisées pour tous vos cas d’usage de personnalisation.

Configurez une table source dans Redshift. Vous pouvez reprendre les noms de l’exemple suivant ou choisir vos propres noms de base de données, de schéma et de table. Vous pouvez également utiliser une vue ou une vue matérialisée au lieu d’une table.

 CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
 CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;
 CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC (
    updated_at timestamptz default sysdate not null,
    --ID of the catalog item to be created or updated
    id varchar not null,
    --Catalog fields and values that should be added or updated
    payload varchar(max),
    --The catalog item associated with this ID should be deleted
    deleted boolean
 )

Configurez un utilisateur et accordez les autorisations appropriées. Si vous disposez déjà d’identifiants issus d’une synchronisation existante, vous pouvez les réutiliser, mais veillez à étendre l’accès à la table source du catalogue.

 CREATE USER braze_user PASSWORD '{password}';
 GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION to braze_user;
 GRANT SELECT ON TABLE CATALOGS_SYNC TO braze_user;

Si vous utilisez un pare-feu ou d’autres politiques réseau, vous devez accorder à Braze un accès réseau à votre instance Redshift. Autorisez l’accès depuis les IP correspondant à la région de votre tableau de bord de Braze. Pour obtenir la liste des IP, consultez la page Ingestion de données cloud.

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;

Créez une ou plusieurs tables à utiliser pour votre intégration CDI avec les champs suivants :

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

Configurez un utilisateur et accordez les autorisations appropriées. Si vous disposez déjà d’identifiants issus d’une synchronisation existante, vous pouvez les réutiliser—mais veillez à étendre l’accès à la table source du catalogue. 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 lister 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 tâches
  
  Après avoir créé le compte de service et accordé les autorisations, configurez la manière dont Braze s’authentifie en tant que compte de service. Utilisez la fédération d’identité de charge de travail pour ne pas avoir à créer de clé, ou générez une clé JSON. Pour en savoir plus sur les clés JSON, consultez Créer et supprimer des clés. Si vous générez une clé JSON, vous la téléchargerez plus tard dans le tableau de bord de Braze.

Si des politiques réseau sont en place, vous devez accorder à Braze un accès réseau à votre instance BigQuery. Pour obtenir la liste des IP, consultez la page Ingestion de données cloud.

Configurez une table source dans Databricks. Vous pouvez reprendre les noms de l’exemple suivant ou choisir vos propres noms de catalogue, de schéma et de table. Vous pouvez également utiliser une vue ou une vue matérialisée au lieu d’une table.

CREATE SCHEMA BRAZE-CLOUD-PRODUCTION.INGESTION;

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

Créez des identifiants pour Braze. Braze recommande OAuth de machine à machine (M2M) avec un principal de service, mais vous pouvez aussi utiliser un jeton d’accès personnel. Si vous disposez déjà d’identifiants issus d’une synchronisation existante, vous pouvez les réutiliser, mais veillez à étendre l’accès à la table source du catalogue.

OAuth M2M : Créez un principal de service, générez un secret client, accordez au principal de service l’autorisation Can use sur votre entrepôt SQL, puis accordez-lui SELECT sur la table source du catalogue. Pour connaître les étapes, consultez Créer des identifiants pour Braze.

Jeton d’accès personnel :

a. Sélectionnez votre nom d’utilisateur Databricks, puis sélectionnez User Settings dans le menu déroulant.
b. Dans l’onglet Access tokens, sélectionnez Generate new token.
c. Saisissez un commentaire qui vous aidera à identifier ce jeton, par exemple « Braze CDI ».
d. Supprimez la durée de vie du jeton en laissant vide le champ Lifetime (days). Sélectionnez Generate.
e. Copiez le jeton affiché, puis sélectionnez Done.
f. Conservez le jeton en lieu sûr jusqu’à ce que vous deviez le saisir lors de l’étape de création des identifiants dans le tableau de bord de Braze.

Si des politiques réseau sont en place, vous devez accorder à Braze un accès réseau à votre instance Databricks. Pour obtenir la liste des IP, consultez la page Ingestion de données cloud.

Créez une ou plusieurs tables à utiliser pour votre intégration CDI avec les champs suivants :

CREATE OR ALTER TABLE [warehouse].[schema].[CDI_table_name]
(
  UPDATED_AT DATETIME2(6) NOT NULL,
  PAYLOAD VARCHAR NOT NULL,
  ID VARCHAR NOT NULL,
  DELETED BIT
)
GO

Configurez un principal de service et accordez les autorisations appropriées. Si vous disposez déjà d’identifiants issus d’une synchronisation existante, vous pouvez les réutiliser—veillez simplement à étendre l’accès à la table source du catalogue. Pour savoir comment créer un nouveau principal de service et ses identifiants, consultez la page Ingestion de données cloud.

Si des politiques réseau sont en place, vous devez accorder à Braze un accès réseau à votre instance Microsoft Fabric. Pour obtenir la liste des IP, consultez la page Ingestion de données cloud.

Créez des fichiers sources dans S3 au format JSON ou CSV. Chaque fichier doit inclure les champs suivants :

Champ	Obligatoire ?	Description
`ID`	Oui	L’ID de l’élément de catalogue à créer ou à mettre à jour.
`payload`	Oui	Une chaîne de caractères JSON contenant les champs à synchroniser avec l’élément de catalogue dans Braze.
`DELETED`	Facultatif	Lorsque ce champ est défini sur `true`, l’élément de catalogue correspondant est supprimé du catalogue.
`UPDATED_AT`	Non pris en charge	Le stockage de fichiers ne prend pas en charge les colonnes `UPDATED_AT`.

Remarque

Les noms de fichiers doivent respecter les règles d’AWS et être uniques. Ajoutez-y des horodatages pour garantir leur unicité.

La configuration complète de S3 nécessite un compartiment S3, une file d’attente Amazon SQS ainsi qu’un rôle et une politique AWS IAM. Braze ne traite que les fichiers téléchargés après la création de la synchronisation : téléchargez donc à nouveau les fichiers existants que vous souhaitez ingérer.

Pour suivre l’ensemble du processus de configuration de S3, consultez Intégrations de stockage de fichiers, en particulier :

Pour les problèmes courants de notification et d’autorisation côté AWS, consultez Accorder des autorisations pour publier des messages de notification d’événement vers une destination.

Les exemples suivants présentent des formats JSON et CSV valides pour synchroniser des données de catalogue depuis un stockage de fichiers.

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

Important

Chaque ligne de votre fichier source doit contenir du JSON valide, sinon le fichier est ignoré.

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

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

Pour d’autres exemples de fichiers, consultez Intégrations de stockage de fichiers.

Fonctionnement de l’intégration

Remarque

Les vues de synchronisation présentées dans cette section s’appliquent uniquement aux intégrations d’entrepôt de données. Pour le stockage de fichiers S3, Braze traite les nouveaux fichiers au fur et à mesure de leur téléchargement dans votre compartiment. Pour plus de détails, consultez la section Intégrations de stockage de fichiers.

À chaque exécution de la synchronisation, Braze récupère toutes 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. Nous vous recommandons de créer une vue dans votre entrepôt de données à partir des données de votre catalogue afin de configurer une table source qui sera entièrement actualisée à chaque synchronisation. Grâce aux vues, vous n’aurez pas besoin de réécrire la requête à chaque fois.

Par exemple, si vous disposez d’une table de données produit (product_catalog_1) avec product_id et trois attributs supplémentaires, vous pouvez synchroniser la vue suivante :

CREATE VIEW BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS
SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    product_id as id,
    TO_JSON(
        OBJECT_CONSTRUCT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'attribute_3',
            attribute_3)
    )as PAYLOAD FROM "product_catalog_1";

CREATE TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.CATALOGS_SYNC AS
SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    Product_id as id,
    JSON_SERIALIZE(
        OBJECT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'attribute_3',
            attribute_3)
    ) as PAYLOAD FROM "product_catalog_1";

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

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

CREATE VIEW [braze].[user_update_example]
AS SELECT
    id as ID,
    CURRENT_TIMESTAMP as UPDATED_AT,
    JSON_OBJECT('attribute_1':attribute_1, 'attribute_2':attribute_2, 'attribute_3':attribute_3, 'attribute_4':attribute_4) as PAYLOAD

FROM [braze].[product_catalog] ;

Les données récupérées depuis l’intégration servent à créer ou à mettre à jour des éléments dans le catalogue cible, en fonction de l’id fourni.
Si DELETED est défini sur true, l’élément de catalogue correspondant sera supprimé.
La synchronisation n’enregistre pas de points de données, mais toutes les données synchronisées sont prises en compte dans l’utilisation totale de votre catalogue. Cette utilisation est mesurée en fonction du volume total de données stockées : vous n’avez donc pas à vous soucier de ne synchroniser que les données modifiées.

New Stuff!