Show Menu
SUJETS×

Création d’un schéma ad hoc

In specific circumstances, it may be necessary to create an Experience Data Model (XDM) schema with fields that are namespaced for usage only by a single dataset. On parle alors de schéma « ad hoc ». Ad-hoc schemas are used in various data ingestion workflows for Experience Platform, including ingesting CSV files and creating certain kinds of source connections.
Ce document décrit les étapes générales de création d’un schéma ad hoc à l’aide de l’ API Schema Registry . It is intended to be used in conjunction with other Experience Platform tutorials that require creating an ad-hoc schema as part of their workflow. Chacun de ces documents fournit des informations détaillées sur la manière de configurer correctement un schéma ad hoc pour son cas d’utilisation spécifique.

Prise en main

This tutorial requires a working understanding of Experience Data Model (XDM) System. Avant de commencer ce tutoriel, consultez la documentation XDM suivante :
Avant de commencer ce tutoriel, veuillez consulter le guide de développement pour trouver les informations importantes à connaître afin d’effectuer avec succès des appels vers l’API Schema Registry Cela inclut votre {TENANT_ID} , le concept de « conteneurs » et les en-têtes requis pour effectuer des requêtes (avec une attention particulière à l’en-tête Accept et à ses valeurs possibles).

Création d’une classe ad hoc

Le comportement des données d’un schéma XDM est déterminé par sa classe sous-jacente. La première étape de la création d’un schéma ad hoc consiste à créer une classe basée sur le comportement adhoc . Pour ce faire, vous devez envoyer une requête POST au point de terminaison /tenant/classes .
Format d’API
POST /tenant/classes

Requête
La requête suivante crée une nouvelle classe XDM configurée par les attributs fournis dans le payload. En fournissant une propriété $ref définie sur https://ns.adobe.com/xdm/data/adhoc dans le tableau allOf , cette classe hérite du comportement adhoc . La requête définit également un objet _adhoc , qui contient les champs personnalisés de la classe.
Les champs personnalisés définis sous _adhoc varient selon le cas d’utilisation du schéma ad hoc. Reportez-vous au workflow spécifique du tutoriel approprié pour les champs personnalisés requis en fonction du cas d’utilisation.
curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/classes \
  -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 '{
        "title":"New ad-hoc class",
        "description": "New ad-hoc class description",
        "type":"object",
        "allOf": [
          {
            "$ref":"https://ns.adobe.com/xdm/data/adhoc"
          },
          {
            "properties": {
              "_adhoc": {
                "type":"object",
                "properties": {
                  "field1": {
                    "type":"string"
                  },
                  "field2": {
                    "type":"string"
                  }
                }
              }
            }
          }
        ]
      }'

Propriété
Description
$ref
Comportement des données pour la nouvelle classe. Pour les classes ad hoc, cette valeur doit être définie sur https://ns.adobe.com/xdm/data/adhoc .
properties._adhoc
Objet contenant les champs personnalisés de la classe, exprimés en paires clé-valeur des noms de champ et des types de données.
Réponse
Une réponse réussie renvoie les détails de la nouvelle classe, en remplaçant le nom de l’objet properties._adhoc par un GUID, qui est un identifiant unique généré par le système et en lecture seule pour la classe. L’attribut meta:datasetNamespace est également généré automatiquement et inclus dans la réponse.
{
    "$id": "https://ns.adobe.com/{TENANT_ID}/classes/6395cbd58812a6d64c4e5344f7b9120f",
    "meta:altId": "_{TENANT_ID}.classes.6395cbd58812a6d64c4e5344f7b9120f",
    "meta:resourceType": "classes",
    "version": "1.0",
    "title": "New Class",
    "description": "New class description",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/data/adhoc"
        },
        {
            "properties": {
                "_6395cbd58812a6d64c4e5344f7b9120f": {
                    "type": "object",
                    "properties": {
                        "field1": {
                            "type": "string",
                            "meta:xdmType": "string"
                        },
                        "field2": {
                            "type": "string",
                            "meta:xdmType": "string"
                        }
                    },
                    "meta:xdmType": "object"
                }
            },
            "type": "object",
            "meta:xdmType": "object"
        }
    ],
    "meta:abstract": true,
    "meta:extensible": true,
    "meta:extends": [
        "https://ns.adobe.com/xdm/data/adhoc"
    ],
    "meta:containerId": "tenant",
    "meta:datasetNamespace": "_6395cbd58812a6d64c4e5344f7b9120f",
    "imsOrg": "{IMS_ORG}",
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createdDate": 1557527784822,
        "repo:lastModifiedDate": 1557527784822,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:lastModifiedClientId": "{MODIFIED_CLIENT}",
        "eTag": "Jggrlh4PQdZUvDUhQHXKx38iTQo="
    }
}

