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. Une fois ces données synchronisé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.

Éviter les problèmes de type de données

Lorsque vous utilisez le CDI pour synchroniser des données provenant de sources externes (comme Databricks ou Snowflake), vérifiez que les colonnes sources utilisent les bons types de données avant la synchronisation. Voici les problèmes les plus courants :

• Horodatages stockés sous forme de chaînes de caractères : Vos colonnes de date doivent utiliser un type timestamp ou datetime dans votre base de données source, et non un type varchar ou string.
• Nombres stockés sous forme de chaînes de caractères : Convertissez les colonnes numériques en type integer ou float dans votre requête source avant la synchronisation.
• Types incohérents d’une synchronisation à l’autre : Si le type d’une colonne change entre deux 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 Gérer les données personnalisées.

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

Utiliser un horodatage UTC pour la colonne UPDATED_AT

La colonne UPDATED_AT doit être en UTC afin d’éviter les problèmes liés à l’heure d’été. Dans la mesure du possible, privilégiez les fonctions exclusivement UTC, par exemple SYSDATE() plutôt que CURRENT_DATE().

É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 limiter la consommation

À chaque synchronisation, Braze recherche les lignes qui n’ont pas encore été synchronisées. Pour cela, nous utilisons la colonne UPDATED_AT de votre table ou de votre 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, même si elles sont identiques aux données figurant déjà dans le profil utilisateur. Les lignes correspondant à l’horodatage limite peuvent aussi être resynchronisées si de nouvelles lignes partagent cet horodatage. Nous vous recommandons donc de ne synchroniser que les attributs que vous souhaitez ajouter ou mettre à jour.

La consommation de points de donnée est la même avec CDI qu’avec d’autres méthodes d’ingestion comme les API REST ou les SDK. C’est donc à vous de veiller à n’ajouter 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’ID.

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(...)).

Effectuer des mises à jour incrémentielles

Mettez à jour vos données de manière incrémentielle pour éviter les écrasements involontaires lorsque plusieurs mises à jour ont lieu simultanément.

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, leurs résultats sont totalement indépendants. Par exemple, si vous mettez à jour l’attribut Color d’un utilisateur, puis son attribut Size séparément, les deux mises à jour devraient être appliquées correctement, même si elles surviennent à quelques secondes d’intervalle.
• Mises à jour du même attribut : Des conditions de concurrence peuvent survenir lorsque plusieurs mises à jour ciblent le même attribut au cours d’une même synchronisation. Dans ces rares cas, une mise à jour peut en écraser une autre. Le meilleur moyen d’éviter ce comportement est de veiller à ce que les données sources de votre synchronisation CDI ne reflètent que l’état le plus récent de chaque utilisateur, ou que toutes les mises à jour pour un utilisateur donné ou une paire utilisateur+attribut soient regroupées dans une seule ligne.
• Opérateurs de tableaux d’objets : Les seules exceptions à l’indépendance des mises à jour concernent les opérateurs $add, $remove et $update pour les tableaux d’objets : les mises à jour d’un même tableau peuvent alors interagir entre elles.
• Événements : Les conditions de concurrence n’affectent pas les événements, car chaque événement est unique et associé à un horodatage.

Le meilleur moyen d’éviter ce comportement est de veiller à ce que les données sources de votre synchronisation CDI ne reflètent que l’état le plus récent de chaque utilisateur, ou que toutes les mises à jour pour un utilisateur donné ou une paire utilisateur+attribut soient regroupées 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 en interne chaque attribut dans sa propre colonne, convertissez ces colonnes en chaîne JSON pour alimenter payload. Pour synchroniser des colonnes séparées sans construire de chaîne JSON, utilisez plutôt l’option Visuel ou SQL. Pour en savoir plus, consultez Choisir une option de définition des données.

Chaque page de source propose un exemple concret dans le dialecte SQL de l’entrepôt concerné :

• Snowflake
• Amazon Redshift
• Google BigQuery
• Databricks
• Microsoft Fabric

Par exemple, dans Snowflake :

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

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 correspondant au dernier horodatage synchronisé. Si de nouvelles lignes portant ce même horodatage sont ajoutées entre deux exécutions, CDI resynchronise toutes les lignes correspondant à cet horodatage, ce qui peut entraîner des doublons. Pour plus de détails et de conseils, consultez Éviter la resynchronisation de lignes aux horodatages en double.

Configuration des tables

Nous mettons à disposition un dépôt GitHub public permettant aux clients de partager leurs 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 Cloud Data Ingestion sont décrites dans Configuration des tables pour Cloud Data Ingestion.

Consultez cette page pour distinguer :

• Les exigences relatives à la table source (colonnes obligatoires, colonnes d’identifiant et comportement de UPDATED_AT)
• Les exigences relatives au payload (champs devant respecter le format d’objet /users/track pour chaque type de données)

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

Nous recommandons que les requêtes s’exécutent en moins d’une heure pour garantir des performances optimales et éviter d’éventuelles erreurs. Si vos requêtes dépassent ce délai, pensez à revoir la configuration de votre entrepôt de données. Optimiser les ressources allouées à votre entrepôt peut contribuer à accélérer l’exécution des requêtes.

Limites du produit