Aperçu de l’ingestion de données cloud (CDI) dans Braze

L’ingestion de données dans le 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 synchronisées avec Braze, ces données peuvent être exploitées pour des cas d’utilisation tels que la personnalisation, le déclenchement ou la segmentation.

Fonctionnement

Avec Braze Cloud Data Ingestion (CDI), vous configurez une intégration entre votre instance d’entrepôt de données et l’espace de travail Braze pour synchroniser les données de manière récurrente. Cette synchronisation se fait selon la planification que vous déterminez et chaque intégration peut disposer d’une planification différente. Les synchronisations peuvent avoir lieu d’une fois toutes les 15 minutes à une fois par mois. Les clients ayant besoin d’une synchronisation plus fréquente que toutes les 15 minutes peuvent contacter leur gestionnaire du succès des clients ou envisager d’utiliser les appels API REST pour une ingestion de données en temps réel.

Lorsqu’une synchronisation s’exécute, Braze se connecte directement à votre instance d’entrepôt de données, récupère toutes les nouvelles données de la table spécifiée et met à jour les données correspondantes sur votre tableau de bord de Braze. Chaque fois que la synchronisation s’exécute, toute donnée mise à jour est reflétée dans Braze.

Sources de données prises en charge

L’ingestion de données dans le nuage peut synchroniser les données des sources suivantes avec Braze :

• Sources de l’entrepôt de données
  • Amazon Redshift
  • Databricks
  • Google BigQuery
  • Snowflake
• Sources de stockage de fichiers
  • Amazon S3

Types de données prises en charge

L’ingestion de données dans le nuage prend en charge les types de données suivants :

• Attributs de l’utilisateur, y compris :
  • Attributs personnalisés imbriqués
  • Tableaux d’objets
  • État des abonnements
• Événements personnalisés
• Événements d’achat
• Articles de catalogue
• Demandes de suppression d’un utilisateur

Les données de l’utilisateur peuvent être mises à jour par ID externe, alias d’utilisateur, ID Braze, e-mail ou numéro de téléphone. Les utilisateurs peuvent être supprimés par ID externe, alias d’utilisateur ou ID Braze.

Qu’est-ce qui est synchronisé

Chaque fois qu’une synchronisation a lieu, Braze cherchera les lignes qui n’ont pas déjà été synchronisées. Nous le vérifions en utilisant la colonne UPDATED_AT dans votre table ou votre affichage. Chaque ligne dans laquelle UPDATED_AT est plus ancien que la dernière synchronisation, la ligne sera sélectionnée et transmise à Braze.

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

Pendant la prochaine synchronisation planifiée, toutes les lignes possédant un horodatage UPDATED_AT plus ancien que l’horodatage le plus récent seront synchronisées aux profils utilisateurs de Braze. Les champs seront mis à jour ou ajoutés et vous n’aurez donc pas besoin de synchroniser le profil utilisateur tout entier à chaque fois. Après la synchronisation, les utilisateurs afficheront les nouvelles mises à jour :

1
2
3
4
5
6
7
8
9
10
11
12
{
  "external_id":"customer_1234",
  "email":"jane@example.com",
  "attribute_1":"abcdefg",
  "attribute_2":{
        "attribute_a":"example_value_1",
        "attribute_b":"example_value_2"
    },
  "attribute_3":"2019-07-16T19:20:30+1:00",
  "attribute_4":false,
  "attribute_5":"testing"
}

1
2
3
4
5
6
7
8
9
{
  "external_id":"customer_3456",
  "email":"michael@example.com",
  "attribute_1":"abcdefg",
  "attribute_2":42,
  "attribute_3":"2019-07-16T19:20:30+1:00",
  "attribute_4":true,
  "attribute_5":"testing"
}

1
2
3
4
5
6
7
8
9
{
  "external_id":"customer_5678",
  "email":"bob@example.com",
  "attribute_1":"abcdefg",
  "attribute_2":42,
  "attribute_3":"2017-08-10T09:20:30+1:00",
  "attribute_4":true,
  "attribute_5":"testing_123"
}

