Show Menu
SUJETS×

Descripteurs

Les schémas définissent un affichage statique des entités de données, mais ne fournissent pas de détails spécifiques sur la manière dont les données basées sur ces schémas (jeux de données, par exemple) peuvent être reliées entre elles. Adobe Experience Platform vous permet de décrire ces relations et d’autres métadonnées interprétatives relatives à un schéma à l’aide de descripteurs.
Les descripteurs de schéma sont des métadonnées au niveau du client, ce qui signifie qu’ils sont propres à votre organisation IMS et que toutes les opérations de descripteur se déroulent dans le conteneur du client.
Une ou plusieurs entités de descripteur de schéma peuvent être appliquées à chaque schéma. Chaque entité de descripteur de schéma comprend un descripteur @type et le sourceSchema auquel il s’applique. Une fois appliqués, ces descripteurs s’appliquent à tous les jeux de données créés à l’aide du schéma.
Ce document fournit des exemples d’appels API pour les descripteurs, ainsi qu’une liste complète des descripteurs disponibles et des champs requis pour la définition de chaque type.
Descriptors require unique Accept headers that replace xed with xdm , but otherwise look very similar to Accept headers used elsewhere in the Schema Registry. Les en-têtes Accept appropriés ont été inclus dans les exemples d’appels ci-dessous, mais soyez particulièrement vigilants quant à l’utilisation des en-têtes corrects.

Descripteurs de la liste

Une requête GET unique peut être utilisée pour renvoyer une liste de tous les descripteurs définis par votre organisation.
Format d’API
GET /tenant/descriptors

Requête
curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xdm-link+json'

Le format de la réponse dépend de l’en-tête Accept envoyé dans la requête. Notez que le point de terminaison /descriptors utilise des en-têtes Accept différents de tous les autres points de terminaison dans l’API Schema Registry
Les en-têtes Accept du descripteur remplacent xed par xdm et offrent une option link propre aux descripteurs.
Accept
Description
application/vnd.adobe.xdm-id+json
Renvoie un tableau d’identifiants de descripteur
application/vnd.adobe.xdm-link+json
Renvoie un tableau de chemins d’API de descripteur
application/vnd.adobe.xdm+json
Renvoie un tableau d’objets de descripteurs étendus
Réponse
La réponse comprend un tableau pour chaque type de descripteur possédant des descripteurs définis. En d’autres termes, s’il n’existe aucun descripteur d’un certain @type défini, le registre ne renvoie pas de tableau vide pour ce type de descripteur.
Lors de l’utilisation de l’en-tête Accept link , chaque descripteur est présenté sous la forme d’un tableau au format /{CONTAINER}/descriptors/{DESCRIPTOR_ID}
{
  "xdm:alternateDisplayInfo": [
    "/tenant/descriptors/85dc1bc8b91516ac41163365318e38a9f1e4f351",
    "/tenant/descriptors/49bd5abb5a1310ee80ebc1848eb508d383a462cf",
    "/tenant/descriptors/b3b3e548f1c653326bcf5459ceac4140fc0b9e08"
  ],
  "xdm:descriptorIdentity": [
    "/tenant/descriptors/f7a4bc25429496c4740f8f9a7a49ba96862c5379"
  ],
  "xdm:descriptorOneToOne": [
    "/tenant/descriptors/cb509fd6f8ab6304e346905441a34b58a0cd481a"
  ]
}

Recherche d’un descripteur

Si vous souhaitez consulter les détails d’un descripteur spécifique, vous pouvez rechercher (GET) un descripteur individuel à l’aide de son identifiant @id .
Format d’API
GET /tenant/descriptors/{DESCRIPTOR_ID}

