Bonnes pratiques

L’ingestion de données cloud de Braze vous permet d’établir une connexion directe entre votre entrepôt de données ou votre système de stockage de fichiers et Braze, afin de synchroniser les données pertinentes relatives aux utilisateurs ou aux catalogues. Lorsque vous synchronisez ces données avec Braze, vous pouvez les exploiter pour des cas d’usage tels que la personnalisation, le déclenchement ou la segmentation.

Suivre les modifications avec UPDATED_AT

Remarque

UPDATED_AT est pertinent uniquement pour les intégrations d’entrepôts de données, pas pour les synchronisations de stockage de fichiers.

Lorsqu’une synchronisation s’exécute, Braze se connecte directement à votre instance d’entrepôt de données et utilise l’horodatage UPDATED_AT de chaque ligne pour le suivi des modifications. UPDATED_AT est un champ obligatoire pour toutes les synchronisations d’entrepôts de données.

Important

CDI suit les modifications strictement en fonction des valeurs UPDATED_AT, indépendamment du fait que le contenu de la ligne soit identique à ce qui est actuellement dans Braze. Braze recommande d’utiliser UPDATED_AT pour ne synchroniser que les données nouvelles ou mises à jour, ce qui évite une consommation inutile de points de donnée.

Exemple : comportement de synchronisation récurrente

Pour illustrer comment UPDATED_AT est utilisé dans une synchronisation CDI, voici un exemple de synchronisation récurrente pour la mise à jour d’attributs utilisateur.

À chaque exécution d’une synchronisation, CDI recherche les lignes qui n’ont pas encore été synchronisées. CDI vérifie cela en utilisant la colonne UPDATED_AT de votre table ou vue. Braze sélectionne et importe toutes les lignes dont la valeur UPDATED_AT est postérieure à la dernière valeur UPDATED_AT synchronisée. Les lignes situées exactement à l’horodatage limite peuvent également être resynchronisées si de nouvelles lignes sont ajoutées avec ce même horodatage entre deux exécutions.

Important

CDI suit le nombre de lignes à la dernière valeur UPDATED_AT synchronisée. Si de nouvelles lignes sont ajoutées avec ce même horodatage entre deux exécutions, CDI passe à une limite inclusive (>=) et resynchronise toutes les lignes à cet horodatage, y compris celles déjà traitées. Pour éviter les synchronisations en double et la consommation inutile de points de donnée, utilisez des valeurs UPDATED_AT uniques entre les exécutions de synchronisation. Pour plus d’informations, consultez Éviter la resynchronisation de lignes avec des horodatages en double.

Dans votre entrepôt de données, ajoutez les utilisateurs et attributs suivants à votre table, en définissant l’heure UPDATED_AT sur l’heure à laquelle vous ajoutez ces données :

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_1",
        "attribute_b":"example_value_1"
    },
    "attribute_3":"2019-07-16T19:20:30+1:00"
}

1
2
3
4
5
6

{
    "attribute_1":"abcdefg",
    "attribute_2":42,
    "attribute_3":"2019-07-16T19:20:30+1:00",
    "attribute_5":"testing"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":true,
    "attribute_5":"testing_123"
}

Lors de la prochaine synchronisation planifiée, Braze synchronise toutes les lignes dont l’horodatage UPDATED_AT est postérieur à l’horodatage le plus récent synchronisé. Braze met à jour ou ajoute des champs, vous n’avez donc pas besoin de synchroniser l’intégralité du profil utilisateur à chaque fois. Après la synchronisation, les profils utilisateur reflètent les nouvelles mises à jour :

Synchronisation récurrente, deuxième exécution le 20 juillet 2022 à 12 h

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_2",
        "attribute_b":"example_value_2"
    },
    "attribute_3":"2019-07-16T19:20:30+1:00"
}

1
2
3
4
5
6

{
    "attribute_1":"abcdefg",
    "attribute_2":42,
    "attribute_3":"2019-07-16T19:20:30+1:00",
    "attribute_5":"testing"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":true,
    "attribute_5":"testing_123"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":false,
    "attribute_5":"testing_123"
}

Une nouvelle ligne a été ajoutée pour customer_9012, mais sa valeur UPDATED_AT (2022-07-16 00:25:30) est antérieure à l’horodatage stocké (2022-07-19 09:07:23), elle ne sera donc pas synchronisée. En revanche, la ligne existante de customer_5678 a une valeur UPDATED_AT égale à l’horodatage stocké, elle est donc resynchronisée en raison de la limite inclusive. Pour plus de détails sur ce comportement, consultez Éviter la resynchronisation de lignes avec des horodatages en double. La valeur UPDATED_AT stockée reste 2022-07-19 09:07:23.

