Documentation Experience Platform Guide des catalogues et des jeux de données

Activer un jeu de données pour les mises à jour de profil à l’aide d’API

4 avril 2025

Rubriques :
Catalogue

Créé pour :

Développeur

Ce tutoriel décrit le processus d’activation d’un jeu de données avec des fonctionnalités « d’upsert » pour faire les mises à jour des données du profil client en temps réel. Ceci inclut les étapes de création d’un nouveau jeu de données et la configuration d’un jeu de données existant.

NOTE

Le workflow décrit dans ce tutoriel ne fonctionne que pour l’ingestion par lots. Pour les upserts d’ingestion en flux continu, reportez-vous au guide sur l’envoi de mises à jour de lignes partielles au profil client en temps réel à l’aide de la préparation des données.

Prise en main

Ce tutoriel nécessite une connaissance pratique des différents services Adobe Experience Platform impliqués dans la gestion des jeux de données activés pour Profil. Avant de commencer ce tutoriel, consultez la documentation relative à ces services Experience Platform associés :

Real-Time Customer Profile : fournit un profil de consommateur unifié en temps réel, basé sur des données agrégées provenant de plusieurs sources.
Catalog Service : une API RESTful qui vous permet de créer des jeux de données et de les configurer pour Real-Time Customer Profile et Identity Service.
Experience Data Model (XDM) : cadre normalisé selon lequel Experience Platform organise les données de l’expérience client.
Ingestion par lots : l’API d’ingestion par lots vous permet d’ingérer des données dans Experience Platform sous forme de fichiers par lots.

Les sections suivantes apportent des informations supplémentaires dont vous aurez besoin afin de passer des appels avec succès aux API Experience Platform.

Lecture d’exemples d’appels API

Ce tutoriel fournit des exemples d’appels API pour démontrer comment formater vos requêtes. Il s’agit notamment de chemins d’accès, d’en-têtes requis et de payloads de requêtes correctement formatés. L’exemple JSON renvoyé dans les réponses de l’API est également fourni. Pour plus d’informations sur les conventions utilisées dans la documentation pour les exemples d’appels d’API, voir la section concernant la lecture d’exemples d’appels d’API dans le guide de dépannage Experience Platform.

Collecte des valeurs des en-têtes requis

Pour lancer des appels aux API Experience Platform, vous devez d’abord suivre le tutoriel d’authentification. Le tutoriel d’authentification fournit les valeurs de chacun des en-têtes requis dans tous les appels d’API Experience Platform, comme indiqué ci-dessous :

Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {ORG_ID}

Toutes les requêtes contenant une payload (POST, PUT, PATCH) nécessitent un en-tête Content-Type supplémentaire : La valeur correcte de cet en-tête s’affiche dans les exemples de requêtes, le cas échéant.

Dans Experience Platform, toutes les ressources sont isolées dans des sandbox virtuels spécifiques. Toutes les requêtes envoyées aux API Experience Platform nécessitent un en-tête x-sandbox-name spécifiant le nom du sandbox dans lequel l’opération sera effectuée. Pour plus d’informations sur les sandbox dans Experience Platform, consultez la documentation de présentation des sandbox.

Créer un jeu de données activé pour les mises à jour de profil

Lors de la création d’un jeu de données, vous pouvez activer ce jeu de données pour le profil et activer les fonctionnalités de mise à jour.

NOTE

Pour créer un nouveau jeu de données activé pour Profil, vous devez connaître l’identifiant d’un schéma XDM existant et activé pour Profil. Pour plus d’informations sur la recherche ou la création d’un schéma activé pour Profil, reportez-vous au tutoriel sur la création d’un schéma à l’aide de l’API Schema Registry.

Pour créer un jeu de données activé pour le profil et les mises à jour, utilisez une requête POST au point d’entrée /dataSets.

Format d’API

POST /dataSets

Requête

En incluant à la fois le unifiedIdentity et le unifiedProfile sous tags dans le corps de la requête, le jeu de données sera activé pour Profile à la création. Dans le tableau unifiedProfile, l’ajout de isUpsert:true permettra au jeu de données de prendre en charge les mises à jour.

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "Sample dataset",
        "description: "A sample dataset with a sample description.",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
            "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
        },
        "tags": {
            "unifiedIdentity": [
                "enabled: true"
            ],
            "unifiedProfile": [
                "enabled: true",
                "isUpsert: true"
            ]
        }
      }'

Propriété

Description

schemaRef.id

L’ID du schéma activé pour Profile sur lequel le jeu de données sera basé.

{TENANT_ID}

L’espace de noms dans Schema Registry qui contient les ressources appartenant à votre organisation. Pour plus d’informations, consultez la section TENANT_ID du guide de développement Schema Registry.

Réponse

Une réponse réussie affiche un tableau contenant l’identifiant du jeu de données nouvellement créé sous la forme d’un "@/dataSets/{DATASET_ID}".

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Configurer un jeu de données existant

Les étapes suivantes expliquent comment configurer un jeu de données existant activé pour un profil pour permettre une mise à jour (upsert).

NOTE

