Intégrations de stockage de fichiers

Cette page explique comment configurer la prise en charge de l’ingestion de données cloud et synchroniser les données pertinentes d’Amazon S3 vers Braze.

Fonctionnement

Vous pouvez utiliser l’ingestion de données cloud (CDI) pour S3 afin d’intégrer directement un ou plusieurs compartiments S3 de votre compte AWS avec Braze. Lorsque de nouveaux fichiers sont publiés sur S3, un message est envoyé à SQS, et l’ingestion de données cloud de Braze prend en charge ces nouveaux fichiers.

L’ingestion de données cloud prend en charge les éléments suivants :

• Fichiers JSON
• Fichiers CSV
• Fichiers Parquet
• Données d’attributs, d’événements personnalisés, d’événements d’achat, de suppression d’utilisateurs et de catalogue

Prérequis

L’intégration nécessite les ressources suivantes :

• Un compartiment S3 pour le stockage des données
• Une file d’attente SQS pour les notifications de nouveaux fichiers
• Un rôle IAM pour l’accès à Braze

Définitions AWS

Commencez par définir les termes utilisés au cours de cette tâche.

Configuration de Cloud Data Ingestion dans AWS

Étape 1 : Créer un compartiment source

Créez un compartiment S3 à usage général avec les paramètres par défaut dans votre compte AWS. Les compartiments S3 peuvent être réutilisés entre les synchronisations tant que le dossier est unique.

Les paramètres par défaut sont :

• ACL désactivées
• Bloquer tout accès public
• Désactiver le versionnement du compartiment
• Chiffrement SSE-S3
  • SSE-S3 est le seul type de chiffrement côté serveur pris en charge. Le chiffrement Amazon KMS n’est pas pris en charge.

Notez la région dans laquelle vous avez créé le compartiment — vous créerez une file d’attente SQS dans la même région à l’étape suivante.

Étape 2 : Créer une file d’attente SQS

Créez une file d’attente SQS pour suivre l’ajout d’objets dans le compartiment que vous avez créé. Utilisez les paramètres de configuration par défaut pour le moment.

Une file d’attente SQS doit être unique au niveau mondial (par exemple, une seule peut être utilisée pour une synchronisation CDI et ne peut pas être réutilisée dans un autre espace de travail).

Important

Veillez à créer cette file SQS dans la même région que celle dans laquelle vous avez créé le compartiment.

Notez l’ARN et l’URL de la file d’attente SQS — vous en aurez fréquemment besoin au cours de cette configuration.

Étape 3 : Configurer la politique d’accès

Pour configurer la politique d’accès, choisissez Advanced options.

Ajoutez l’instruction suivante à la politique d’accès de la file d’attente, en prenant soin de remplacer YOUR-BUCKET-NAME-HERE par le nom de votre compartiment, YOUR-SQS-ARN par l’ARN de votre file d’attente SQS, et YOUR-AWS-ACCOUNT-ID par l’ID de votre compte AWS :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "Sid": "braze-cdi-s3-sqs-publish",
  "Effect": "Allow",
  "Principal": {
    "Service": "s3.amazonaws.com"
  },
  "Action": "SQS:SendMessage",
  "Resource": "YOUR-SQS-ARN",
  "Condition": {
    "StringEquals": {
      "aws:SourceAccount": "YOUR-AWS-ACCOUNT-ID"
    },
    "ArnLike": {
      "aws:SourceArn": "arn:aws:s3:::YOUR-BUCKET-NAME-HERE"
    }
  }
}

Étape 4 : Ajouter une notification d’événement au compartiment S3

1. Dans le compartiment créé à l’étape 1, accédez à Properties > Event notifications.
2. Donnez un nom à la configuration. Vous pouvez éventuellement spécifier un préfixe ou un suffixe pour cibler uniquement un sous-ensemble de fichiers à ingérer par Braze.
3. Sous Destination, sélectionnez SQS queue et fournissez l’ARN de la file SQS que vous avez créée à l’étape 2.

Remarque