Paramètre
Description
{DESCRIPTOR_ID}
L’identifiant @id du descripteur que vous souhaitez rechercher.
Requête
Les descripteurs n’ont pas de version. Par conséquent, aucun en-tête Accept n’est requis dans la requête de recherche.
curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Réponse
Une réponse réussie renvoie les détails du descripteur, y compris ses @type et sourceSchema , ainsi que des informations supplémentaires qui varient selon le type de descripteur. L’identifiant @id renvoyé doit correspondre à l’identifiant @id du descripteur fourni dans la requête.
{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "createdUser": "{CREATED_USER}",
  "imsOrg": "{IMS_ORG}",
  "createdClient": "{CREATED_CLIENT}",
  "updatedUser": "{UPDATED_USER}",
  "created": 1548899346989,
  "updated": 1548899346989,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Création d’un descripteur

The Schema Registry allows you to define several different descriptor types. Chaque type de descripteur nécessite l’envoi de ses propres champs spécifiques dans la requête POST. Une liste complète des descripteurs, ainsi que des champs nécessaires pour les définir, est disponible dans la section de l’annexe sur la définition des descripteurs .
Format d’API
POST /tenant/descriptors

Requête
La requête suivante définit un descripteur d’identité dans un champ « adresse électronique » d’un exemple de schéma. This tells Experience Platform to use the email address as an identifier to help stitch together information about the individual.
curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -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 '
      {
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/personalEmail/address",
        "xdm:namespace": "Email",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

Réponse
Une réponse réussie renvoie un état HTTP 201 (Created) et les détails du nouveau descripteur, y compris son identifiant @id . The @id is a read-only field assigned by the Schema Registry and used for referencing the descriptor in the API.
{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Mise à jour du descripteur

Vous pouvez mettre à jour un descripteur en effectuant une requête PUT qui référence l’identifiant @id du descripteur que vous souhaitez mettre à jour dans le chemin de la requête.
Format d’API
PUT /tenant/descriptors/{DESCRIPTOR_ID}

Paramètre
Description
{DESCRIPTOR_ID}
L’identifiant @id du descripteur que vous souhaitez mettre à jour.
Requête
Cette requête réécrit essentiellement le descripteur. Le corps de la requête doit donc inclure tous les champs nécessaires pour définir un descripteur de ce type. En d’autres termes, le payload de requête pour mettre à jour (PUT) un descripteur est identique au payload pour créer (POST) un descripteur du même type.
Dans cet exemple, le descripteur d’identité est mis à jour pour référencer un autre xdm:sourceProperty (« téléphone mobile ») et remplacer xdm:namespace par « Téléphone ».
curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -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 '{
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/mobilePhone/number",
        "xdm:namespace": "Phone",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

Les détails concernant les propriétés xdm:namespace et xdm:property , y compris la manière d’y accéder, sont disponibles dans la section de l’annexe sur la définition des descripteurs .
Réponse
Une réponse réussie renvoie un état HTTP 201 (Created) et l’identifiant @id du descripteur mis à jour (qui doit correspondre à l’identifiant @id envoyé dans la requête).
{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

En effectuant une requête de recherche (GET) pour afficher le descripteur, vous verrez que les champs ont été mis à jour pour refléter les changements envoyés dans la requête PUT.

Suppression du descripteur

Occasionally you may need to remove a descriptor that you have defined from the Schema Registry. Pour ce faire, effectuez une requête DELETE en référençant l’identifiant @id du descripteur que vous souhaitez supprimer.
Format d’API
DELETE /tenant/descriptors/{DESCRIPTOR_ID}

Paramètre
Description
{DESCRIPTOR_ID}
L’identifiant @id du descripteur que vous souhaitez supprimer.
Requête
Les en-têtes Accept ne sont pas nécessaires lors de la suppression de descripteurs.
curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/ca921946fb5281cbdb8ba5e07087486ce531a1f2  \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Réponse
Une réponse réussie renvoie un état HTTP 204 (No Content) et un corps vide.
Pour confirmer la suppression du descripteur, vous pouvez effectuer une requête de recherche concernant l’identifiant @id du descripteur. The response returns HTTP status 404 (Not Found) because the descriptor has been removed from the Schema Registry.

Annexe

The following section provides additional information regarding working with descriptors in the Schema Registry API.

Définition de descripteurs

Les sections suivantes présentent les types de descripteurs disponibles, y compris les champs nécessaires pour définir un descripteur de chaque type.

Descripteur d’identité

An identity descriptor signals that the "sourceProperty" of the "sourceSchema" is an Identity field as described by Adobe Experience Platform Identity Service .
{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false
}

Propriété
Description
@type
Le type de descripteur en cours de définition.
xdm:sourceSchema
L’URI $id du schéma dans lequel le descripteur est défini.
xdm:sourceVersion
La version principale du schéma source.
xdm:sourceProperty
Le chemin vers la propriété spécifique qui sera l’identité. Le chemin doit commencer et non se terminer par un « / ». N’incluez pas « properties » dans le chemin (par exemple, utilisez « /personalEmail/address » au lieu de « /properties/personalEmail/properties/address »)
xdm:namespace
La valeur id ou code de l’espace de noms de l’identité. A list of namespaces can be found using the Identity Service API .
xdm:property
xdm:id ou xdm:code selon l’espace de noms xdm:namespace utilisé.
xdm:isPrimary
Une valeur booléenne facultative. Lorsqu’elle est définie sur true, le champ est l’identité principale. Les schémas ne peuvent contenir qu’une seule identité principale.

Descripteur de nom convivial

Friendly name descriptors allow a user to modify the title , description , and meta:enum values of the core library schema fields. Ils sont particulièrement utiles lorsque vous utilisez des « eVars » et d’autres champs « génériques » auxquels vous souhaitez appliquer des libellés indiquant qu’ils contiennent des informations propres à votre organisation. L’interface utilisateur peut les utiliser pour afficher un nom plus convivial ou pour n’afficher que les champs dont le nom est convivial.
{
  "@type": "xdm:alternateDisplayInfo",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/xdm:eventType",
  "xdm:title": {
    "en_us": "Event Type"
  },
  "xdm:description": {
    "en_us": "The type of experience event detected by the system."
  },
  "meta:enum": {
    "click": "Mouse Click",
    "addCart": "Add to Cart",
    "checkout": "Cart Checkout"
  }
}

Propriété
Description
@type
Le type de descripteur en cours de définition.
xdm:sourceSchema
L’URI $id du schéma dans lequel le descripteur est défini.
xdm:sourceVersion
La version principale du schéma source.
xdm:sourceProperty
Le chemin vers la propriété spécifique qui sera l’identité. Le chemin doit commencer et non se terminer par un « / ». N’incluez pas « properties » dans le chemin (par exemple, utilisez « /personalEmail/address » au lieu de « /properties/personalEmail/properties/address »)
xdm:title
Le nouveau titre que vous souhaitez afficher pour ce champ, écrit en Casse Titre.
xdm:description
Vous pouvez ajouter une description facultative avec le titre.
meta:enum
Si le champ indiqué par xdm:sourceProperty est un champ de chaîne, meta:enum détermine la liste des valeurs suggérées pour le champ dans l’ Experience Platform interface utilisateur. Il est important de noter que meta:enum ne déclare pas de énumération ou ne fournit aucune validation de données pour le champ XDM.
Ceci ne doit être utilisé que pour les champs XDM principaux définis par Adobe. Si la propriété source est un champ personnalisé défini par votre organisation, vous devez modifier la meta:enum propriété du champ directement par le biais d’une requête de PATCH.

Descripteur de relation

Les descripteurs de relation décrivent une relation entre deux schémas différents, en fonction des propriétés décrites dans sourceProperty et destinationProperty . Pour plus d’informations, consultez le tutoriel sur la définition d’une relation entre deux schémas .
{
  "@type": "xdm:descriptorOneToOne",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:destinationSchema": 
    "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:destinationVersion": 1,
  "xdm:destinationProperty": "/parentField/subField"
}

Propriété
Description
@type
Le type de descripteur en cours de définition.
xdm:sourceSchema
L’URI $id du schéma dans lequel le descripteur est défini.
xdm:sourceVersion
La version principale du schéma source.
xdm:sourceProperty
Chemin vers le champ du schéma source dans lequel la relation est définie. Doit commencer et non se terminer par un « / ». N’incluez pas « properties » dans le chemin (par exemple, « /personalEmail/address » au lieu de « /properties/personalEmail/properties/address »).
xdm:destinationSchema
L’URI $id du schéma de destination avec lequel ce descripteur définit une relation.
xdm:destinationVersion
La version principale du schéma de destination.
xdm:destinationProperty
Chemin facultatif vers un champ cible dans le schéma de destination. Si cette propriété est omise, le champ cible est déterminé par les champs qui contiennent un descripteur d’identité de référence correspondant (voir ci-dessous).

Descripteur d’identité de référence

Les descripteurs d'identité de référence fournissent un contexte de référence à l'identité Principale d'un champ de schéma, ce qui permet de le référencer par des champs d'autres schémas. Les champs doivent déjà disposer d’un libellé de descripteur d’identité avant qu’un descripteur de référence puisse leur être appliqué.
{
  "@type": "xdm:descriptorReferenceIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:identityNamespace": "Email"
}

Propriété
Description
@type
Le type de descripteur en cours de définition.
xdm:sourceSchema
L’URI $id du schéma dans lequel le descripteur est défini.
xdm:sourceVersion
La version principale du schéma source.
xdm:sourceProperty
Chemin vers le champ du schéma source dans lequel le descripteur est défini. Doit commencer et non se terminer par un « / ». N’incluez pas « properties » dans le chemin (par exemple, « /personalEmail/address » au lieu de « /properties/personalEmail/properties/address »).
xdm:identityNamespace
Le code d’espace de noms d’identité de la propriété source.