Documentation Experience Platform Guide de modèle de données d’expérience (XDM)

Point d’entrée Unions

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Rubriques :

Créé pour :

Développeur

Les unions (ou vues d’union) sont des schémas en lecture seule générés par le système qui regroupent les champs de tous les schémas qui partagent la même classe (XDM ExperienceEvent ou XDM Individual Profile) et sont activés pour Real-Time Customer Profile.

Ce document couvre les concepts essentiels pour travailler avec les unions dans l’API Schema Registry, y compris des exemples d’appels pour diverses opérations. Pour plus d’informations générales sur les unions dans XDM, consultez la section sur les unions dans le Principe de base de la composition des schémas.

Champs de schéma d’union

Schema Registry inclut automatiquement trois champs clés dans un schéma d’union : identityMap, timeSeriesEvents et segmentMembership.

Mappage d’identités

Un schéma d’union identityMap est une représentation des identités connues dans les schémas d’enregistrement associés de l’union. Le mappage d’identités sépare les identités en différents tableaux saisis par espace de noms. Chaque identité répertoriée est elle-même un objet contenant une valeur id unique. Pour plus d’informations, voir la documentation du service d’identités.

Événements de série temporelle

Le tableau timeSeriesEvents est une liste d’événements de série temporelle liés aux schémas d’enregistrement associés à l’union. Lorsque les données de profil sont exportées vers des jeux de données, ce tableau est inclus pour chaque enregistrement. Ceci est utile pour divers cas d’utilisation, tels que le machine learning où les modèles ont besoin de l’historique complet du comportement d’un profil en plus de ses attributs d’enregistrement.

Mappage de l’adhésion aux segments

La carte segmentMembership stocke les résultats de l’évaluation d’une définition de segment. Lorsque les tâches de segmentation sont exécutées avec succès à l’aide de l’API Segmentation, le mappage est mis à jour. segmentMembership stocke également toutes les audiences préévaluées ingérées dans Platform, ce qui permet l’intégration à d’autres solutions comme Adobe Audience Manager. Pour plus d’informations, consultez le tutoriel sur la création d’audiences à l’aide d’API .

Récupération d’une liste d’unions list

Lorsque vous définissez la balise union sur un schéma, Schema Registry ajoute automatiquement le schéma à l’union pour la classe sur laquelle le schéma est basé. S’il n’existe aucune union pour la classe en question, une nouvelle union est automatiquement créée. $id pour l’union est similaire à la $id standard des autres ressources Schema Registry, la seule différence étant que la seule différence est ajoutée par deux traits de soulignement et le mot "union" (__union).

Vous pouvez afficher une liste des unions disponibles en envoyant une requête de GET au point de terminaison /tenant/unions.

Format d’API

GET /tenant/unions

Requête

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/unions \
  -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}' \
  -H 'Accept: application/vnd.adobe.xed-id+json'

Le format de la réponse dépend de l’en-tête Accept envoyé dans la requête. Les en-têtes Accept suivants sont disponibles pour répertorier les unions :

En-tête Accept

Description

application/vnd.adobe.xed-id+json

Renvoie un court résumé de chaque ressource. Il s’agit de l’en-tête recommandé pour répertorier les ressources. (Limite : 300)

application/vnd.adobe.xed+json

Renvoie la classe JSON complète pour chaque ressource, avec les $ref et allOf d'origine inclus. (Limite : 300)

Réponse

Une réponse réussie renvoie un état HTTP 200 (OK) et un tableau results dans le corps de la réponse. Si des unions ont été définies, les détails de chaque union sont fournis sous la forme d’objets dans le tableau. Si aucune union n’a été définie, un état HTTP 200 (OK) est toujours renvoyé, mais le tableau results est vide.

{
    "results": [
        {
            "title": "XDM Individual Profile",
            "$id": "https://ns.adobe.com/xdm/context/profile__union",
            "meta:altId": "_xdm.context.profile__union",
            "version": "1"
        },
        {
            "title": "Property",
            "$id": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590__union",
            "meta:altId": "_{TENANT_ID}.classes.19e1d8b5098a7a76e2c10a81cbc99590__union",
            "version": "1"
        }
    ]
}

Recherche d’une union lookup

Vous pouvez voir une union spécifique en exécutant une requête GET qui inclut l’$id et, selon l’en-tête Accept, certains ou tous les détails de l’union.

NOTE

Les recherches d’unions sont disponibles à l’aide du point de terminaison /unions et /schemas pour les activer pour une utilisation dans les exportations Profile dans un jeu de données.

Format d’API

GET /tenant/unions/{UNION_ID}
GET /tenant/schemas/{UNION_ID}

Paramètre

Description

{UNION_ID}

URI $id encodé URL de l’union que vous souhaitez rechercher. Les URI pour les schémas d’unions sont suivis de « __union ».

Requête

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/unions/https%3A%2F%2Fns.adobe.com%2Fxdm%2Fcontext%2Fprofile__union \
  -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}' \
  -H 'Accept: application/vnd.adobe.xed+json; version=1'

Les requêtes de recherche d’unions requièrent que version soit inclus dans l’en-tête Accept.

Les en-têtes Accept suivants sont disponibles pour les recherches de schémas d’unions :

Description

application/vnd.adobe.xed+json; version=1

Raw avec $ref et allOf. Contient des titres et des descriptions.

