Point d’entrée des types de données

Les types de données sont utilisés comme champs de type référence dans les classes ou les groupes de champs de schéma de la même manière que les champs littéraux de base, la principale différence étant que les types de données peuvent définir plusieurs sous-champs. Bien qu’ils soient similaires aux groupes de champs en ce qu’ils permettent l’utilisation cohérente d’une structure à champs multiples, les types de données sont plus flexibles, car ils peuvent être inclus n’importe où dans la structure du schéma, tandis que les groupes de champs ne peuvent être ajoutés qu’au niveau racine. Le point d’entrée /datatypes de l’API Schema Registry vous permet de gérer par programmation les types de données dans votre application d’expérience.

NOTE
Si un champ est défini comme un type de données spécifique, vous ne pouvez pas créer le même champ avec un type de données différent dans un autre schéma. Cette contrainte s’applique à l’ensemble du client de votre organisation.

Prise en main

Le point d’entrée utilisé dans ce guide fait partie de l’API 🔗. Schema Registry Avant de continuer, consultez le guide de prise en main pour obtenir des liens vers la documentation associée, un guide de lecture des exemples d’appels API dans ce document et des informations importantes sur les en-têtes requis pour réussir des appels vers n’importe quelle API d’Experience Platform.

Récupération d’une liste de types de données list

Vous pouvez répertorier tous les types de données sous le conteneur global ou tenant en effectuant une requête GET à /global/datatypes ou /tenant/datatypes, respectivement.

NOTE
Lors de l’énumération des ressources, le registre des schémas limite les jeux de résultats à 300 éléments. Pour renvoyer des ressources au-delà de cette limite, vous devez utiliser des paramètres de pagination. Il est également recommandé d’utiliser des paramètres de requête supplémentaires pour filtrer les résultats et réduire le nombre de ressources renvoyées. Pour plus d’informations, consultez la section sur les paramètres de requête dans le document annexe.

Format d’API

GET /{CONTAINER_ID}/datatypes?{QUERY_PARAMS}
Paramètre
Description
{CONTAINER_ID}
Conteneur à partir duquel vous souhaitez récupérer les types de données : global pour les types de données créés par Adobe ou tenant pour les types de données appartenant à votre organisation.
{QUERY_PARAMS}
Paramètres de requête facultatifs en fonction desquels filtrer les résultats. Voir le document annexe pour obtenir une liste des paramètres disponibles.

Requête

La requête suivante récupère une liste de types de données à partir du conteneur de tenant, à l’aide d’un paramètre de requête orderby pour trier les types de données en fonction de leur attribut title.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes?orderby=title \
  -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 types de données :

En-tête Accept
Description
application/vnd.adobe.xed-id+json
Renvoie un bref 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 type de données JSON complet pour chaque ressource, avec les $ref et allOf d’origine inclus. (Limite : 300)

Réponse

La requête ci-dessus a utilisé l’en-tête application/vnd.adobe.xed-id+json Accept. Par conséquent, la réponse inclut uniquement les attributs title, $id, meta:altId et version pour chaque type de données. L’utilisation de l’autre en-tête de Accept (application/vnd.adobe.xed+json) renvoie tous les attributs de chaque type de données. Sélectionnez l’en-tête de Accept approprié en fonction des informations dont vous avez besoin dans votre réponse.

{
  "results": [
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/78570e371092c032260714dd8bfd6d44",
      "meta:altId": "_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44",
      "version": "1.0",
      "title": "Loyalty"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/4b0329b5573cbb7cb757db667d7fdf66",
      "meta:altId": "_{TENANT_ID}.datatypes.4b0329b5573cbb7cb757db667d7fdf66",
      "version": "1.0",
      "title": "Property Details"
    }
  ],
  "_page": {
    "orderby": "title",
    "next": null,
    "count": 2
  },
  "_links": {
    "next": null,
    "global_schemas": {
      "href": "https://platform.adobe.io/data/foundation/schemaregistry/global/datatypes?orderby=title"
    }
  }
}