Pour configurer un jeu de données existant activé pour un profil en vue de sa mise à jour, vous devez d’abord désactiver le jeu de données pour le profil puis le réactiver avec la balise isUpsert. Si le jeu de données existant n’est pas activé pour le profil, vous pouvez passer directement aux étapes d’activation du jeu de données pour le profil et l’upsert. Si vous n’êtes pas sûr, les étapes suivantes vous montrent comment vérifier si le jeu de données est déjà activé.

Vérifier si le jeu de données est activé pour le profil

En utilisant l’API Catalog, vous pouvez examiner un jeu de données existant et déterminer s’il est activé pour une utilisation dans Real-Time Customer Profile. L’appel suivant récupère les détails d’un jeu de données via son identifiant.

Format d’API

GET /dataSets/{DATASET_ID}

Paramètre

Description

{DATASET_ID}

Identifiant du jeu de données à examiner.

Requête

curl -X GET 'https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Réponse

{
    "5b020a27e7040801dedbf46e": {
        "name": "{DATASET_NAME}",
        "imsOrg": "{ORG_ID}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ],
            "unifiedProfile": [
                "enabled:true"
            ]
        },
        "version": "1.0.1",
        "created": 1536536917382,
        "updated": 1539793978215,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "viewId": "{VIEW_ID}",
        "files": "@/dataSetFiles?dataSetId=5b020a27e7040801dedbf46e",
        "schema": "{SCHEMA}",
        "schemaRef": {
            "id": "https://ns.adobe.com/xdm/context/experienceevent",
            "contentType": "application/vnd.adobe.xed+json"
        }
    }
}

Sous la propriété tags, vous pouvez voir que unifiedProfile est présent avec la valeur enabled:true. Par conséquent, Real-Time Customer Profile est activé pour ce jeu de données.

Désactiver le jeu de données pour Profil

Pour configurer un jeu de données activé pour le profil pour les mises à jour, vous devez d’abord désactiver les balises unifiedProfile et unifiedIdentity puis les réactiver avec la balise isUpsert. Cette opération s’effectue à l’aide de deux requêtes PATCH, une pour la désactivation et une pour la réactivation.

WARNING

Les données ingérées dans le jeu de données alors qu’il est désactivé ne seront pas ingérées dans la banque de profils. Vous devez éviter d’ingérer des données dans le jeu de données jusqu’à ce qu’il ait été réactivé pour Profil.

Format d’API

PATCH /dataSets/{DATASET_ID}

Paramètre

Description

{DATASET_ID}

Identifiant du jeu de données à mettre à jour.

Requête

Le premier corps de requête PATCH comprend un path vers unifiedProfile et un path vers unifiedIdentity, qui définissent value sur enabled:false pour ces deux chemins afin de désactiver les balises.

curl -X PATCH https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
            "op": "replace",
            "path": "/tags/unifiedProfile",
            "value": ["enabled:false"]
        },
        {
            "op": "replace",
            "path": "/tags/unifiedIdentity",
            "value": ["enabled:false"]
        }
      ]'

Réponse

Une requête PATCH réussie renvoie un statut HTTP 200 (OK) et un tableau contenant l’identifiant du jeu de données mis à jour. Cet identifiant doit correspondre à celui envoyé dans la requête PATCH. Les balises unifiedProfile et unifiedIdentity ont désormais été désactivées.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Activer le jeu de données pour Profil et upsert

Un jeu de données existant peut être activé pour les mises à jour de Profil et d’attribut à l’aide d’une seule requête PATCH.

IMPORTANT

Lors de l’activation de votre jeu de données pour Profil, assurez-vous que le schéma auquel le jeu de données est associé est également activé pour Profil. Si le schéma n’est pas activé pour Profil, le jeu de données n’apparaîtra pas en tant qu’activé pour Profil dans l’interface utilisateur d’Experience Platform.

Format d’API

PATCH /dataSets/{DATASET_ID}

Paramètre

Description

{DATASET_ID}

Identifiant du jeu de données à mettre à jour.

Requête

Le corps de la requête comprend un path vers unifiedProfile qui définit value pour inclure les balises enabled et isUpsert, toutes deux définies sur true, et un path vers unifiedIdentity qui définit value pour inclure la balise enabled définie sur true.

curl -X PATCH https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
            "op": "add",
            "path": "/tags/unifiedProfile",
            "value": [
                "enabled:true",
                "isUpsert:true"
            ]
        },
        {
            "op": "add",
            "path": "/tags/unifiedIdentity",
            "value": [
                "enabled:true"
            ]
        }
      ]'

Réponse

Une requête PATCH réussie renvoie un statut HTTP 200 (OK) et un tableau contenant l’identifiant du jeu de données mis à jour. Cet identifiant doit correspondre à celui envoyé dans la requête PATCH. Les balises unifiedProfile et unifiedIdentity ont maintenant été activées et configurées pour les mises à jour d’attributs.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Étapes suivantes

Votre jeu de données activé pour Profil et upsert peut désormais être utilisé par les workflows d’ingestion par lots pour mettre à jour les données de profil. Pour en savoir plus sur l’ingestion de données dans Adobe Experience Platform, commencez par lire la présentation de l’ingestion des données.

recommendation-more-help