Si vous chargez vos fichiers dans le dossier racine d’un compartiment S3 puis déplacez certains fichiers vers un dossier spécifique dans le compartiment, vous pourriez rencontrer une erreur inattendue. À la place, vous pouvez modifier les notifications d’événement pour n’envoyer que les fichiers correspondant au préfixe, éviter de placer des fichiers dans le compartiment S3 en dehors de ce préfixe, ou mettre à jour l’intégration sans préfixe, ce qui ingère alors tous les fichiers.

Étape 5 : Créer une politique IAM

Créez une politique IAM pour permettre à Braze d’interagir avec votre compartiment source. Pour commencer, connectez-vous à la console de gestion AWS en tant qu’administrateur de compte.

1. Accédez à la section IAM de la console AWS, sélectionnez Policies dans la barre de navigation, puis sélectionnez Create Policy.
   
   
   
   

2. Ouvrez l’onglet JSON et saisissez l’extrait de code suivant dans la section Policy Document, en prenant soin de remplacer YOUR-BUCKET-NAME-HERE par le nom de votre compartiment, et YOUR-SQS-ARN-HERE par le nom de votre file d’attente SQS :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE"]
        },
        {
            "Effect": "Allow",
            "Action": ["s3:ListBucket", "s3:GetObjectAttributes", "s3:GetObject"],
            "Resource": ["arn:aws:s3:::YOUR-BUCKET-NAME-HERE/*"]
        },
        {
            "Effect": "Allow",
            "Action": [
                "sqs:DeleteMessage",
                "sqs:GetQueueUrl",
                "sqs:ReceiveMessage",
                "sqs:GetQueueAttributes"
            ],
            "Resource": "YOUR-SQS-ARN-HERE"
        }
    ]
}

3. Sélectionnez Review Policy lorsque vous avez terminé.

4. Donnez un nom et une description à la politique, puis sélectionnez Create Policy.

Étape 6 : Créer un rôle IAM

Pour terminer la configuration sur AWS, créez un rôle IAM et attachez-y la politique IAM de l’étape 5.

1. Dans la même section IAM de la console où vous avez créé la politique IAM, accédez à Roles > Create Role.

2. Dans AWS, sélectionnez Another AWS Account comme type d’entité de confiance. Fournissez l’ID de votre compte Braze. Cochez la case Require external ID.
3. Dans Braze, accédez à Data Settings > Cloud Data Ingestion > Sources, sélectionnez Add data source, puis sélectionnez Amazon S3 dans la section des sources de fichiers.
4. Copiez l’ID de compte Braze généré automatiquement.

6. Dans AWS, collez l’ID de compte, puis sélectionnez Next.

7. Attachez la politique créée à l’étape 4 au rôle. Recherchez la politique dans la barre de recherche et cochez la case à côté de la politique pour l’attacher. Sélectionnez Next lorsque vous avez terminé.

Donnez un nom et une description au rôle, puis sélectionnez Create Role.

8. Notez l’ARN du rôle que vous avez créé et l’ID externe que vous avez généré, car vous en aurez besoin pour créer l’intégration Cloud Data Ingestion.

Configuration de l’ingestion de données cloud dans Braze

1. Commencez par créer une nouvelle source dans le tableau de bord de Braze. Accédez à Data Settings > Cloud Data Ingestion > Sources, sélectionnez Add data source, puis sélectionnez Amazon S3.
2. Choisissez un nom pour votre source et saisissez les informations issues du processus de configuration AWS pour créer une nouvelle source. Spécifiez les éléments suivants :

• Role ARN
• ID externe
• Nom du compartiment
• Région

3. Sélectionnez Test connection pour confirmer que Braze peut accéder à votre compartiment. Après un test réussi, sélectionnez Connect to Source. Si la connexion échoue, un message d’erreur s’affiche pour vous aider à résoudre le problème.

4. Ensuite, créez une nouvelle synchronisation. Accédez à Data Settings > Cloud Data Ingestion > Syncs et sélectionnez Create data sync.

5. Choisissez un nom pour votre synchronisation. Sélectionnez ensuite une source S3 active et saisissez votre table source pour la synchronisation. Sélectionnez un type de données et sélectionnez Test Connection.