Propriété
Description
$id
URI qui sert d’identifiant unique généré par le système et en lecture seule pour la nouvelle classe ad hoc. Cette valeur est utilisée à l’étape suivante de la création d’un schéma ad hoc.

Création d’un schéma ad hoc

Une fois que vous avez créé une classe ad hoc, vous pouvez créer un nouveau schéma qui implémente celle-ci en envoyant une requête POST au point de terminaison /tenant/schemas .
Format d’API
POST /tenant/schemas

Requête
La requête suivante crée un nouveau schéma, fournissant une référence ( $ref ) à la propriété $id de la classe ad hoc créée précédemment dans son payload.
curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
  -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 '{
        "title":"New Schema",
        "description": "New schema description.",
        "type":"object",
        "allOf": [
          {
            "$ref":"https://ns.adobe.com/{TENANT_ID}/classes/6395cbd58812a6d64c4e5344f7b9120f"
          }
        ]
      }'

Réponse
Une réponse réussie renvoie les détails du schéma créé, y compris sa propriété $id générée par le système et en lecture seule.
{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/26f6833e55db1dd8308aa07a64f2042d",
    "meta:altId": "_{TENANT_ID}.schemas.26f6833e55db1dd8308aa07a64f2042d",
    "meta:resourceType": "schemas",
    "version": "1.0",
    "title": "New Schema",
    "description": "New schema description.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/6395cbd58812a6d64c4e5344f7b9120f"
        }
    ],
    "meta:datasetNamespace": "_6395cbd58812a6d64c4e5344f7b9120f",
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/6395cbd58812a6d64c4e5344f7b9120f",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/6395cbd58812a6d64c4e5344f7b9120f",
        "https://ns.adobe.com/xdm/data/adhoc"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:xdmType": "object",
    "meta:registryMetadata": {
        "repo:createdDate": 1557528570542,
        "repo:lastModifiedDate": 1557528570542,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:lastModifiedClientId": "{MODIFIED_CLIENT}",
        "eTag": "Jggrlh4PQdZUvDUhQHXKx38iTQo="
    }
}

Affichage du schéma ad hoc complet

Cette étape est facultative. Si vous ne souhaitez pas examiner la structure des champs de votre schéma ad hoc, vous pouvez passer aux étapes suivantes de la section, à la fin de ce tutoriel.
Une fois le schéma ad hoc créé, vous pouvez effectuer une requête de recherche (GET) pour afficher la forme développée du schéma. Pour ce faire, utilisez l’en-tête Accept approprié dans la requête GET, comme illustré ci-dessous.
Format d’API
GET /tenant/schemas/{SCHEMA_ID}

Paramètre
Description
{SCHEMA_ID}
URI $id encodé URL ou meta:altId du schéma ad hoc auquel vous souhaitez accéder.
Requête
La requête suivante utilise l’en-tête Accept application/vnd.adobe.xed-full+json; version=1 , qui renvoie la forme développée du schéma. Note that when retrieving a specific resource from the Schema Registry, the request's Accept header must include major version of the resource in question.
curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.26f6833e55db1dd8308aa07a64f2042d \
  -H 'Accept: application/vnd.adobe.xed-full+json; version=1' \
  -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 schéma, y compris tous les champs imbriqués sous properties .
{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/26f6833e55db1dd8308aa07a64f2042d",
    "meta:altId": "_{TENANT_ID}.schemas.26f6833e55db1dd8308aa07a64f2042d",
    "meta:resourceType": "schemas",
    "version": "1.0",
    "title": "New Schema",
    "description": "New schema description.",
    "type": "object",
    "meta:datasetNamespace": "_6395cbd58812a6d64c4e5344f7b9120f",
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/6395cbd58812a6d64c4e5344f7b9120f",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/6395cbd58812a6d64c4e5344f7b9120f",
        "https://ns.adobe.com/xdm/data/adhoc"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:xdmType": "object",
    "properties": {
        "_6395cbd58812a6d64c4e5344f7b9120f": {
            "type": "object",
            "meta:xdmType": "object",
            "properties": {
                "field1": {
                    "type": "string",
                    "meta:xdmType": "string"
                },
                "field2": {
                    "type": "string",
                    "meta:xdmType": "string"
                }
            }
        }
    },
    "meta:registryMetadata": {
        "repo:createdDate": 1557528570542,
        "repo:lastModifiedDate": 1557528570542,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:lastModifiedClientId": "{MODIFIED_CLIENT}",
        "eTag": "bTogM1ON2LO/F7rlcc1iOWmNVy0="
    }
}

Étapes suivantes

En suivant ce tutoriel, vous avez créé un schéma ad hoc. Si un autre tutoriel vous a renvoyé à ce document, vous pouvez désormais utiliser la propriété $id de votre schéma ad hoc pour terminer le workflow comme indiqué.
For more information on working with the Schema Registry API, please refer to the developer guide .