application/vnd.adobe.xed-full+json; version=1

Attributs $ref et allOf résolus. Contient des titres et des descriptions.

Réponse

Une réponse réussie renvoie la vue d’union de tous les schémas qui implémentent la classe dont le $id a été fourni dans le chemin de la requête.

Le format de la réponse dépend de l’en-tête Accept envoyé dans la requête. Testez différents en-têtes Accept pour comparer les réponses et déterminer l’en-tête qui convient le mieux à votre cas d’utilisation.

{
    "type": "object",
    "description": "Union view of all schemas that extend https://ns.adobe.com/xdm/context/profile",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/477bb01d7125b015b4feba7bccc2e599"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
        }
    ],
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/common/extensible",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/{TENANT_ID}/mixins/477bb01d7125b015b4feba7bccc2e599",
        "https://ns.adobe.com/xdm/context/profile-personal-details"
    ],
    "title": "Union object for https://ns.adobe.com/xdm/context/profile",
    "$id": "https://ns.adobe.com/xdm/context/profile__union",
    "meta:containerId": "tenant",
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:altId": "_xdm.context.profile__union",
    "version": "1.0",
    "meta:resourceType": "unions",
    "meta:registryMetadata": {}
}

Activation d’un segment pour un abonnement à l’union enable

Pour qu’un schéma soit inclus dans l’union pour sa classe, une balise union doit être ajoutée à l’attribut meta:immutableTags du schéma. Pour ce faire, vous pouvez envoyer une requête de PATCH pour ajouter un tableau meta:immutableTags avec une seule valeur de chaîne union au schéma en question. Pour obtenir un exemple détaillé, consultez le guide de point d’entrée des schémas .

Liste des schémas dans une union list-schemas

Afin de voir quels schémas font partie d’une union spécifique, vous pouvez exécuter une requête de GET sur le point de terminaison /tenant/schemas. En utilisant le paramètre de requête property, vous pouvez configurer la réponse afin de renvoyer uniquement les schémas contenant un champ meta:immutableTags et un meta:class égal à la classe de l’union à laquelle vous accédez.

Format d’API

GET /tenant/schemas?property=meta:immutableTags==union&property=meta:class=={CLASS_ID}

Paramètre

Description

{CLASS_ID}

$id de la classe dont vous souhaitez répertorier les schémas activés pour l’union.

Requête

La requête suivante récupère une liste de tous les schémas qui font partie de l’union pour la classe XDM Individual Profile.

curl -X GET \
  'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas?property=meta:immutableTags==union&property=meta:class==https://ns.adobe.com/xdm/context/profile' \
  -H 'Accept: application/vnd.adobe.xed-id+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}'

Le format de la réponse dépend de l’en-tête Accept envoyé dans la requête. Les en-têtes Accept suivants sont disponibles pour répertorier les schémas :

En-tête Accept

Description

application/vnd.adobe.xed-id+json

Renvoie un court résumé de chaque ressource. Il s’agit de l’en-tête recommandé pour répertorier les ressources. (Limite : 300)

application/vnd.adobe.xed+json

Renvoie le schéma JSON complet pour chaque ressource, avec les $ref et allOf d'origine inclus. (Limite : 300)

Réponse

Une réponse réussie renvoie une liste filtrée de schémas, contenant uniquement ceux qui appartiennent à la classe spécifiée et qui ont été activés pour l’adhésion à l’union. N’oubliez pas que lorsque vous utilisez plusieurs paramètres de requête, une relation ET est utilisée.

{
    "results": [
        {
            "title": "Schema 1",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/142afb78d8b368a5ba97a6cc8fc7e033",
            "meta:altId": "_{TENANT_ID}.schemas.142afb78d8b368a5ba97a6cc8fc7e033",
            "version": "1.2"
        },
        {
            "title": "Schema 2",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/e7297a6ddfc7812ab3a7b504a1ab98da",
            "meta:altId": "_{TENANT_ID}.schemas.e7297a6ddfc7812ab3a7b504a1ab98da",
            "version": "1.5"
        },
        {
            "title": "Schema 3",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/50f960bb810e99a21737254866a477bf",
            "meta:altId": "_{TENANT_ID}.schemas.50f960bb810e99a21737254866a477bf",
            "version": "1.2"
        },
        {
            "title": "Schema 4",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/a39655ca8ea3d5c1f36a463b45fccca8",
            "meta:altId": "_{TENANT_ID}.schemas.a39655ca8ea3d5c1f36a463b45fccca8",
            "version": "1.1"
        },
        {
            "title": "Schema 5",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/c063fac45c6d6285ef33b0e2af09f633",
            "meta:altId": "_{TENANT_ID}.schemas.c063fac45c6d6285ef33b0e2af09f633",
            "version": "1.2"
        },
        {
            "title": "Schema 6",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/dfebb19b93827b70bbad006137812537",
            "meta:altId": "_{TENANT_ID}.schemas.dfebb19b93827b70bbad006137812537",
            "version": "1.7"
        }
    ],
    "_links": {
        "global_schemas": {
            "href": "https://platform.adobe.io/data/foundation/schemaregistry/global/schemas?property=meta:immutableTags==union&property=meta:class==https://ns.adobe.com/xdm/context/profile"
        }
    }
}

recommendation-more-help

62e9ffd9-1c74-4cef-8f47-0d00af32fc07