1. Saisissez les informations restantes issues du processus de configuration AWS. Spécifiez les éléments suivants :
   • URL SQS (doit être unique pour chaque nouvelle intégration)
   • Chemin du dossier (facultatif, doit être unique parmi les synchronisations d’un espace de travail)
2. Sélectionnez un type de données et sélectionnez Test Connection pour confirmer que Braze peut lister les fichiers disponibles à ingérer (pas les données contenues dans ces fichiers). Une fois le test réussi, sélectionnez Next: Notifications.
3. Ajoutez une ou plusieurs adresses e-mail de contact pour les notifications en cas de rupture de la synchronisation due à des problèmes d’accès ou de permissions. Vous pouvez également activer les notifications pour les erreurs au niveau utilisateur et les synchronisations réussies.
4. Créez la synchronisation.

Formats de fichiers requis

L’ingestion de données cloud prend en charge les fichiers JSON, CSV et Parquet. Les colonnes requises dépendent du type de données :

• Les données utilisateur (attributs, événements personnalisés, événements d’achat) utilisent des identifiants utilisateur et un payload
• Les données de catalogue utilisent des identifiants de catalogue

Si vous utilisez S3 pour les données de catalogue, consultez cette page ainsi que Synchroniser et supprimer des données de catalogue pour les exigences et comportements spécifiques aux catalogues.

Braze n’impose aucune exigence supplémentaire concernant les noms de fichiers au-delà de ce qu’AWS impose. Les noms de fichiers doivent être uniques. L’ajout d’un horodatage permet de garantir cette unicité.

Pour des exemples de tous les types de fichiers pris en charge (attributs, événements personnalisés, achats, catalogues et suppressions d’utilisateurs), consultez les fichiers d’exemple dans braze-examples.

Identifiants utilisateur

Pour les synchronisations de données utilisateur (attributs, événements personnalisés, événements d’achat), chaque ligne de votre fichier source nécessite exactement un identifiant utilisateur et une colonne payload. Un fichier source peut contenir des lignes avec différents types d’identifiants, mais chaque ligne individuelle ne doit en utiliser qu’un seul.

En plus d’un identifiant, chaque ligne doit inclure une colonne payload contenant une chaîne JSON des champs que vous souhaitez synchroniser vers l’utilisateur dans Braze.

Remarque

Contrairement aux sources d’entrepôt de données, la colonne UPDATED_AT n’est ni requise ni prise en charge pour les synchronisations de stockage de fichiers.

Identifiants de catalogue

Pour les synchronisations de catalogue, votre fichier source doit contenir les colonnes suivantes. Les fichiers de catalogue utilisent des identifiants différents de ceux des fichiers de données utilisateur.

Exemples

• json attributes
• json custom events
• json purchase events
• csv attributes
• csv catalogs

1
2
3
4
5
6
7
{"external_id":"s3-qa-0","payload":"{\"name\": \"GT896\", \"age\": 74, \"subscriber\": true, \"retention\": {\"previous_purchases\": 21, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600803\"}"}
{"external_id":"s3-qa-1","payload":"{\"name\": \"HSCJC\", \"age\": 86, \"subscriber\": false, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600824\"}"}
{"external_id":"s3-qa-2","payload":"{\"name\": \"YTMQZ\", \"age\": 43, \"subscriber\": false, \"retention\": {\"previous_purchases\": 23, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600831\"}"}
{"external_id":"s3-qa-3","payload":"{\"name\": \"5P44M\", \"age\": 15, \"subscriber\": true, \"retention\": {\"previous_purchases\": 7, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600838\"}"}
{"external_id":"s3-qa-4","payload":"{\"name\": \"WMYS7\", \"age\": 11, \"subscriber\": true, \"retention\": {\"previous_purchases\": 0, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600844\"}"}
{"external_id":"s3-qa-5","payload":"{\"name\": \"KCBLK\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 11, \"vip\": true}, \"last_visit\": \"2023-08-08T16:03:26.600850\"}"}
{"external_id":"s3-qa-6","payload":"{\"name\": \"T93MJ\", \"age\": 47, \"subscriber\": true, \"retention\": {\"previous_purchases\": 10, \"vip\": false}, \"last_visit\": \"2023-08-08T16:03:26.600856\"}"}