Recherche d’un type de données lookup

Vous pouvez rechercher un type de données spécifique en incluant l’identifiant du type de données dans le chemin d’accès d’une requête GET.

Format d’API

GET /{CONTAINER_ID}/datatypes/{DATA_TYPE_ID}
Paramètre
Description
{CONTAINER_ID}
Conteneur contenant le type de données à récupérer : global pour un type de données créé par Adobe ou tenant pour un type de données appartenant à votre organisation.
{DATA_TYPE_ID}
$id codée en meta:altId ou en URL du type de données que vous souhaitez rechercher.

Requête

La requête suivante récupère un type de données en fonction de sa valeur meta:altId fournie dans le chemin d’accès .

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44 \
  -H 'Accept: application/vnd.adobe.xed+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. Toutes les requêtes de recherche nécessitent qu’un version soit inclus dans l’en-tête Accept. Les en-têtes Accept suivants sont disponibles :

En-tête Accept
Description
application/vnd.adobe.xed+json; version=1
Brut avec $ref et allOf, contient des titres et des descriptions.
application/vnd.adobe.xed-full+json; version=1
$ref et allOf résolus, contient des titres et des descriptions.
application/vnd.adobe.xed-notext+json; version=1
Brut avec $ref et allOf, ne contient aucun titre ni aucune description.
application/vnd.adobe.xed-full-notext+json; version=1
$ref et allOf résolus, ne contient aucun titre ni aucune description.
application/vnd.adobe.xed-full-desc+json; version=1
$ref et allOf résolus, contient des descripteurs.

Réponse

Une réponse réussie renvoie les détails du type de données. Les champs renvoyés dépendent 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 le mieux adapté à votre cas d’utilisation.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/78570e371092c032260714dd8bfd6d44",
  "meta:altId": "_{TENANT_ID}.datatypes.78570e371092c032260714dd8bfd6d44",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Loyalty",
  "type": "object",
  "description": "Loyalty object containing loyalty-specific fields.",
  "definitions": {
    "customFields": {
      "properties": {
        "loyaltyId": {
          "title": "Loyalty ID",
          "description": "Unique loyalty program member ID. Should be in the format of an email address.",
          "type": "string",
          "meta:xdmType": "string"
        },
        "memberSince": {
          "title": "Member Since",
          "description": "Date person joined loyalty program.",
          "type": "string",
          "format": "date",
          "meta:xdmType": "date"
        },
        "points": {
          "title": "Points",
          "description": "Accumulated loyalty points",
          "type": "integer",
          "meta:xdmType": "int"
        },
        "loyaltyLevel": {
          "title": "Loyalty Level",
          "description": "The current loyalty program level to which the individual member belongs.",
          "type": "string",
          "enum": [
            "platinum",
            "gold",
            "silver",
            "bronze"
          ],
          "meta:enum": {
            "platinum": "Platinum",
            "gold": "Gold",
            "silver": "Silver",
            "bronze": "Bronze"
          },
          "meta:xdmType": "string"
        }
      },
      "type": "object",
      "meta:xdmType": "object"
    }
  },
  "allOf": [
    {
      "$ref": "#/definitions/customFields"
    }
  ],
  "imsOrg": "{ORG_ID}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1557529442681,
    "repo:lastModifiedDate": 1557529442681,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "50b8008b588e911314f9685240dd4c23a247f37179a6d9ff6ba3877dc11ca504",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Création d’un type de données create

Vous pouvez définir un type de données personnalisé sous le conteneur tenant en effectuant une requête POST.

Format d’API

POST /tenant/datatypes

Requête

Contrairement aux groupes de champs, la définition d’un type de données ne nécessite pas de champs meta:extends ou meta:intendedToExtend, pas plus que les champs ne doivent être imbriqués pour éviter les collisions.