Synchronisation récurrente, troisième exécution le 21 juillet 2022 à 12 h

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_1",
        "attribute_b":"example_value_1"
    },
    "attribute_3":"2019-07-16T19:20:30+1:00"
}

1
2
3
4
5
6

{
    "attribute_1":"abcdefg",
    "attribute_2":42,
    "attribute_3":"2019-07-16T19:20:30+1:00",
    "attribute_5":"testing"
}

1
2
3
4
5

{
    "attribute_1":"abcdefg",
    "attribute_4":true,
    "attribute_5":"testing_123"
}

1
2
3
4
5

{
    "attribute_1":"xyz",
    "attribute_4":false,
    "attribute_5":"testing_123"
}

1
2
3
4
5
6
7
8

{
    "attribute_1":"abcdefg",
    "attribute_2": {
        "attribute_a":"example_value_2",
        "attribute_b":"example_value_2"
    },
    "attribute_3":"2019-07-20T19:20:30+1:00"
}

Lors de cette troisième exécution, une nouvelle ligne a été ajoutée pour customer_1234 avec une valeur UPDATED_AT (2022-07-21 08:30:00) postérieure à l’horodatage stocké. Cette nouvelle ligne et la ligne existante de customer_5678 (dont la valeur UPDATED_AT est égale à l’horodatage stocké) sont toutes deux synchronisées. La valeur UPDATED_AT stockée est désormais définie à 2022-07-21 08:30:00.

Remarque

Les valeurs UPDATED_AT peuvent être postérieures à l’heure de début de l’exécution d’une synchronisation donnée. Cependant, cela n’est pas recommandé, car cela pousse le dernier horodatage UPDATED_AT « dans le futur » et les synchronisations suivantes ne synchroniseront pas les valeurs antérieures.

Prévenir les problèmes de types de données

Lorsque vous utilisez CDI pour synchroniser des données depuis des sources externes (telles que Databricks ou Snowflake), assurez-vous que les colonnes de votre source utilisent les bons types de données avant la synchronisation. Les problèmes courants incluent :

• Horodatages stockés sous forme de chaînes de caractères : Assurez-vous que vos colonnes de dates utilisent un type timestamp ou datetime dans votre base de données source, et non un varchar ou une chaîne de caractères.
• Nombres stockés sous forme de chaînes de caractères : Convertissez les colonnes numériques en types integer ou float dans votre requête source avant la synchronisation.
• Types incohérents entre les synchronisations : Si le type d’une colonne change entre les synchronisations, Braze peut rejeter les nouvelles données. Vérifiez que le schéma de votre source reste cohérent.

Pour forcer ou modifier les types de données des attributs personnalisés dans le tableau de bord de Braze, consultez la section Gérer les données personnalisées.

Vous pouvez mettre à jour les données utilisateur par ID externe, alias d’utilisateur, ID Braze, e-mail ou numéro de téléphone. Vous pouvez supprimer des utilisateurs par ID externe, alias d’utilisateur ou ID Braze.

Utilisez un horodatage UTC pour la colonne UPDATED_AT

La colonne UPDATED_AT doit être en UTC afin d’éviter les problèmes liés aux changements d’heure. Privilégiez les fonctions exclusivement UTC, telles que SYSDATE() au lieu de CURRENT_DATE(), dans la mesure du possible.

Éviter la re-synchronisation de lignes avec des horodatages en double

CDI suit le nombre de lignes au dernier horodatage UPDATED_AT synchronisé. Si CDI détecte que de nouvelles lignes ont été ajoutées avec ce même horodatage depuis la dernière exécution, il utilise une limite inclusive (>=) pour re-sélectionner toutes les lignes à cet horodatage, y compris celles déjà traitées. Sinon, CDI utilise une limite exclusive (>) et ne sélectionne que les lignes strictement postérieures à la dernière valeur synchronisée.

Par exemple, si une synchronisation traite cinq lignes avec UPDATED_AT = 2025-04-01 00:00:00, et qu’une sixième ligne est ajoutée ultérieurement avec le même horodatage, la synchronisation suivante détecte le changement de nombre et re-synchronise les six lignes. Cela peut entraîner des données en double et une consommation inutile de points de donnée.

Pour éviter cela :