Cas d’utilisation : Première synchronisation et mises à jour ultérieures

Cet exemple montre le processus général de synchronisation des données pour la première fois, puis la mise à jour des seules données changeantes (deltas) dans les mises à jour ultérieures. Supposons que nous ayons une table EXAMPLE_DATA contenant des données utilisateur. Le jour 1, il présente les valeurs suivantes :

Pour obtenir ces données dans le format attendu par CDI, 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 tout cela à 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 deuxième jour, vous avez un processus ETL qui s’exécute et certains champs de votre table d’utilisateurs sont mis à jour (en surbrillance) :

Vous devez maintenant ajouter uniquement les valeurs modifiées dans le tableau source CDI. Ces lignes peuvent être ajoutées plutôt que de mettre à jour les anciennes lignes. Ce tableau 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.

Cas d’utilisation : Mettre à jour un champ dans un tableau d’objets existant

Cet exemple montre comment mettre à jour un champ dans un tableau d’objets existant. Supposons que nous ayons un tableau source avec la définition suivante :

1
2
3
4
5
6
7
8
Create table BRAZE_CLOUD_INGESTION_DEMO.BRAZE_SCHEMA.pet_list (
    pet_id int IDENTITY(1,1), 
    breed VARCHAR, 
    type VARCHAR, 
    name VARCHAR, 
    owner_id VARCHAR, 
    age int
);

Dans cet exemple, nous voulons ajouter un tableau des animaux de compagnie appartenant à chaque utilisateur, ce qui correspond à owner_id. Plus précisément, nous voulons inclure l’identification, la race, le type et le nom. Nous pouvons utiliser la requête suivante pour remplir une table ou une vue :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
SELECT 
CURRENT_TIMESTAMP as UPDATED_AT,
owner_id as EXTERNAL_ID,
TO_JSON(
    OBJECT_CONSTRUCT(
        '_merge_objects','true',
       'pets',
        OBJECT_CONSTRUCT(
           '$add', ARRAY_AGG( OBJECT_CONSTRUCT(
                'id',
                pet_id,
                'breed',
                breed,
                'type',
                type,
                'name',
                name
                )) WITHIN GROUP (ORDER BY type ASC)    
        )
    )
)
as PAYLOAD from BRAZE_CLOUD_INGESTION_DEMO.BRAZE_SCHEMA.pet_list group by EXTERNAL_ID;

Le résultat attendu serait le suivant :

1
2
3
4
UPDATED_AT	EXTERNAL_ID	PAYLOAD
2023-10-02 19:56:17.377 +0000	03409324	{"_merge_objects":"true","pets":{"$add":[{"breed":"parakeet","id":5,"name":"Mary","type":"bird"}]}}
2023-10-02 19:56:17.377 +0000	21231234	{"_merge_objects":"true","pets":{"$add":[{"breed":"calico","id":2,"name":"Gerald","type":"cat"},{"breed":"beagle","id":1,"name":"Gus","type":"dog"}]}}
2023-10-02 19:56:17.377 +0000	12335345	{"_merge_objects":"true","pets":{"$add":[{"breed":"corgi","id":3,"name":"Doug","type":"dog"},{"breed":"salmon","id":4,"name":"Larry","type":"fish"}]}}

Ensuite, pour envoyer un champ de nom mis à jour et un nouveau champ d’âge pour chaque propriétaire, nous pouvons utiliser la requête suivante pour remplir une table ou une vue :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
SELECT 
CURRENT_TIMESTAMP as UPDATED_AT,
owner_id as EXTERNAL_ID,
TO_JSON(
    OBJECT_CONSTRUCT(
        '_merge_objects','true',
       'pets',
        OBJECT_CONSTRUCT(
           '$update', ARRAY_AGG( OBJECT_CONSTRUCT(
                '$identifier_key','id',
                '$identifier_value',pet_id,
                '$new_object',OBJECT_CONSTRUCT(
                    'name',name,
                    'age',age
                )
                )) WITHIN GROUP (ORDER BY type ASC)    
        )
    )
)
as PAYLOAD from BRAZE_CLOUD_INGESTION_DEMO.BRAZE_SCHEMA.pet_list group by EXTERNAL_ID; 