Important

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

1
2
{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"name\": \"view-206\", \"time\": \"2024-04-02T14:34:08\", \"properties\": {\"bool_value\": false, \"preceding_event\": \"unsubscribe\", \"important_number\": 206}}"}

Important

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

1
2
{"external_id":"s3-qa-0","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}
{"external_id":"s3-qa-1","payload":"{\"app_id\": \"YOUR_APP_ID\", \"product_id\": \"product-11\", \"currency\": \"BSD\", \"price\": 8.511527858335066, \"time\": \"2024-04-02T14:34:08\", \"quantity\": 19, \"properties\": {\"is_a_boolean\": true, \"important_number\": 40, \"preceding_event\": \"click\"}}"}

Important

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

1
2
3
4
external_id,payload
s3-qa-load-0-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""SNXIM"", ""age"": 54, ""subscriber"": true, ""retention"": {""previous_purchases"": 19, ""vip"": true}, ""last_visit"": ""2023-08-08T16:03:26.598806""}"
s3-qa-load-1-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""0J747"", ""age"": 73, ""subscriber"": false, ""retention"": {""previous_purchases"": 22, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598816""}"
s3-qa-load-2-d0daa196-cdf5-4a69-84ae-4797303aee75,"{""name"": ""EP1U0"", ""age"": 99, ""subscriber"": false, ""retention"": {""previous_purchases"": 23, ""vip"": false}, ""last_visit"": ""2023-08-08T16:03:26.598822""}"

1
2
3
ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

Incluez une colonne DELETED facultative. Lorsque DELETED est true, cet élément de catalogue est supprimé du catalogue dans Braze. Pour la liste complète des colonnes requises, consultez Identifiants de catalogue. Pour le comportement de suppression, consultez Suppression d’éléments de catalogue. Pour un flux de configuration de catalogue de bout en bout (y compris la création du catalogue cible et le comportement de synchronisation), consultez Synchroniser et supprimer des données de catalogue.

Suppression de données

L’ingestion de données cloud pour S3 prend en charge la suppression d’utilisateurs et d’éléments de catalogue via le téléversement de fichiers. Utilisez des synchronisations et des formats de fichiers distincts pour chaque type.

• Suppression d’utilisateurs – Créez une synchronisation avec le type de données Delete Users et téléversez des fichiers contenant uniquement des identifiants utilisateur (sans payload).
• Suppression d’éléments de catalogue – Utilisez votre synchronisation de catalogue existante et ajoutez une colonne deleted (ou DELETED) pour marquer les éléments à supprimer.

Suppression d’utilisateurs

Pour supprimer des profils utilisateur dans Braze à l’aide de fichiers dans S3 :

1. Créez une nouvelle synchronisation d’ingestion de données cloud (même configuration AWS et Braze que pour les autres synchronisations).
2. Lors de la configuration de la synchronisation dans Braze, définissez Data Type sur Delete Users.
3. Téléversez dans votre compartiment S3 des fichiers contenant uniquement les colonnes d’identifiants utilisateur. N’incluez pas de colonne payload — la synchronisation échoue si un payload est présent, afin d’éviter les suppressions accidentelles.

Chaque ligne du fichier doit identifier exactement un utilisateur à l’aide de l’un des éléments suivants :

Important

La suppression d’utilisateurs est permanente et ne peut pas être annulée. N’incluez que les utilisateurs que vous avez l’intention de supprimer. Pour plus de détails, consultez Supprimer des utilisateurs avec l’ingestion de données cloud.

Exemple – JSON (suppression d’utilisateurs) :

{"external_id":"user-to-delete-001"}
{"external_id":"user-to-delete-002"}
{"braze_id":"braze-id-from-profile"}

Exemple – CSV (suppression d’utilisateurs) :

1
2
3
external_id
user-to-delete-001
user-to-delete-002