Lorsqu’il s’agit de définir la structure du champ du type de données lui-même, vous pouvez utiliser des types primitifs (comme string ou object) ou vous pouvez référencer d’autres types de données existants par le biais d’attributs $ref. Consultez le guide sur la définition de champs XDM personnalisés dans l’API pour obtenir des conseils détaillés sur le format attendu pour les différents types de champs XDM.

La requête suivante crée un type de données d’objet « Construction de propriété » avec des sous-propriétés yearBuilt, propertyType et location :

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "title": "Property Construction",
        "description": "Information related to the property construction",
        "type": "object",
        "properties": {
          "yearBuilt": {
            "type": "integer",
            "title": "Year Built",
            "description": "The year the property was constructed."
          },
          "propertyType": {
            "type": "string",
            "title": "Property Type",
            "description": "Type of building or structure in which the property exists.",
            "enum": [
              "freeStanding",
              "mall",
              "shoppingCenter"
            ],
            "meta:enum": {
              "freeStanding": "Free Standing Building",
              "mall": "Mall Space",
              "shoppingCenter": "Shopping Center"
            }
          },
          "location": {
            "title": "Location",
            "description": "The physical location of the property.",
            "$ref": "https://ns.adobe.com/xdm/common/address"
          }
        }
      }'

Réponse

Une réponse réussie renvoie un état HTTP 201 (Created) ainsi qu’un payload contenant les détails du type de données nouvellement créé, y compris $id, meta:altId et version. Ces trois valeurs sont en lecture seule et sont attribuées par le Schema Registry.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/669ffcc61cf5e94e8640dbe6a15f0f24eb3cd1ddbbfb6b36",
  "meta:altId": "_{TENANT_ID}.datatypes.669ffcc61cf5e94e8640dbe6a15f0f24eb3cd1ddbbfb6b36",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Property Construction",
  "type": "object",
  "description": "Information related to the property construction",
  "properties": {
    "yearBuilt": {
      "type": "integer",
      "title": "Year Built",
      "description": "The year the property was constructed.",
      "meta:xdmType": "int"
    },
    "propertyType": {
      "type": "string",
      "title": "Property Type",
      "description": "Type of building or structure in which the property exists.",
      "enum": [
        "freeStanding",
        "mall",
        "shoppingCenter"
      ],
      "meta:enum": {
        "freeStanding": "Free Standing Building",
        "mall": "Mall Space",
        "shoppingCenter": "Shopping Center"
      },
      "meta:xdmType": "string"
    },
    "location": {
      "title": "Location",
      "description": "The physical location of the property.",
      "$ref": "https://ns.adobe.com/xdm/common/address",
      "type": "object",
      "meta:xdmType": "object"
    }
  },
  "refs": [
    "https://ns.adobe.com/xdm/common/address"
  ],
  "imsOrg": "{ORG_ID}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1670885230789,
    "repo:lastModifiedDate": 1670885230789,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "d3cc803a1f8daa06b7c150d882bd337d88f4d5d5f08d36cfc4c2849dc0255f7e",
    "meta:globalLibVersion": "1.38.3.1"
  },
  "meta:containerId": "tenant",
  "meta:sandboxId": "1bd86660-c5da-11e9-93d4-6d5fc3a66a8e",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

L’exécution d’une requête GET pour répertorier tous les types de données dans le conteneur du client inclut désormais le type de données Détails de la propriété , ou vous pouvez effectuer une requête de recherche (GET) à l’aide de l’URI $id codé par URL pour afficher directement le nouveau type de données.

Mettre à jour un type de données put

Vous pouvez remplacer un type de données entier par le biais d’une opération PUT, ce qui revient essentiellement à réécrire la ressource. Lors de la mise à jour d’un type de données par le biais d’une requête PUT, le corps doit inclure tous les champs requis lors de la création d’un nouveau type de données dans une requête POST.

NOTE
Si vous souhaitez uniquement mettre à jour une partie d’un type de données au lieu de le remplacer entièrement, consultez la section sur la mise à jour d’une partie d’un type de données.