Le résultat attendu serait le suivant :

1
2
3
4
UPDATED_AT	EXTERNAL_ID	PAYLOAD
2023-10-02 19:50:25.266 +0000	03409324	{"_merge_objects":"true","pets":{"$update":[{"$identifier_key":"id","$identifier_value":5,"$new_object":{"age":7,"name":"Mary"}}]}}
2023-10-02 19:50:25.266 +0000	21231234	{"_merge_objects":"true","pets":{"$update":[{"$identifier_key":"id","$identifier_value":2,"$new_object":{"age":3,"name":"Gerald"}},{"$identifier_key":"id","$identifier_value":1,"$new_object":{"age":3,"name":"Gus"}}]}}
2023-10-02 19:50:25.266 +0000	12335345	{"_merge_objects":"true","pets":{"$update":[{"$identifier_key":"id","$identifier_value":3,"$new_object":{"age":6,"name":"Doug"}},{"$identifier_key":"id","$identifier_value":4,"$new_object":{"age":1,"name":"Larry"}}]}}

Utilisation de points de données

La facturation des points de données pour Cloud Data Ingestion équivaut à la facturation des mises à jour via l’endpoint /users/track. Pour plus d’informations, reportez-vous à la section Points de données.

Recommandations pour la configuration des données

N’écrivez que les attributs nouveaux ou mis à jour pour limiter l’utilisation

Chaque fois qu’une synchronisation a lieu, Braze cherchera les lignes qui n’ont pas déjà été synchronisées. Nous le vérifions en utilisant la colonne UPDATED_AT dans votre table ou votre affichage. Toutes les lignes pour lesquelles UPDATED_AT est postérieur à la dernière ligne synchronisée seront sélectionnées et transférées dans Braze, qu’elles soient ou non identiques à celles figurant actuellement dans le profil utilisateur. Voilà pourquoi nous recommandons de ne synchroniser que les attributs que vous voulez ajouter ou mettre à jour.

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

Utilisez un horodatage UTC pour la colonne UPDATED_AT

La colonne UPDATED_AT devrait être en UTC pour éviter les problèmes liés aux heures d’été. Utilisez de préférence des fonctions uniquement en UTC, telles que SYSDATE() plutôt que CURRENT_DATE() dès que possible.

Assurez-vous que l’heure de UPDATED_AT n’est pas la même que celle de votre synchronisation.

Votre synchronisation CDI peut contenir des données en double si l’un des champs UPDATED_AT se trouve exactement à la même heure que votre synchronisation précédente. En effet, l’IDC choisira une “limite inclusive” lorsqu’il repérera une ligne qui se situe à la même heure que la synchronisation précédente, et rendra les lignes viables à synchroniser. Le CDI réintègre ces lignes et crée des données en double.

Séparer la colonne EXTERNAL_ID de la colonne PAYLOAD

L’objet PAYLOAD ne doit pas comporter d’ID externe ou d’autre type d’ID.

Supprimer un attribut

Vous pouvez lui attribuer la valeur null si vous souhaitez omettre un attribut dans le profil d’un utilisateur. Si vous désirez qu’un attribut reste inchangé, ne l’envoyez pas à Braze jusqu’à ce qu’il ait été mis à jour. Pour supprimer complètement un attribut, utilisez TO_JSON(OBJECT_CONSTRUCT_KEEP_NULL(...)).

Effectuer des mises à jour incrémentielles

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

Dans l’exemple suivant, un utilisateur possède deux attributs :