Lorsque la synchronisation s’exécute, Braze traite les nouveaux fichiers dans le compartiment et supprime les profils utilisateur correspondants.

Suppression d’éléments de catalogue

Pour supprimer des éléments d’un catalogue à l’aide du stockage de fichiers :

1. Utilisez la même synchronisation S3 que celle utilisée pour synchroniser les données de catalogue (type de données Catalogs).
2. Dans vos fichiers CSV ou JSON, ajoutez une colonne optionnelle deleted (ou DELETED).
3. Définissez deleted sur true pour tout élément de catalogue que vous souhaitez supprimer du catalogue dans Braze.

Chaque ligne nécessite toujours ID et payload. Pour les lignes marquées pour suppression, le payload peut être minimal ; Braze supprime l’élément par ID.

Exemple – JSON (suppression d’élément de catalogue) :

{"id":"85","payload":"{\"product_name\": \"Product 85\", \"price\": 85.85}"}
{"id":"1","payload":"{\"product_name\": \"Product 1\", \"price\": 1.01}","deleted":true}

Exemple – CSV (suppression d’élément de catalogue) :

1
2
3
ID,PAYLOAD,DELETED
85,"{""product_name"": ""Product 85"", ""price"": 85.85}",false
1,"{""product_name"": ""Product 1"", ""price"": 1.01}",true

Lorsque la synchronisation s’exécute, les lignes avec deleted: true entraînent la suppression de l’élément de catalogue correspondant dans Braze. Pour en savoir plus sur le comportement de synchronisation et de suppression de catalogue, consultez Synchroniser et supprimer des données de catalogue.

Points importants

• Les fichiers ajoutés au compartiment S3 source ne doivent pas dépasser 512 Mo. Les fichiers de plus de 512 Mo génèrent une erreur et ne sont pas synchronisés avec Braze.
• Bien qu’il n’y ait pas de limite supplémentaire sur le nombre de lignes par fichier, nous recommandons d’utiliser des fichiers plus petits pour améliorer la vitesse d’exécution de vos synchronisations. Par exemple, l’ingestion d’un fichier de 500 Mo prendrait considérablement plus de temps que celle de cinq fichiers distincts de 100 Mo.
• Il n’y a pas de limite supplémentaire sur le nombre de fichiers téléversés dans un laps de temps donné.
• L’ordonnancement n’est pas pris en charge au sein des fichiers ni entre eux. Nous recommandons de regrouper les mises à jour périodiquement si vous surveillez d’éventuelles conditions de concurrence.

Résolution des problèmes

Téléchargement et traitement des fichiers

L’ingestion de données cloud (CDI) ne traite que les fichiers ajoutés après la création de la synchronisation. Au cours de ce processus, Braze recherche les nouveaux fichiers ajoutés, ce qui déclenche un nouveau message vers SQS. Cela lance une nouvelle synchronisation pour traiter le nouveau fichier.

Vous pouvez utiliser des fichiers existants pour vérifier que Braze peut accéder à votre compartiment et détecter les fichiers à ingérer, mais ils ne sont pas synchronisés avec Braze. Pour que le CDI les traite, vous devez re-télécharger vers S3 tous les fichiers existants que vous souhaitez synchroniser.

Gestion des erreurs de fichiers inattendues

Si vous observez un nombre élevé d’erreurs ou de fichiers en échec, il est possible qu’un autre processus ajoute des fichiers au compartiment S3 dans un dossier différent du dossier cible pour le CDI.

Lorsque des fichiers sont téléchargés dans le compartiment source mais pas dans le dossier source, le CDI traite la notification SQS, mais n’effectue aucune action sur le fichier, ce qui peut apparaître comme une erreur.

Si votre problème est lié aux notifications S3 ou aux autorisations de destination SQS (par exemple, des erreurs de validation de destination), consultez la documentation AWS :

• Activation et configuration des notifications d’événements à l’aide de la console Amazon S3
• Octroi d’autorisations pour publier des messages de notification d’événements vers une destination
• Résolution des problèmes dans Amazon SQS