Format d’API

PUT /tenant/datatypes/{DATA_TYPE_ID}
Paramètre
Description
{DATA_TYPE_ID}
$id codée en meta:altId ou en URL du type de données que vous souhaitez réécrire.

Requête

La requête suivante réécrit un type de données existant, en ajoutant un nouveau champ de floorSize.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "title": "Property Construction",
        "description": "Information related to the property construction",
        "type": "object",
        "properties": {
          "yearBuilt": {
            "type": "integer",
            "title": "Year Built",
            "description": "The year the property was constructed."
          },
          "propertyType": {
            "type": "string",
            "title": "Property Type",
            "description": "Type of building or structure in which the property exists.",
            "enum": [
              "freeStanding",
              "mall",
              "shoppingCenter"
            ],
            "meta:enum": {
              "freeStanding": "Free Standing Building",
              "mall": "Mall Space",
              "shoppingCenter": "Shopping Center"
            }
          },
          "floorSize" {
            "type": "integer",
            "title": "Floor Size",
            "description": "The floor size of the property, in square feet."
          }
        }
      }'

Réponse

Une réponse réussie renvoie les détails du type de données mis à jour.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:altId": "_{TENANT_ID}.datatypes.7602bc6e97e5786a31c95d9e6531a1596687433451d97bc1",
  "meta:resourceType": "datatypes",
  "version": "1.0",
  "title": "Property Construction",
  "type": "object",
  "description": "Information related to the property construction",
  "properties": {
    "yearBuilt": {
      "type": "integer",
      "title": "Year Built",
      "description": "The year the property was constructed.",
      "meta:xdmType": "int"
    },
    "propertyType": {
      "type": "string",
      "title": "Property Type",
      "description": "Type of building or structure in which the property exists.",
      "enum": [
        "freeStanding",
        "mall",
        "shoppingCenter"
      ],
      "meta:enum": {
        "freeStanding": "Free Standing Building",
        "mall": "Mall Space",
        "shoppingCenter": "Shopping Center"
      },
      "meta:xdmType": "string"
    },
    "floorSize" {
      "type":  "integer",
      "title":  "Floor Size",
      "description":  "The floor size of the property, in square feet.",
      "meta:xdmType": "int"
    }
  },
  "refs": [],
  "imsOrg": "{ORG_ID}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1604524729435,
    "repo:lastModifiedDate": 1604524729435,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "1c838764342756868ca1297869f582a38d15f03ed0acfc97fda7532d22e942c7",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Mettre à jour une partie d’un type de données patch

Vous pouvez mettre à jour une partie d’un type de données à l’aide d’une requête PATCH. Le Schema Registry prend en charge toutes les opérations standard JSON Patch, notamment add, remove et replace. Pour plus d’informations sur le correctif JSON, voir Guide de base des API.

NOTE
Si vous souhaitez remplacer une ressource entière par de nouvelles valeurs au lieu de mettre à jour des champs individuels, consultez la section sur le remplacement d’un type de données à l’aide d’une opération PUT.

Format d’API

PATCH /tenant/data type/{DATA_TYPE_ID}
Paramètre
Description
{DATA_TYPE_ID}
L’URI $id encodé URL ou le meta:altId du type de données que vous souhaitez mettre à jour.

Requête

L’exemple de requête ci-dessous met à jour la description d’un type de données existant et ajoute un nouveau champ de floorSize.

Le corps de la requête se présente sous la forme d’un tableau, où chaque objet répertorié représente une modification spécifique apportée à un champ individuel. Chaque objet inclut l’opération à effectuer (op), le champ sur lequel l’opération doit être effectuée (path) et les informations à inclure dans cette opération (value).

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.8779fd45d6e4eb074300023a439862bbba359b60d451627a \
  -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 'content-type: application/json' \
  -d '[
        {
          "op": "replace",
          "path": "/description",
          "value": "Construction-related information for a company-operated property."
        },
        {
          "op": "add",
          "path": "/properties/floorSize",
          "value": {
            "type": "integer",
            "title": "Floor Size",
            "description": "The floor size of the property, in square feet."
          }
        }
      ]'

