Passer au contenu

Ingestion de données cloud pour Amazon S3

Cette page couvre tout ce dont vous avez besoin pour synchroniser des données d’Amazon S3 vers Braze à l’aide de l’ingestion de données cloud (CDI) : les ressources AWS à créer, comment connecter la source et créer une synchronisation dans Braze, le format de fichier pour chaque type de données et la résolution des problèmes spécifiques à S3.

Fonctionnement

Les intégrations Amazon S3 sont basées sur les événements plutôt que planifiées. Lorsque de nouveaux fichiers sont publiés dans S3, un message est publié dans une file d’attente Amazon Simple Queue Service (SQS), et Braze consomme ce message pour ingérer le nouveau fichier.

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

  • Compartiment S3 pour le stockage des données
  • File d’attente SQS pour les notifications de nouveaux fichiers
  • Rôle IAM pour l’accès de Braze

Définitions AWS

Terme Définition
Amazon Resource Name (ARN) L’ARN est un identifiant unique pour les ressources AWS.
Identity and Access Management (IAM) IAM est un service web qui vous permet de contrôler l’accès aux ressources AWS en toute sécurité. Dans ce tutoriel, vous créez une politique IAM et l’attribuez à un rôle IAM pour intégrer votre compartiment S3 à l’ingestion de données cloud de Braze.
Amazon Simple Queue Service (SQS) SQS est une file d’attente hébergée qui vous permet d’intégrer des systèmes et composants logiciels distribués.

Configurer l’ingestion de données cloud 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 plusieurs synchronisations, à condition que le dossier soit unique.

Les paramètres par défaut sont les suivants :

  • ACL désactivées
  • Blocage de tout accès public
  • Gestion des versions du compartiment désactivée
  • 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 pour l’instant les paramètres de configuration par défaut.

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

Notez l’ARN et l’URL de la file d’attente SQS. Vous en aurez souvent besoin au cours de cette configuration.

Sélection de l’option « Avancé » avec un exemple d’objet JSON définissant qui peut accéder à une file d’attente.

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

Pour configurer la politique d’accès, choisissez Options avancées.

Ajoutez la déclaration 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 :

{
  "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 à Propriétés > Notifications d’événements.
  2. Donnez un nom à la configuration. Vous pouvez éventuellement spécifier un préfixe ou un suffixe à cibler si vous souhaitez que Braze n’ingère qu’un sous-ensemble de fichiers.
  3. Sous Destination, sélectionnez File d’attente SQS et indiquez l’ARN de la file SQS créée à l’étape 2.

É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 du compte.

  1. Accédez à la section IAM de la console AWS, sélectionnez Politiques dans la barre de navigation, puis Créer une politique.

    Le bouton « Créer une politique » dans la console AWS.

  2. Ouvrez l’onglet JSON et saisissez l’extrait de code suivant dans la section Document de politique, 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 :

{
    "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"
        }
    ]
}

  1. Une fois que vous avez terminé, sélectionnez Vérifier la politique.

  2. Donnez un nom et une description à la politique, puis sélectionnez Créer une politique.

Un exemple de politique nommée « new-policy-name ».

Le champ de description de la politique.

Étape 6 : Configurer l’authentification

Braze accède à votre compartiment et à votre file d’attente à l’aide de la méthode d’authentification suivante :

Méthode Mode d’authentification de Braze Informations à saisir dans Braze
IAM role Braze assumes an AWS Identity and Access Management (IAM) role in your account, using an external ID. Role ARN and External ID

IAM role

Braze endosse un rôle IAM dans votre compte AWS. Créez ce rôle et associez-lui la politique IAM que vous avez créée.

  1. Dans la même section IAM de la console où vous avez créé la politique IAM, accédez à Rôles > Créer un rôle.

Le bouton « Créer un rôle ».

  1. Dans AWS, sélectionnez Un autre compte AWS comme type de sélecteur d’entité de confiance. Indiquez l’ID de votre compte Braze. Cochez la case Exiger un ID externe.
  2. Dans Braze, accédez à Paramètres des données > Ingestion de données cloud > Sources, sélectionnez Ajouter une source de données, puis sélectionnez Amazon S3 dans la section des sources de fichiers.
  3. Copiez l’ID de compte Braze généré automatiquement.