• Si vous configurez une synchronisation avec une VIEW, n’utilisez pas CURRENT_TIMESTAMP comme valeur par défaut. Cela entraînerait la synchronisation de toutes les données à chaque exécution, car le champ UPDATED_AT serait évalué au moment de l’exécution de la requête.
• Si vous avez des pipelines ou des requêtes de longue durée qui écrivent des données dans votre table source, évitez de les exécuter en même temps qu’une synchronisation, ou évitez d’utiliser le même horodatage pour chaque ligne insérée.
• Utilisez une transaction pour écrire toutes les lignes qui partagent le même horodatage.
• Utilisez des valeurs UPDATED_AT uniques et croissantes de manière monotone pour éviter que des lignes ne soient re-sélectionnées après avoir été traitées.

Exemple : gestion des mises à jour ultérieures

Cet exemple illustre le processus général de synchronisation des données pour la première fois, puis de mise à jour des seules données modifiées (deltas) lors des mises à jour suivantes. Supposons que nous ayons une table EXAMPLE_DATA contenant des données utilisateur. Le jour 1, elle contient les valeurs suivantes :

Pour obtenir ces données dans une colonne payload, vous pouvez exécuter la requête suivante :

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

SELECT
    CURRENT_TIMESTAMP AS UPDATED_AT,
    EXTERNAL_ID AS EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT(
            'attribute_1', attribute_1,
            'attribute_2', attribute_2,
            'attribute_3', attribute_3,
            'attribute_4', attribute_4
        )
    ) AS PAYLOAD
FROM EXAMPLE_DATA;

Rien de tout cela n’ayant été synchronisé avec Braze auparavant, ajoutez l’ensemble à la table source pour CDI :

Une synchronisation s’exécute et Braze enregistre que vous avez synchronisé toutes les données disponibles jusqu’à « 2023-03-16 15:00:00 ». Ensuite, le matin du jour 2, un processus ETL s’exécute et certains champs de votre table d’utilisateurs sont mis à jour (indiqués par *) :

Vous devez maintenant ajouter uniquement les valeurs modifiées dans la table source CDI. Ces lignes peuvent être ajoutées en complément plutôt que de remplacer les anciennes. La table se présente désormais comme suit :

CDI ne synchronisera que les nouvelles lignes, de sorte que la prochaine synchronisation ne portera que sur les cinq dernières lignes.

Conseils supplémentaires

N’écrivez que les attributs nouveaux ou mis à jour pour minimiser la consommation

À chaque exécution d’une synchronisation, Braze recherche les lignes qui n’ont pas encore été synchronisées. Nous vérifions cela à l’aide de la colonne UPDATED_AT de votre table ou vue. Braze sélectionne et importe toutes les lignes dont la valeur UPDATED_AT est postérieure à la dernière valeur UPDATED_AT synchronisée, qu’elles soient identiques ou non à ce qui se trouve actuellement dans le profil utilisateur. Les lignes situées à la limite du horodatage peuvent également être resynchronisées si de nouvelles lignes partagent ce même horodatage. C’est pourquoi nous recommandons de ne synchroniser que les attributs que vous souhaitez ajouter ou mettre à jour.

La consommation de points de données avec CDI est identique à celle des autres méthodes d’ingestion comme les REST API ou les SDK. Il vous appartient donc de vous assurer que vous n’ajoutez que des attributs nouveaux ou mis à jour dans vos tables sources.

Séparez EXTERNAL_ID de la colonne payload

L’objet payload ne doit pas contenir d’ID externe ni d’autre type d’identifiant.

Supprimer un attribut

Dans une colonne payload, vous pouvez définir un attribut sur null si vous souhaitez l’omettre du profil d’un utilisateur. Si vous voulez qu’un attribut reste inchangé, ne l’envoyez pas à Braze tant qu’il n’a pas été mis à jour. Pour supprimer complètement un attribut, utilisez TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...)).

Effectuez des mises à jour incrémentielles

Effectuez des mises à jour incrémentielles de vos données afin d’éviter les écrasements involontaires lorsque des mises à jour simultanées sont effectuées.

Important

