DocumentationExperience PlatformGuide de préparation des données

Envoyer des mises à jour de lignes partielles aux Real-Time Customer Profile à l’aide de Data Prep

Dernière mise à jour : 4 avril 2025
  • Rubriques :
  • Préparation des données

Créé pour :

  • Développeur
IMPORTANT
  • 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 ou upsert_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.

NOTE
Pour tirer parti de la fonctionnalité d’upsert, il est recommandé de désactiver les configurations compatibles avec XDM lors de l’ingestion des données et de remapper la payload entrante à l’aide du mappeur de préparation des données.

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

NOTE
Les sources suivantes prennent en charge l’utilisation d’upserts en flux continu :
  • Amazon Kinesis
  • Azure Event Hubs
  • HTTP API

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 et delete.
    • Opération d’identité facultative à effectuer avec Identity Service : create.

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"
        ]
    }
}'
TIP
Vous n’avez pas besoin d’effectuer de configuration supplémentaire si le schéma associé au jeu de données d’identité ne comporte aucun champ obligatoire.

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.
}
Paramètre
Description
flowId
Identifiant unique permettant d’identifier un flux de données. Cet identifiant de flux de données doit correspondre à la connexion source créée avec Amazon Kinesis, Azure Event Hubs ou HTTP API. Ce flux de données doit également avoir un jeu de données activé pour Profile comme jeu de données cible. Remarque : l’identifiant du jeu de données cible activé pour Profile est également utilisé comme paramètre de datasetId.
imsOrgId
Identifiant qui correspond à votre organisation.
datasetId
L’identifiant du jeu de données cible activé pour Profile de votre flux de données. Remarque : il s’agit du même identifiant que l’identifiant du jeu de données cible activé pour Profile qui se trouve dans votre flux de données.
operations
Ce paramètre décrit les actions que Data Prep entreprendrez en fonction de la requête entrante.
operations.data
Définit les actions qui doivent être effectuées dans Real-Time Customer Profile.
operations.identity
Définit les opérations autorisées sur les données par Identity Service.
operations.identityDatasetId
(Facultatif) Identifiant du jeu de données d’identité obligatoire uniquement si de nouvelles identités doivent être liées.

Opérations prises en charge

Les opérations suivantes sont prises en charge par Real-Time Customer Profile :

Opérations
Description
create
Opération par défaut. Cela génère une méthode de création d’entité XDM pour Real-Time Customer Profile.
merge
Cela génère une méthode de mise à jour d’entité XDM pour Real-Time Customer Profile.
delete
Cela génère une méthode de suppression d’entité XDM pour Real-Time Customer Profile et supprime définitivement les données du Profile store.

Les opérations suivantes sont prises en charge par Identity Service :

Opérations
Descriptions
create
Seule opération autorisée pour ce paramètre. Si 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.

NOTE
Dans cet exemple, les identités ne seront pas liées, car aucune opération n’est définie pour l’identité.
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.

recommendation-more-help
461cc884-c234-4a0c-ac75-6efbaafc1394