La page « Ajouter une nouvelle source » affichant les sections Nom de la source et Détails de la connexion S3.

  1. Dans AWS, collez l’ID de compte, puis sélectionnez Suivant.

La page S3 « Créer un rôle », avec des champs pour le nom du rôle, la description du rôle, les entités de confiance, les politiques et la limite des autorisations.

  1. Associez la politique IAM au rôle. Recherchez la politique dans la barre de recherche, puis cochez la case à côté de la politique pour l’associer. Sélectionnez ensuite Suivant.

ARN du rôle avec la politique new-policy-name sélectionnée.

  1. Donnez un nom et une description au rôle, puis sélectionnez Créer un rôle.

Exemple de rôle nommé « new-role-name ».

  1. Notez l’ARN du rôle que vous avez créé et l’ID externe que vous avez généré : vous en aurez besoin pour créer l’intégration d’ingestion de données cloud.

Configurer 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 à Paramètres des données > Ingestion de données cloud > Sources, sélectionnez Ajouter une source de données, puis 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. Indiquez les éléments suivants :

La section Détails de connexion S3 affichant les identifiants (configuration AWS et configuration Braze) et les champs de configuration.

  1. Sélectionnez Tester la connexion pour vérifier que Braze peut accéder à votre compartiment. Une fois le test réussi, sélectionnez Se connecter à la source. Si la connexion échoue, un message d’erreur s’affiche pour vous aider à résoudre le problème.
  1. Ensuite, créez une nouvelle synchronisation. Accédez à Paramètres des données > Ingestion de données cloud > Synchronisations et sélectionnez Créer une synchronisation de données.
  1. Choisissez un nom pour votre synchronisation. Ensuite, sélectionnez une source S3 active et saisissez la table source de la synchronisation. Sélectionnez un type de données, puis Tester la connexion.

Une option permettant de tester la connexion avec un aperçu des données.

  1. Saisissez les autres informations issues du processus de configuration AWS. Indiquez 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, puis Tester la connexion pour vérifier que Braze peut lister les fichiers disponibles pour l’ingestion (et non les données contenues dans ces fichiers). Une fois le test réussi, sélectionnez Suivant : Notifications.
  3. Ajoutez des adresses e-mail de contact pour recevoir des notifications si la synchronisation échoue en raison de problèmes d’accès ou d’autorisations. Vous pouvez éventuellement activer les notifications pour les erreurs au niveau utilisateur et les synchronisations réussies.
  4. Créez la synchronisation.

Formats de fichiers requis

Cloud Data Ingestion prend en charge les fichiers JSON, CSV et Parquet. Les colonnes requises dépendent du type de données. Braze n’impose aucune exigence supplémentaire concernant les noms de fichiers, au-delà de celles de votre fournisseur de stockage de fichiers. Les noms de fichiers doivent être uniques, et l’ajout d’un horodatage permet de garantir cette unicité.

Pour consulter des exemples de tous les types de fichiers pris en charge, reportez-vous aux fichiers d’exemple dans braze-examples.

Sélectionnez l’onglet correspondant au type de données que vous souhaitez synchroniser.

Chaque ligne 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 ne doit en utiliser qu’un seul.

Identifiant Description
EXTERNAL_ID Identifie l’utilisateur que vous souhaitez mettre à jour. Cette valeur doit correspondre à la valeur external_id utilisée dans Braze.
ALIAS_NAME et ALIAS_LABEL Ces deux colonnes créent un objet alias d’utilisateur. alias_name doit être un identifiant unique, et alias_label indique le type d’alias. Les utilisateurs peuvent avoir plusieurs alias avec des libellés différents, mais un seul alias_name par alias_label.
BRAZE_ID L’identifiant utilisateur Braze. Il est généré par le SDK de Braze, et il n’est pas possible de créer de nouveaux utilisateurs à l’aide d’un ID Braze via Cloud Data Ingestion. Pour créer de nouveaux utilisateurs, indiquez un ID utilisateur externe ou un alias d’utilisateur.
EMAIL L’adresse e-mail de l’utilisateur. Si plusieurs profils partagent la même adresse e-mail, le profil mis à jour le plus récemment est prioritaire pour les mises à jour. Si vous incluez à la fois l’e-mail et le téléphone, Braze utilise l’e-mail comme identifiant principal.
PHONE Le numéro de téléphone de l’utilisateur. Si plusieurs profils partagent le même numéro de téléphone, le profil mis à jour le plus récemment est prioritaire pour les mises à jour.

