Show Menu
SUJETS×

Descripteurs

Les Schémas définissent une vue 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 se relier les unes aux autres. 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 descripteurs ont lieu dans le conteneur du client.
Un ou plusieurs descripteurs de schéma peuvent être appliqués à chaque schéma. Chaque entité 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 d'API pour les descripteurs, ainsi qu'une liste complète des descripteurs disponibles et des champs requis pour définir chaque type.
Les descripteurs nécessitent des en-têtes Accept uniques qui remplacent xed par xdm , mais qui, autrement, ressemblent beaucoup aux en-têtes Accept utilisés ailleurs dans le registre des Schémas. Les en-têtes Accepter appropriés ont été inclus dans les exemples d’appels ci-dessous, mais soyez prudent pour vous assurer que les en-têtes appropriés sont utilisés.

descripteurs de Liste

Une seule requête GET 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 réponse dépend de l’en-tête Accepter envoyé dans la requête. Notez que le /descriptors point de terminaison utilise des en-têtes Accepter différents de tous les autres points de terminaison dans l'API de Registre de Schéma.
Les en-têtes Accepter du descripteur remplacent xed par xdm et offre une link option propre aux descripteurs.
Accepter
Description
application/vnd.adobe.xdm-id+json
Renvoie un tableau d’ID de descripteur.
application/vnd.adobe.xdm-link+json
Renvoie un tableau de chemins d’API descripteur.
application/vnd.adobe.xdm+json
Renvoie un tableau d’objets descripteurs étendus
Réponse
La réponse comprend un tableau pour chaque type de descripteur qui a défini des descripteurs. En d'autres termes, s'il n'y a pas de descripteurs d'un certain @type type défini, le registre ne retournera pas un tableau vide pour ce type de descripteur.
Lors de l’utilisation de l’en-tête link Accepter, 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"
  ]
}

Rechercher un descripteur

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

Paramètre
Description
{DESCRIPTOR_ID}
Le nom @id du descripteur à rechercher.
Requête
Les descripteurs ne sont pas versionnés. Par conséquent, aucun en-tête Accepter n’est requis dans la demande 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 son @type et sourceSchema ainsi que des informations supplémentaires qui varient selon le type de descripteur. La valeur renvoyée @id doit correspondre au descripteur @id 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éer un descripteur

Le Registre des Schémas vous permet de définir plusieurs types de descripteurs différents. Chaque type de descripteur nécessite l’envoi de ses propres champs spécifiques dans la demande POST. Une liste complète des descripteurs et 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é sur un champ "adresse électronique" dans un exemple de schéma. Cela indique à la plate-forme d’expérience d’utiliser l’adresse électronique comme identifiant afin de mieux rassembler les informations sur l’individu.
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 l’état HTTP 201 (Créé) et les détails du descripteur nouvellement créé, y compris son @id nom. Il @id s’agit d’un champ en lecture seule attribué par le Registre du Schéma et utilisé pour référencer le descripteur dans l’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"
}

Mettre à jour le descripteur

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

Paramètre
Description
{DESCRIPTOR_ID}
Le nom @id du descripteur à mettre à jour.
Requête
Cette requête réécrit essentiellement le descripteur, de sorte que le corps de la requête doit inclure tous les champs nécessaires pour définir un descripteur de ce type. En d’autres termes, la charge utile de requête pour mettre à jour (PUT) un descripteur est identique à la charge utile pour créer (POST) un descripteur du même type.
Dans cet exemple, le descripteur d'identité est en cours de mise à jour afin de référencer un autre xdm:sourceProperty (téléphone mobile) et de remplacer le xdm:namespace mot 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
      }'