Réponse

La réponse montre que les deux opérations ont été réalisées avec succès. Le description a été mis à jour et floorSize a été ajouté sous definitions.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/datatypes/8779fd45d6e4eb074300023a439862bbba359b60d451627a",
  "meta:altId": "_{TENANT_ID}.datatypes.8779fd45d6e4eb074300023a439862bbba359b60d451627a",
  "meta:resourceType": "datatypes",
  "version": "1.2",
  "title": "Property Details",
  "type": "object",
  "description": "Details relating to a property operated by the company.",
  "definitions": {
    "property": {
      "properties": {
        "_{TENANT_ID}": {
        "type": "object",
        "properties": {
            "propertyName": {
              "type": "string",
              "title": "Property Name",
              "description": "Name of the property"
            },
            "propertyCity": {
              "title": "Property City",
              "description": "City where the property is located.",
              "type": "string"
            },
            "propertyCountry": {
              "title": "Property Country",
              "description": "Country where the property is located.",
              "type": "string"
            },
            "phoneNumber": {
              "title": "Phone Number",
              "description": "Primary phone number for the property.",
              "type": "string"
            },
            "propertyType": {
              "type": "string",
              "title": "Property Type",
              "description": "Type and primary use of property.",
              "enum": [
                  "retail",
                  "yoga",
                  "fitness"
              ],
              "meta:enum": {
                  "retail": "Retail Store",
                  "yoga": "Yoga Studio",
                  "fitness": "Fitness Center"
              }
            },
            "propertyConstruction": {
              "$ref": "https://ns.adobe.com/{TENANT_ID}/datatypes/24c643f618647344606222c494bd0102"
            }
          }
        }
      }
    }
  },
  "allOf": [
    {
      "$ref": "#/definitions/customFields",
      "type": "object",
      "meta:xdmType": "object"
    }
  ],
  "imsOrg": "{ORG_ID}",
  "meta:extensible": true,
  "meta:abstract": true,
  "meta:intendedToExtend": [
    "https://ns.adobe.com/xdm/context/profile"
  ],
  "meta:xdmType": "object",
  "meta:registryMetadata": {
    "repo:createdDate": 1594941263588,
    "repo:lastModifiedDate": 1594941538433,
    "xdm:createdClientId": "{CLIENT_ID}",
    "xdm:lastModifiedClientId": "{CLIENT_ID}",
    "xdm:createdUserId": "{USER_ID}",
    "xdm:lastModifiedUserId": "{USER_ID}",
    "eTag": "5e8a5e508eb2ed344c08cb23ed27cfb60c841bec59a2f7513deda0f7af903021",
    "meta:globalLibVersion": "1.15.4"
  },
  "meta:containerId": "tenant",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Suppression d’un type de données delete

Il peut parfois être nécessaire de supprimer un type de données du registre des schémas. Pour ce faire, il suffit d’effectuer une requête DELETE avec l’identifiant de type de données fourni dans le chemin d’accès .

Format d’API

DELETE /tenant/datatypes/{DATA_TYPE_ID}
Paramètre
Description
{DATA_TYPE_ID}
L’URI $id encodé URL ou le meta:altId du type de données à supprimer.

Requête

curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/datatypes/_{TENANT_ID}.datatypes.d5cc04eb8d50190001287e4c869ebe67 \
  -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}'

Réponse

Une réponse réussie renvoie un statut HTTP 204 (Pas de contenu) et un corps vide.

Vous pouvez confirmer la suppression en tentant d’adresser une ​ requête de recherche (GET) au type de données . Vous devez inclure un en-tête Accept dans la requête, mais vous devriez recevoir le statut HTTP 404 (Not Found), car le type de données a été supprimé du registre des schémas.

recommendation-more-help
experience-platform-help-xdm