La colonne payload contient une chaîne de caractères JSON des champs que vous souhaitez synchroniser avec l’utilisateur dans Braze, selon le format de l’objet attributs utilisateur.

Exemple JSON

{"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\"}"}

Exemple CSV

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

Les événements personnalisés utilisent les mêmes colonnes d’identifiant utilisateur que les attributs utilisateur. La colonne payload suit le format de l’objet événements.

{"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}}"}

Les événements d’achat utilisent les mêmes colonnes d’identifiant utilisateur que les attributs utilisateur. La colonne payload suit le format de l’objet achats.

{"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\"}}"}

Les fichiers de catalogue utilisent des identifiants différents de ceux des fichiers de données utilisateur. Avant de créer une synchronisation de catalogue, créez le catalogue cible dans Braze. Pour connaître le processus complet relatif aux catalogues, consultez Synchroniser et supprimer des données de catalogue.

Colonne Requis Description
ID Oui L’identifiant unique de l’article de catalogue. Il sert à créer, mettre à jour ou supprimer l’article dans Braze.
payload Oui Une chaîne de caractères JSON des champs et valeurs de catalogue à synchroniser. Elle doit correspondre au schéma de votre catalogue dans Braze.
DELETED Non Lorsque la valeur est true, l’article de catalogue correspondant à l’ID est retiré du catalogue dans Braze. Omettez cette colonne ou définissez-la sur false pour les opérations de création ou de mise à jour.

Exemple JSON

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

Exemple CSV avec la colonne DELETED

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

Exemple CSV sans la colonne DELETED

ID,PAYLOAD
85,"{""product_name"": ""Product 85"", ""price"": 85.85}"
86,"{""product_name"": ""Product 86"", ""price"": 86.86}"

Les déclencheurs Canvas alimentent la personnalisation zéro copie. Pour la configuration du Canvas de destination et les points à prendre en compte, consultez Personnalisation zéro copie.

Champ Requis Description
EXTERNAL_ID Oui, l’un des deux : external_id ou alias_name et alias_label Identifie l’utilisateur que vous souhaitez mettre à jour. Cette valeur doit correspondre à la valeur external_id utilisée dans Braze.
ALIAS_NAME et ALIAS_LABEL Oui, l’un des deux : external_id ou alias_name et alias_label Ces deux colonnes créent un objet alias d’utilisateur. alias_name doit être un identifiant unique, et alias_label indique le type d’alias. Les utilisateurs peuvent avoir plusieurs alias avec des libellés différents, mais un seul alias_name par alias_label.
PROPERTIES Oui Chaîne de caractères JSON des champs à rendre disponibles en tant que propriétés de personnalisation dans votre Canvas. Elle doit contenir des informations propres à l’utilisateur.

Pour commencer, sélectionnez le type de données Déclencheurs Canvas lors de la création d’une nouvelle synchronisation.

Pour supprimer des profils utilisateur dans Braze à l’aide de fichiers présents dans votre compartiment source :

  1. Créez une nouvelle synchronisation Cloud Data Ingestion, avec la même configuration que pour les autres synchronisations.
  2. Lors de la configuration de la synchronisation dans Braze, définissez Type de données sur Supprimer des utilisateurs.
  3. Importez dans votre compartiment source des fichiers contenant uniquement des colonnes d’identifiant 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 identifiants suivants :

Identifiant Description
EXTERNAL_ID Correspond à l’external_id utilisé dans Braze.
ALIAS_NAME et ALIAS_LABEL Ces deux colonnes identifient ensemble l’utilisateur par son alias.
BRAZE_ID ID utilisateur généré par Braze (utilisateurs existants uniquement).