• Couleur : “Vert”
• Taille : “Grand”

Braze reçoit alors simultanément les deux mises à jour suivantes pour cet utilisateur :

• Demande 1 : Changer la couleur en “Rouge”
• Demande 2 : Modifier la taille en “Moyen”

La demande 1 étant la première, les attributs de l’utilisateur sont mis à jour comme suit :

• Couleur : “Rouge”
• Taille : “Grand”

Cependant, lorsque la demande 2 se produit, Braze commence par les valeurs d’attribut originales (“Vert” et “Grand”), puis met à jour les attributs de l’utilisateur de la manière suivante :

• Couleur : “Vert”
• Taille : “Moyen”

Lorsque les demandes sont terminées, la demande 2 écrase la mise à jour de la demande 1. Pour cette raison, il est préférable d’échelonner vos mises à jour afin d’éviter que les demandes ne soient écrasées.

Créer une chaîne de caractères JSON depuis une autre table

Si vous préférez stocker de manière interne chaque attribut dans sa propre colonne, vous devez convertir ces colonnes en chaîne de caractères JSON pour remplir la synchronisation avec Braze. Pour ce faire, vous pouvez utiliser une requête du type :

• snowflake
• redshift
• bigquery
• databricks

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;

Utilisez l’horodatage UPDATED_AT

Nous utilisons l’horodatage UPDATED_AT pour suivre quelles données ont été synchronisées avec succès dans Braze. Si de nombreuses rangées sont écrites avec le même horodatage pendant qu’une synchronisation est en cours, ceci peut entraîner la synchronisation de données en double dans Braze. Voici quelques conseils pour éviter des données en double :

• Si vous mettez en place une synchronisation contre une VIEW, n’utilisez pas CURRENT_TIMESTAMP comme valeur de base. Ceci entraînera la synchronisation de toutes les données chaque fois qu’elle s’effectue, car le champ UPDATED_AT sera évalué à chaque fois que nos requêtes sont lancées.
• Si vous avez des flux de données à très longue durée d’exécution ou des requêtes écrivant des données dans votre table source, évitez de les exécuter en même temps que la synchronisation ou évitez d’utiliser le même horodatage pour chaque ligne insérée.
• Utilisez une transaction pour écrire toutes les rangées qui ont le même horodatage.

Configuration de la table

Nous disposons d’un référentiel GitHub public permettant aux clients de partager des bonnes pratiques ou des extraits de code. Pour contribuer avec vos propres extraits de code, créez une requête d’extraction !

Formatage des données

Toutes les opérations possibles via l’endpoint de Braze /users/track sont prises en charge par l’ingestion de données dans le nuage, notamment la mise à jour des attributs personnalisés imbriqués, l’ajout d’un statut d’abonnement et la synchronisation d’événements personnalisés ou d’achats.

Les champs de la charge utile doivent respecter le même format que l’endpoint /users/track correspondant. Pour plus d’informations sur les exigences en matière de formatage, reportez-vous à ce qui suit :

Notez la nécessité de capturer les dates dans les attributs imbriqués.

• attributs personnalisés imbriqués
• événement
• achat
• groupes d’abonnement

1
2
3
4
5
6
7
8
9
10
11
12
{
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "genre": "Jazz",
        "play_analytics": {
            "count": 1000,
            "top_10_listeners": true
        }
      }
}

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": "Dan Alexander"
    }
} 

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
    "subscription_groups" : [
        {
            "subscription_group_id": "subscription_group_identifier_1",
            "subscription_state": "unsubscribed"
        },
        {
            "subscription_group_id": "subscription_group_identifier_2",
            "subscription_state": "subscribed"
        },
        {
            "subscription_group_id": "subscription_group_identifier_3",
            "subscription_state": "subscribed"
        }
      ]
}

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

Nous vous recommandons d’effectuer les requêtes dans un délai d’une heure afin d’optimiser les performances et d’éviter les erreurs potentielles. 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