Activer un jeu de données pour Profile et Identity Service à l’aide des API

Ce tutoriel décrit le processus d’activation d’un jeu de données en vue de son utilisation dans Real-Time Customer Profile et Identity Service. Il est composé des étapes suivantes :

1. Activer un jeu de données à utiliser dans Real-Time Customer Profile à l’aide de l’une des deux options suivantes :
   • Créer un nouveau jeu de données
   • Configurer un jeu de données existant
2. Ingestion de données dans le jeu de données
3. Confirmation de l’ingestion des données par Real-time Customer Profile
4. Confirmation de l’ingestion des données par Identity Service

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 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.
• Identity Service : permet d’activer Real-Time Customer Profile en établissant un lien entre les identités des sources de données disparates ingérées dans Platform.
• Catalog Service : 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 Platform organise les données de l’expérience client.

Les sections suivantes apportent des informations supplémentaires dont vous aurez besoin pour passer avec succès des appels à des API 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 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 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 Platform, consultez la documentation de présentation des sandbox.

Créer un jeu de données activé pour Profile et Service d’identités

Vous pouvez activer un jeu de données pour Real-Time Customer Profile et Identity Service dès sa création ou à tout moment après la création du jeu de données. Si vous souhaitez activer un jeu de données déjà créé, suivez les étapes de configuration d’un jeu de données existant qui se trouvent plus bas dans ce document.

Pour créer un jeu de données activé pour Profil, vous pouvez utiliser une requête POST au point d’entrée /dataSets.

Format d’API

POST /dataSets

Requête

En incluant unifiedProfile et unifiedIdentity sous tags dans le corps de la requête, le jeu de données sera immédiatement activé pour Profile et Identity Service respectivement. Les valeurs de ces balises doivent être un tableau contenant la chaîne "enabled:true".

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 '{
    "schemaRef": {
        "id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
        "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
    },
    "tags": {
       "unifiedProfile": ["enabled:true"],
       "unifiedIdentity": ["enabled:true"]
    }
  }'

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}". Une fois le jeu de données créé et activé, passez à l’étape du chargement des données.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Configurer un jeu de données existant

Les étapes suivantes expliquent comment activer un jeu de données précédemment créé pour Real-Time Customer Profile et Identity Service. Si vous avez déjà créé un jeu de données activé pour Profile, passez à l’étape de l’ingestion de données.

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

À l’aide de l’API Catalog, vous pouvez examiner un jeu de données existant afin de déterminer s’il est activé pour une utilisation dans Real-Time Customer Profile et Identity Service. 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}

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": "Commission Program Events DataSet",
        "imsOrg": "{ORG_ID}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedProfile": [
                "enabled:true"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ]
        },
        "version": "1.0.1",
        "created": 1536536917382,
        "updated": 1539793978215,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "viewId": "5b020a27e7040801dedbf46f",
        "files": "@/dataSets/5b020a27e7040801dedbf46e/views/5b020a27e7040801dedbf46f/files",
        "schema": "@/xdms/context/experienceevent",
        "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 et unifiedIdentity sont tous les deux présents et affichent la valeur enabled:true. Par conséquent, Real-Time Customer Profile et Identity Service sont activés pour ce jeu de données, respectivement.

Activer le jeu de données

Si le jeu de données existant n’a pas été activé pour Profile ou Identity Service, vous pouvez l’activer en effectuant une requête PATCH à l’aide de l’identifiant du jeu de données.

Format d’API

PATCH /dataSets/{DATASET_ID}

Requête

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"] },
        { "op": "add", "path": "/tags/unifiedIdentity", "value": ["enabled:true"] }
      ]'

Le corps de la requête comprend un path à deux types de balises, unifiedProfile et unifiedIdentity. Le value de chacune de ces balises sont des tableaux contenant la chaîne 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é ajoutées, et le jeu de données est activé pour une utilisation dans Profile et Identity Service.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Ingérer des données dans le jeu de données

Real-Time Customer Profile et Identity Service utilisent tous deux des données XDM lors de leur ingestion dans un jeu de données. Pour apprendre à charger des données dans un jeu de données, reportez-vous au tutoriel sur la création d’un jeu de données à l’aide d’API. Lors de la planification des données à envoyer à votre jeu de données activé pour Profile, tenez compte des bonnes pratiques suivantes :

• Incluez toutes les données à utiliser comme critères de segmentation.
• Incluez autant d’identifiants que vous pouvez en valider à partir des données de profil afin d’optimiser le graphique d’identités. Cela permet à Identity Service de regrouper plus efficacement les identités à l’échelle des jeux de données.

Confirmer l’ingestion des données par Real-Time Customer Profile

Lors du premier chargement de données vers un nouveau jeu de données ou dans le cadre d’un processus impliquant un nouveau ETL ou une nouvelle source de données, il est recommandé de vérifier soigneusement les données afin de s’assurer qu’elles ont été chargées comme prévu. Grâce à l’API Access Real-Time Customer Profile, vous pouvez récupérer des données de lots lors de leur chargement dans un jeu de données. Si vous ne parvenez pas à récupérer les entités attendues, il se peut que votre jeu de données ne soit pas activé pour Real-Time Customer Profile. Une fois que vous avez confirmé que votre jeu de données a été activé, assurez-vous que le format et les identifiants des données sources répondent à vos attentes. Pour obtenir des instructions détaillées sur l’utilisation de l’API Real-Time Customer Profile pour accéder aux données Profile, reportez-vous au guide de point d’entrée des entités, également appelé l’API « Profile Access ».

Confirmer l’ingestion des données par le Service d’identités

Chaque fragment de données ingéré contenant plusieurs identités crée un lien dans votre graphique d’identités privé. Pour plus d’informations sur les graphiques d’identités et sur l’accès aux données d’identité, veuillez commencer par lire la présentation d’Identity Service.

Ressources Business.Adobe.com