• Mises à jour d’attributs différents : dans la grande majorité des cas, si deux mises à jour ne concernent pas les mêmes attributs d’un utilisateur, elles produisent des résultats totalement indépendants. Par exemple, si vous mettez à jour l’attribut Color d’un utilisateur et que vous mettez à jour séparément son attribut Size, les deux mises à jour devraient être appliquées correctement, même si elles surviennent à quelques secondes d’intervalle.
• Mises à jour d’un même attribut : des conditions de concurrence peuvent survenir lorsque plusieurs mises à jour ciblent le même attribut au cours d’une même exécution de synchronisation. Dans ces rares cas, une mise à jour peut écraser l’autre. La meilleure façon d’éviter ce comportement est de s’assurer que les données sources de votre synchronisation CDI ne reflètent que le dernier état de chaque utilisateur, ou que toutes les mises à jour pour un utilisateur donné ou une paire utilisateur+attribut sont contenues dans une seule ligne.
• Opérateurs sur les tableaux d’objets : les seules exceptions aux mises à jour indépendantes concernent les opérateurs $add, $remove et $update pour les tableaux d’objets, où les mises à jour d’un même tableau peuvent interagir entre elles.
• Événements : les conditions de concurrence n’affectent pas les événements, car chaque événement est unique et possède un horodatage associé.

La meilleure façon d’éviter ce comportement est de s’assurer que les données sources de votre synchronisation CDI ne reflètent que le dernier état de chaque utilisateur, ou que toutes les mises à jour pour un utilisateur donné ou une paire utilisateur+attribut sont contenues dans une seule ligne.

Créer une chaîne JSON à partir d’une autre table

Si vous utilisez une colonne payload et que vous stockez chaque attribut dans sa propre colonne en interne, convertissez ces colonnes en une chaîne JSON pour remplir payload. Pour synchroniser des colonnes séparées sans construire de chaîne JSON, utilisez plutôt l’option Visuel ou SQL. Pour plus de détails, consultez Choisir une option de définition des données.

Pour construire la chaîne JSON, vous pouvez utiliser une requête comme :

• snowflake
• redshift
• bigquery
• databricks
• microsoft fabric

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

CREATE TABLE "EXAMPLE_USER_DATA"
    (attribute_1 string,
     attribute_2 string,
     attribute_3 number,
     my_user_id string);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    TO_JSON(
        OBJECT_CONSTRUCT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    )as PAYLOAD FROM "EXAMPLE_USER_DATA";

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

CREATE TABLE "EXAMPLE_USER_DATA"
    (attribute_1 string,
     attribute_2 string,
     attribute_3 number,
     my_user_id string);

SELECT
    CURRENT_TIMESTAMP as UPDATED_AT,
    my_user_id as EXTERNAL_ID,
    JSON_SERIALIZE(
        OBJECT (
            'attribute_1',
            attribute_1,
            'attribute_2',
            attribute_2,
            'yet_another_attribute',
            attribute_3)
    ) as PAYLOAD FROM "EXAMPLE_USER_DATA";

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

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

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

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;

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

CREATE TABLE [braze].[users] (
    attribute_1 VARCHAR,
    attribute_2 VARCHAR,
    attribute_3 VARCHAR,
    attribute_4 VARCHAR,
    user_id VARCHAR
)
GO

CREATE VIEW [braze].[user_update_example]
AS SELECT
    user_id as EXTERNAL_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].[users] ;

Utiliser l’horodatage UPDATED_AT

Braze utilise l’horodatage UPDATED_AT pour suivre les données qui ont été synchronisées avec succès. CDI suit également le nombre de lignes au dernier horodatage synchronisé. Si de nouvelles lignes sont ajoutées avec ce même horodatage entre deux exécutions, CDI resynchronise toutes les lignes à cet horodatage, ce qui peut entraîner des données en double. Pour plus de détails et de conseils, consultez Éviter la resynchronisation de lignes avec des horodatages en double.

Configuration des tables

Nous disposons d’un dépôt GitHub public permettant aux clients de partager des bonnes pratiques ou des extraits de code. Pour contribuer avec vos propres extraits, créez une pull request !

Formatage des données

Les exigences de configuration des tables et de formatage du payload pour l’ingestion de données cloud sont documentées dans Configuration des tables pour l’ingestion de données cloud.

Utilisez cette page pour distinguer :

• Les exigences des tables sources (colonnes requises, colonnes d’identifiants et comportement de UPDATED_AT)
• Les exigences du payload (quels champs doivent correspondre au format de l’objet /users/track pour chaque type de données)

Éviter les délais d’expiration pour les requêtes de l’entrepôt de données

Nous recommandons que les requêtes soient exécutées en moins d’une heure pour des performances optimales et pour éviter d’éventuelles erreurs. Si les requêtes dépassent ce délai, envisagez de revoir la configuration de votre entrepôt de données. L’optimisation des ressources allouées à votre entrepôt peut contribuer à améliorer la vitesse d’exécution des requêtes.

Limites du produit