Point de terminaison des 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.

Le point de terminaison /descriptors de l'API Schema Registry vous permet de gérer par programmation les descripteurs dans votre application d'expérience.

Prise en main

Le point de terminaison utilisé dans ce guide fait partie de l'Schema Registry API. Avant de continuer, consultez le guide de prise en main pour obtenir des liens vers la documentation connexe, un guide de lecture des exemples d'appels d'API dans ce document et des informations importantes concernant les en-têtes requis nécessaires pour passer des appels à toute API Experience Platform.

Récupérer une liste de descripteurs

Vous pouvez liste tous les descripteurs définis par votre organisation en adressant une demande de GET à /tenant/descriptors.

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 Accept envoyé dans la demande. Notez que le point de terminaison /descriptors utilise des en-têtes différents de tous les autres points de terminaison dans l’API .AcceptSchema Registry

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 link Accept, 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}

Requête

La requête suivante récupère un descripteur par sa valeur @id. Les descripteurs ne sont pas versionnés. Par conséquent, aucun en-tête Accept 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 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éer un descripteur

Vous pouvez créer un nouveau descripteur en adressant une requête de POST au point de terminaison /tenant/descriptors.

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. Experience Platform est ainsi invité à 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 un état HTTP 201 (Created) et les détails du nouveau descripteur, y compris son identifiant @id. @id est un champ en lecture seule attribué par Schema Registry 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 un descripteur

Vous pouvez mettre à jour un descripteur en incluant @id dans le chemin d’une requête de PUT.

Format d’API

PUT /tenant/descriptors/{DESCRIPTOR_ID}

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, 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.

L'exemple suivant met à jour un descripteur d'identité pour référencer un xdm:sourceProperty différent (mobile phone) et remplacer xdm:namespace par 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
      }'

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"
}

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

Supprimer un descripteur

Il peut arriver que vous deviez supprimer un descripteur que vous avez défini dans le 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}

Requête

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 (Pas de contenu) et un corps vide.

Pour confirmer que le descripteur a été supprimé, vous pouvez exécuter une requête de recherche 🔗 par rapport au descripteur @id. La réponse renvoie l'état HTTP 404 (Introuvable) car le descripteur a été supprimé de Schema Registry.

Annexe

La section suivante fournit des informations supplémentaires sur l'utilisation des descripteurs dans l'API Schema Registry.

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é

Un descripteur d'identité signale que le champ "sourceProperty" de "sourceSchema" est un champ Identity comme décrit par Service d'identité de Adobe Experience Platform.

{
  "@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
}

Descripteur de nom convivial

Les descripteurs de nom conviviaux permettent à un utilisateur de modifier les valeurs title, description et meta:enum des champs du schéma de bibliothèque principal. 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"
  }
}

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"
}

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"
}