Exemple JSON

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

Exemple CSV

external_id
user-to-delete-001
user-to-delete-002

Lors de l’exécution de la synchronisation, Braze traite les nouveaux fichiers du compartiment et supprime les profils utilisateur correspondants.

Supprimer des éléments de catalogue

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

  1. Utilisez la synchronisation que vous employez déjà pour synchroniser les données du catalogue (type de données Catalogues).
  2. Dans vos fichiers CSV ou JSON, ajoutez une colonne facultative deleted (ou DELETED).
  3. Définissez deleted sur true pour chaque article que vous souhaitez supprimer du catalogue dans Braze.

Chaque ligne doit toujours contenir ID et payload. Pour les lignes à supprimer, le payload peut être minimal : Braze supprime l’article en fonction de son ID.

Lors de l’exécution de la synchronisation, chaque ligne avec deleted: true entraîne la suppression de l’article de catalogue correspondant dans Braze. Pour en savoir plus sur le fonctionnement complet de la synchronisation et de la suppression des catalogues, consultez Synchroniser et supprimer des données de catalogue.

À savoir

  • Les fichiers ajoutés au compartiment ou au conteneur source ne doivent pas dépasser 512 Mo. Cette limite s’applique à Amazon S3, Google Cloud Storage et Azure Blob Storage. Les fichiers de plus de 512 Mo génèrent une erreur et ne sont pas synchronisés avec Braze. Azure Blob Storage accepte en soi des fichiers beaucoup plus volumineux, mais CDI applique la même limite de 512 Mo à toutes les sources de stockage de fichiers.
  • Bien qu’il n’y ait pas de limite supplémentaire sur le nombre de lignes par fichier, Braze recommande d’utiliser des fichiers plus petits pour accélérer vos synchronisations. Par exemple, l’ingestion d’un fichier de 500 Mo prendrait beaucoup 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 importés sur une période donnée.
  • L’ordre n’est pas garanti au sein des fichiers ni entre eux. Si vous surveillez d’éventuelles conditions de concurrence, Braze recommande de regrouper périodiquement les mises à jour.
  • CDI ne traite que les fichiers ajoutés après la création de la synchronisation. 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 CDI les traite, importez à nouveau dans le compartiment source les fichiers existants que vous souhaitez synchroniser.
  • Braze supprime un message SQS uniquement lorsque le fichier a été lu avec succès et que les lignes qui en résultent ont été ingérées dans les systèmes internes de Braze. Braze ne prolonge pas le délai de visibilité. Si vous voyez des messages dans votre file d’attente de lettres mortes, envisagez d’augmenter votre délai de visibilité pour qu’il corresponde au temps de traitement de vos fichiers les plus volumineux. Braze suit également les métadonnées de chaque fichier : si un fichier est ingéré avec succès et qu’un message SQS en double apparaît pour ce fichier, Braze supprime immédiatement le doublon. Si le fichier n’a pas été ingéré avec succès, Braze traite le message SQS normalement.

Résolution des problèmes

Chargement et traitement des fichiers

La CDI ne traite que les fichiers ajoutés après la création de la synchronisation. Dans ce processus, Braze recherche l’ajout de nouveaux fichiers, ce qui déclenche une nouvelle notification. Celle-ci lance une nouvelle synchronisation pour traiter le nouveau fichier. Pour Amazon S3, la notification est un message envoyé à SQS.

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 la CDI les traite, vous devez charger à nouveau dans le compartiment source tous les fichiers existants que vous souhaitez synchroniser.

Gérer les 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 autre que le dossier cible de la CDI.

Lorsque des fichiers sont chargés dans le compartiment source mais en dehors du dossier source, la CDI traite la notification SQS sans effectuer aucune action sur le fichier, ce qui peut apparaître comme une erreur.

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

Erreur « Incorrect Integration Object »

Cette erreur se produit lorsque deux espaces de travail ou plus disposent d’intégrations pointant vers le même compartiment ou dossier de stockage cloud. Chaque emplacement de stockage cloud ne peut être utilisé que par une seule intégration à la fois. Pour connaître les étapes de résolution, consultez la FAQ.

New Stuff!