Envoyer des mises à jour de lignes partielles aux Real-Time Customer Profile à l’aide de Data Prep
- Rubriques :
- Préparation des données
Créé pour :
- Développeur
-
L’ingestion de messages de mise à jour d’entité du modèle de données d’expérience (XDM) (avec des opérations JSON PATCH) pour les mises à jour de profil via l’entrée DCS est obsolète. Suivez les étapes décrites dans ce guide comme alternative.
-
Vous pouvez également utiliser la source d’API HTTP pour ingérer des données brutes dans l’inlet DCS et spécifier les mappages de données nécessaires pour transformer vos données en messages conformes à XDM pour les mises à jour de Profile.
-
Lors de l’utilisation de tableaux dans des upserts en flux continu, vous devez utiliser explicitement
upsert_array_append
ouupsert_array_replace
pour définir l’intention claire de l’opération. Vous pouvez recevoir des erreurs si ces fonctions sont manquantes.
Utilisez des upserts en flux continu dans Data Prep pour envoyer des mises à jour de lignes partielles à Real-Time Customer Profile données tout en créant et en établissant de nouveaux liens d’identité avec une seule requête API.
En diffusant des upserts en continu, vous pouvez conserver le format de vos données tout en les traduisant en requêtes PATCH Real-Time Customer Profile lors de l’ingestion. En fonction des entrées que vous fournissez, Data Prep vous permet d’envoyer une seule payload d’API et de traduire les données à la fois vers Real-Time Customer Profile requêtes PATCH et Identity Service CREATE.
Data Prep utilise les paramètres d'en-tête pour faire la distinction entre les insertions et les upserts. Toutes les lignes qui utilisent des upserts doivent avoir un en-tête. Vous pouvez utiliser des upserts avec ou sans descripteurs d’identité. Si vous utilisez des upserts avec des identités, vous devez suivre les étapes de configuration décrites dans la section Configuration du jeu de données d’identité. Si vous utilisez des upserts sans identités, vous n’avez pas besoin de fournir de configurations d’identité dans votre requête. Lisez la section sur la diffusion en continu d’upserts sans identités pour plus d’informations.
Ce document fournit des informations sur la diffusion d’upserts dans Data Prep.
Prise en main
Cette présentation d’ nécessite une compréhension professionnelle des composants suivants d’Adobe Experience Platform :
- Data Prep : Data Prep permet aux ingénieurs de données de mapper, transformer et valider des données vers et à partir du modèle de données d’expérience (XDM).
- Identity Service : obtenez une meilleure compréhension des clients individuels et de leurs comportements en rapprochant des identités entre appareils et systèmes.
- Real-Time Customer Profile : fournit un profil client en temps réel unifié basé sur des données agrégées issues de plusieurs sources.
- Sources : Experience Platform permet d’ingérer des données provenant de diverses sources tout en vous offrant la possibilité de structurer, d’étiqueter et d’améliorer les données entrantes à l’aide des services d’Experience Platform.
Utiliser des upserts en flux continu dans Data Prep
Workflow de haut niveau de diffusion d’upserts
La diffusion en continu d’upserts dans Data Prep fonctionne comme suit :
-
Vous devez d’abord créer et activer un jeu de données pour la consommation Profile. Pour plus d’informations, consultez le guide sur l’activation d’un jeu de données pour Profile.
-
Si de nouvelles identités doivent être liées, vous devez également créer un jeu de données supplémentaire avec le même schéma que votre jeu de données Profile.
-
Une fois que votre ou vos jeux de données sont préparés, vous devez créer un flux de données pour mapper votre requête entrante au jeu de données Profile ;
-
Ensuite, vous devez mettre à jour la requête entrante pour inclure les en-têtes nécessaires. Ces en-têtes définissent les éléments suivants :
- Opération de données devant être effectuée avec Profile :
create
,merge
etdelete
. - Opération d’identité facultative à effectuer avec Identity Service :
create
.
- Opération de données devant être effectuée avec Profile :
Configurer le jeu de données d’identité
Si de nouvelles identités doivent être liées, vous devez créer et transmettre un jeu de données supplémentaire dans la payload entrante. Lors de la création d’un jeu de données d’identité, vous devez vous assurer que les exigences suivantes sont remplies :
- Le jeu de données d’identité doit avoir son schéma associé comme jeu de données Profile. Une incohérence des schémas peut entraîner un comportement incohérent du système.
- Cependant, vous devez vous assurer que le jeu de données d’identité est différent du jeu de données d’Profile. Si les jeux de données sont identiques, les données sont remplacées au lieu d’être mises à jour.
- Alors que le jeu de données initial doit être activé pour Profile, le jeu de données d’identité ne doit pas être activé par Profile. Sinon, les données seront également remplacées au lieu d’être mises à jour. Cependant, le jeu de données d’identité doit être activé par Identity Service.
Champs obligatoires dans les schémas associés au jeu de données d’identité
Si votre schéma contient des champs obligatoires, la validation du jeu de données doit être supprimée pour permettre aux Identity Service de ne recevoir que les identités. Vous pouvez supprimer la validation en appliquant la valeur disabled
au paramètre acp_validationContext
. Voir l’exemple ci-dessous :
curl -X POST 'https://platform.adobe.io/data/foundation/catalog/dataSets/62257bef7a75461948ebcaaa' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"tags": {
"acp_validationContext": [
"disabled"
],
"unifiedProfile": [
"enabled:false"
],
"unifiedIdentity": [
"enabled:true"
]
}
}'
Structure de la payload entrante
Vous trouverez ci-dessous un exemple de structure de payload entrante qui établit de nouveaux liens d’identité.
Payload avec configuration des identités
{
"header": {
"flowId": "923e2ac3-3869-46ec-9e6f-7012c4e23f69",
"imsOrgId": "{ORG_ID}",
"datasetId": "621fc19ab33d941949af16c8",
"operations": {
"data": "create" (default)/"merge"/"delete",
"identity": "create",
"identityDatasetId": "621fc19ab33d941949af16d9"
}
}
... //The raw data attributes are included here as the key/value pairs of the "body" property.
}
flowId
datasetId
.imsOrgId
datasetId
operations
operations.data
operations.identity
operations.identityDatasetId
Opérations prises en charge
Les opérations suivantes sont prises en charge par Real-Time Customer Profile :
create
merge
delete
Les opérations suivantes sont prises en charge par Identity Service :
create
create
est transmis en tant que valeur pour operations.identity
, Data Prep génère une requête de création d’entité XDM pour Identity Service. Si l’identité existe déjà, elle est ignorée. Remarque : si operations.identity
est défini sur create
, le identityDatasetId
doit également être spécifié. Le message de création d’entité XDM généré en interne par Data Prep composant sera généré pour cet identifiant de jeu de données.Payload sans configuration d’identité
S’il n’est pas nécessaire de lier de nouvelles identités, vous pouvez omettre les paramètres identity
et identityDatasetId
dans les opérations. Cela envoie les données uniquement à Real-Time Customer Profile et ignore le Identity Service. Pour obtenir un exemple, reportez-vous à la payload ci-dessous :
{
"header": {
"flowId": "923e2ac3-3869-46ec-9e6f-7012c4e23f69",
"imsOrgId": "{ORG_ID}",
"datasetId": "621fc19ab33d941949af16c8",
"operations": {
"data": "create"/"merge"/"delete",
}
}
... //The raw data attributes are included here as the key/value pairs of the "body" property.
}
Transmission dynamique des identités principales
Pour les mises à jour XDM, le schéma doit être activé pour Profile et contenir une identité principale. Vous pouvez spécifier l’identité principale d’un schéma XDM de deux manières :
- Désigner un champ statique comme identité principale dans le schéma XDM ;
- Désignez l’un des champs d’identité comme identité principale par le biais du groupe de champs de mappage d’identités dans le schéma XDM.
Désigner un champ statique comme champ d’identité principale dans le schéma XDM
Dans l’exemple ci-dessous, les attributs state
, homePhone.number
et autres sont insérés avec leurs valeurs données respectives dans le Profile avec l’identité principale de sampleEmail@gmail.com
. Un message de mise à jour d’entité XDM est ensuite généré par le composant Data Prep de diffusion en continu. Real-Time Customer Profile confirme ensuite ce message de mise à jour XDM pour upsert l’enregistrement de profil.
curl -X POST 'https://dcs.adobedc.net/collection/9aba816d350a69c4abbd283eb5818ec3583275ffce4880ffc482be5a9d810c4b' \
-H 'Content-Type: application/json' \
-H 'x-adobe-flow-id: d5262d48-0f47-4949-be6d-795f06933527' \
-d '{
"header": {
"flowId" : "d5262d48-0f47-4949-be6d-795f06933527",
"imsOrgId": "{ORG_ID}",
"datasetId": "62259f817f62d71947929a7b",
"operations": {
"data": "create"
}
},
{
"body": {
"homeAddress": {
"country": "US",
"state": "GA",
"region": "va7"
},
"homePhone": {
"number": "123.456.799"
},
"identityMap": {
"Email": [{
"id": "sampleEmail@gmail.com",
"primary": true
}]
},
"personalEmail": {
"address": "sampleEmail@gmail.com",
"primary": true
},
"personID": "346576345",
"_id": "346576345",
"timestamp": "2021-05-05T17:51:45.1880+02",
"workEmail": "sampleWorkEmail@gmail.com"
}
}'
Désignez l’un des champs d’identité comme identité principale par le biais du groupe de champs de mappage d’identités dans le schéma XDM
Dans cet exemple, l’en-tête contient l’attribut operations
avec les propriétés identity
et identityDatasetId
. Cela permet de fusionner les données avec Real-Time Customer Profile et de transmettre les identités à Identity Service.
curl -X POST 'https://dcs.adobedc.net/collection/9aba816d350a69c4abbd283eb5818ec3583275ffce4880ffc482be5a9d810c4b' \
-H 'Content-Type: application/json' \
-H 'x-adobe-flow-id: d5262d48-0f47-4949-be6d-795f06933527' \
-d '{
"header": {
"flowId" : "d5262d48-0f47-4949-be6d-795f06933527",
"imsOrgId": "{ORG_ID}",
"datasetId": "62259f817f62d71947929a7b",
"operations": {
"data": "merge",
"identity": "create",
"identityDatasetId": "6254a93b851ecd194b64af9e"
}
},
{
"body": {
"homeAddress": {
"country": "US",
"state": "GA",
"region": "va7"
},
"homePhone": {
"number": "123.456.799"
},
"identityMap": {
"Email": [{
"id": "sampleEmail@gmail.com",
"primary": true
}]
},
"personalEmail": {
"address": "sampleEmail@gmail.com",
"primary": true
},
"personID": "346576345",
"_id": "346576345",
"timestamp": "2021-05-05T17:51:45.1880+02",
"workEmail": "sampleWorkEmail@gmail.com"
}
}'
Limites connues et considérations clés
Vous trouverez ci-dessous une liste des limites connues à prendre en compte lors de la diffusion en flux continu d’upserts avec Data Prep :
- La méthode upserts en flux continu ne doit être utilisée que lors de l’envoi de mises à jour de lignes partielles à Real-Time Customer Profile. Les mises à jour de lignes partielles ne sont pas utilisées par le lac de données.
- La méthode upserts en flux continu ne prend pas en charge la mise à jour, le remplacement et la suppression des identités. De nouvelles identités sont créées si elles n’existent pas. Par conséquent, l’opération
identity
doit toujours être définie sur créer. Si une identité existe déjà, l’opération n’est pas opérationnelle. - La méthode upserts en flux continu ne prend actuellement pas en charge Adobe Experience Platform Web SDK et Adobe Experience Platform Mobile SDK.
Étapes suivantes
En lisant ce document, vous devriez maintenant comprendre comment diffuser des upserts dans Data Prep pour envoyer des mises à jour de lignes partielles à vos données Real-Time Customer Profile, tout en créant et en liant des identités avec une seule requête API. Pour plus d’informations sur les autres fonctionnalités de Data Prep, veuillez lire la Data Prep présentation. Pour savoir comment utiliser les jeux de mappages dans l’API Data Prep, consultez le Data Prep guide de développement.