Des détails concernant les propriétés xdm:namespace et xdm:property les méthodes d'accès sont disponibles dans la section de l'annexe consacrée à la définition des descripteurs .
Réponse
Une réponse réussie renvoie l’état HTTP 201 (Créé) et le descripteur mis à jour (qui doit correspondre à celui @id @id envoyé dans la demande).
{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

L’exécution d’une demande de recherche (GET) à la vue du descripteur indique que les champs ont été mis à jour pour refléter les modifications envoyées dans la demande de recherche (PUT).

Supprimer le descripteur

Il peut arriver que vous deviez supprimer un descripteur que vous avez défini dans le Registre des Schémas. Pour ce faire, vous devez faire une requête DELETE référençant le descripteur @id que vous souhaitez supprimer.
Format d’API
DELETE /tenant/descriptors/{DESCRIPTOR_ID}

Paramètre
Description
{DESCRIPTOR_ID}
Le nom @id du descripteur à supprimer.
Requête
Les en-têtes d’acceptation ne sont pas requis 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 l’état HTTP 204 (Aucun contenu) et un corps vide.
Pour confirmer que le descripteur a été supprimé, vous pouvez exécuter une requête de recherche sur le descripteur @id . La réponse renvoie l’état HTTP 404 (Introuvable) car le descripteur a été supprimé du registre de Schéma.

Annexe

La section suivante fournit des informations supplémentaires sur l'utilisation des descripteurs dans l'API de registre de Schéma.

Définition de descripteurs

Les sections suivantes présentent un aperçu des types de descripteurs disponibles, y compris les champs requis pour définir un descripteur de chaque type.

Descripteur d'identité

Un descripteur d’identité signale que la "sourceProperty" de "sourceSchema" est un champ d’identité, comme décrit par 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
Type de descripteur en cours de définition.
xdm:sourceSchema
URI $id du schéma où le descripteur est en cours de définition.
xdm:sourceVersion
Version principale du schéma source.
xdm:sourceProperty
Chemin d’accès à la propriété spécifique qui sera l’identité. Le chemin doit commencer par un "/" et ne pas se terminer par un. N’incluez pas de "propriétés" dans le chemin d’accès (par exemple, utilisez "/personalEmail/address" au lieu de "/properties/personalEmail/properties/address").
xdm:namespace
Valeur id ou code valeur de l'espace de nommage d'identité. Vous trouverez une liste d'espaces de nommage à l'aide de l'API id-service-api.yaml Identity Service.
xdm:property
Soit xdm:id soit xdm:code , selon l’ xdm:namespace utilisation.
xdm:isPrimary
Valeur booléenne facultative. Lorsque la valeur est true, le champ est indiqué comme identité principale. Les Schémas ne peuvent contenir qu'une seule identité primaire.

Descripteur de nom convivial

Les descripteurs de nom conviviaux permettent à un utilisateur de modifier les title valeurs et les description valeurs des champs de schéma de bibliothèque principaux. Particulièrement utile lorsque vous travaillez avec des "eVars" et d’autres champs "génériques" que vous souhaitez étiqueter comme contenant des informations spécifiques à votre entreprise. L’interface utilisateur peut les utiliser pour afficher un nom plus convivial ou uniquement pour afficher 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": "/eVars/eVar1",
  "xdm:title": {
    "en_us":{"Loyalty ID"}
  },
  "xdm:description": {
    "en_us":{"Unique ID of loyalty program member."}
  },
}

Propriété
Description
@type
Type de descripteur en cours de définition.
xdm:sourceSchema
URI $id du schéma où le descripteur est en cours de définition.
xdm:sourceVersion
Version principale du schéma source.
xdm:sourceProperty
Chemin d’accès à la propriété spécifique qui sera l’identité. Le chemin doit commencer par un "/" et ne pas se terminer par un. N’incluez pas de "propriétés" dans le chemin d’accès (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 dans la casse de titre.
xdm:description
Une description facultative peut être ajoutée avec le titre.

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 la section sourceProperty et destinationProperty . Pour plus d'informations, consultez le didacticiel 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
Type de descripteur en cours de définition.
xdm:sourceSchema
URI $id du schéma où le descripteur est en cours de définition.
xdm:sourceVersion
Version principale du schéma source.
xdm:sourceProperty
Chemin d’accès au champ du schéma source dans lequel la relation est définie. Doit commencer par un "/" et ne pas se terminer par un. N’incluez pas "properties" dans le chemin d’accès (par exemple, "/personalEmail/address" au lieu de "/properties/personalEmail/properties/address").
xdm:destinationSchema
L' $id URI du schéma de destination avec lequel ce descripteur définit une relation.
xdm:destinationVersion
Version principale du schéma de destination.
xdm:destinationProperty
Chemin d’accès facultatif à un champ de cible dans le schéma de destination. Si cette propriété est omise, le champ de cible est déduit 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 à un champ de schéma, ce qui permet de le lier au champ d'identité principal d'un schéma de destination. Les champs doivent déjà être étiquetés avec un descripteur d'identité avant qu'un descripteur de référence ne 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
Type de descripteur en cours de définition.
xdm:sourceSchema
URI $id du schéma où le descripteur est en cours de définition.
xdm:sourceVersion
Version principale du schéma source.
xdm:sourceProperty
Chemin d’accès au champ du schéma source dans lequel le descripteur est en cours de définition. Doit commencer par un "/" et ne pas se terminer par un. N’incluez pas "properties" dans le chemin d’accès (par exemple, "/personalEmail/address" au lieu de "/properties/personalEmail/properties/address").
xdm:identityNamespace
Code d'espace de nommage d'identité de la propriété source.