Aperçu de Braze Cloud Data Ingestion

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éclencheur ou la segmentation.

Comment cela fonctionne-t-il ?

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 s’effectue selon une planification que vous définissez, et chaque intégration peut avoir une planification différente. Les synchronisations peuvent être effectuées aussi fréquemment que toutes les 15 minutes ou aussi rarement qu’une fois par mois. Si vous avez besoin que les synchronisations se produisent à une fréquence supérieure à 15 minutes, contactez votre gestionnaire de satisfaction client ou envisagez d’utiliser les appels API REST pour l’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 sera 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
  • Les banques de données
  • Google BigQuery
  • Microsoft Fabric
  • Snowflake
• Sources de stockage de fichiers
  • Amazon S3

Types de données pris 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
  • Statut de l’abonnement
• Événements personnalisés
• Achat d’événements
• 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.

Ce qui est synchronisé

Chaque fois qu’une synchronisation est exécutée, Braze recherche les lignes qui n’ont pas encore été synchronisées. Nous le vérifions à l’aide de la colonne UPDATED_AT de votre tableau ou de votre vue. Toutes les lignes pour lesquelles UPDATED_AT est égal ou postérieur au dernier horodatage UPDATED_AT du dernier travail de synchronisation réussi seront sélectionnées et transférées dans Braze.

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

Lors de la prochaine synchronisation planifiée, toutes les lignes dont l’horodatage UPDATED_AT est égal ou postérieur à l’horodatage le plus récent seront synchronisées avec les profils utilisateurs de Braze. Les champs seront mis à jour ou ajoutés, de sorte que vous n’avez pas besoin de synchroniser le profil utilisateur complet à chaque fois. Après la synchronisation, les utilisateurs refléteront les nouvelles mises à jour :

1
2
3
4
5
6
7
8
9
10
11
12
{
  "external_id":"customer_1234",
  "email":"[email protected]",
  "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":"[email protected]",
  "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":"[email protected]",
  "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 d’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’a été synchronisé avec Braze auparavant, alors ajoutez tout cela à la table source pour le 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 extraire 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 des points de données

La facturation des points de données pour l’ingestion de données dans le nuage équivaut à la facturation des mises à jour via le point d’extrémité/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 afin de minimiser la consommation

Chaque fois qu’une synchronisation est exécutée, Braze recherche les lignes qui n’ont pas encore été synchronisées. Nous le vérifions à l’aide de la colonne UPDATED_AT de votre tableau ou de votre vue. Toutes les lignes pour lesquelles UPDATED_AT est égal ou postérieur au dernier horodatage UPDATED_AT du dernier travail de synchronisation réussi seront sélectionnées et intégrées à Braze, qu’elles correspondent ou non au profil utilisateur actuel. Nous vous recommandons donc de ne synchroniser que les attributs que vous souhaitez ajouter ou mettre à jour.

L’utilisation des points de données est identique avec CDI qu’avec d’autres méthodes d’ingestion comme les API REST 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.

Utilisez un horodatage UTC pour la colonne UPDATED_AT

La colonne UPDATED_AT doit être en UTC pour éviter les problèmes liés à l’heure d’été. Préférez les fonctions UTC uniquement, telles que SYSDATE() au lieu de CURRENT_DATE() dans la mesure du 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 est exactement à la même heure que le dernier horodatage UPDATED_AT de la précédente synchronisation réussie. En effet, CDI choisira une “limite inclusive” lorsqu’il identifiera une ligne qui se trouve à la même heure que la synchronisation précédente, et fera en sorte que les lignes puissent se synchroniser. CDI ré-ingère 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 souhaitez 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

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. Il est donc 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 à partir d’une autre table

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. Pour ce faire, vous pouvez utiliser une requête telle que :

• 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] ;

Utilisez l’horodatage UPDATED_AT

Nous utilisons l’horodatage UPDATED_AT pour savoir quelles données ont été synchronisées avec succès sur Braze. Si de nombreuses lignes sont écrites avec le même horodatage pendant qu’une synchronisation est en cours, cela peut entraîner la synchronisation de données en double vers Braze. Quelques suggestions pour éviter les données en double :

• Si vous mettez en place une synchronisation avec VIEW, n’utilisez pas CURRENT_TIMESTAMP comme valeur par défaut. Ainsi, toutes les données seront synchronisées à chaque fois que la synchronisation sera exécutée, car le champ UPDATED_AT sera évalué à l’heure à laquelle nos requêtes sont exécutées.
• Si vous avez des pipelines ou des requêtes à très longue durée d’exécution qui écrivent des données dans votre table source, évitez de les exécuter simultanément avec une synchronisation, ou d’utiliser le même horodatage pour chaque ligne insérée.
• Utilisez une transaction pour écrire toutes les lignes qui ont le même horodatage.

Configuration de la table

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

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.

• nested custom attributes
• event
• purchase
• subscription groups

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