Prise en main de l’API Schema Registry

L’API Schema Registry vous permet de créer et de gérer diverses ressources du modèle de données d’expérience (XDM). Ce document présente les concepts de base que vous devez connaître avant d’effectuer des appels à l’API Schema Registry.

Conditions préalables

L’utilisation du guide de développement nécessite une compréhension pratique des composants suivants de Adobe Experience Platform :

XDM utilise le formatage du schéma JSON pour décrire et valider la structure des données d’expérience client ingérées. Il est donc vivement recommandé de consulter la documentation officielle du schéma JSON pour mieux comprendre cette technologie sous-jacente.

Lecture d’exemples d’appels API

La documentation de l’API Schema Registry inclut des exemples d’appels d’API expliquant comment formater vos requêtes. Il s’agit notamment de chemins d’accès, d’en-têtes requis et de payloads de requêtes correctement formatés. L’exemple JSON renvoyé dans les réponses de l’API est également fourni. Pour plus d’informations sur les conventions utilisées dans la documentation pour les exemples d’appels API, consultez la section sur la lecture d’exemples d’appels API dans le guide de dépannage d’Experience Platform.

Collecte des valeurs des en-têtes requis

Pour lancer des appels aux API Platform, vous devez d’abord suivre le tutoriel d’authentification. Le tutoriel d’authentification fournit les valeurs de chacun des en-têtes requis dans tous les appels d’API Experience Platform, comme indiqué ci-dessous :

Toutes les ressources de Experience Platform, y compris celles appartenant à Schema Registry, sont isolées dans des environnements de test virtuels spécifiques. Toutes les requêtes envoyées aux API Platform nécessitent un en-tête spécifiant le nom du sandbox dans lequel l’opération sera effectuée :

Toutes les requêtes de recherche (GET) envoyées à Schema Registry nécessitent un en-tête Accept supplémentaire, dont la valeur détermine le format des informations renvoyées par l’API. Voir la section En-tête Accept ci-dessous pour plus d’informations.

Toutes les requêtes contenant un payload (POST, PUT, PATCH) requièrent un en-tête supplémentaire :

Connaître votre TENANT_ID know-your-tenant_id

Dans les guides d’API, vous trouverez des références à un TENANT_ID. Cet identifiant permet de s’assurer que les espaces de noms des ressources que vous créez sont corrects et contenus dans votre organisation. Si vous ne connaissez pas votre identifiant, vous pouvez y accéder en réalisant la requête GET suivante :

Format d’API

GET /stats

Requête

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/stats \
  -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 des informations concernant l’utilisation de Schema Registry par votre organisation. Cela inclut un attribut tenantId, dont la valeur est votre TENANT_ID.

{
  "imsOrg":"{ORG_ID}",
  "tenantId":"{TENANT_ID}",
  "counts": {
    "schemas": 4,
    "mixins": 3,
    "datatypes": 1,
    "classes": 2,
    "unions": 0,
  },
  "recentlyCreatedResources": [
    {
      "title": "Sample Field Group",
      "description": "New Sample Field Group.",
      "meta:resourceType": "mixins",
      "meta:created": "Sat Feb 02 2019 00:24:30 GMT+0000 (UTC)",
      "version": "1.1"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/classes/5bdb5582be0c0f3ebfc1c603b705764f",
      "title": "Tenant Class",
      "description": "Tenant Defined Class",
      "meta:resourceType": "classes",
      "meta:created": "Fri Feb 01 2019 22:46:21 GMT+0000 (UTC)",
      "version": "1.0"
    }
  ],
  "recentlyUpdatedResources": [
    {
      "title": "Sample Field Group",
      "description": "New Sample Field Group.",
      "meta:resourceType": "mixins",
      "meta:updated": "Sat Feb 02 2019 00:34:06 GMT+0000 (UTC)",
      "version": "1.1"
    },
    {
      "title": "Data Schema",
      "description": "Schema for Data Information",
      "meta:resourceType": "schemas",
      "meta:updated": "Fri Feb 01 2019 23:47:43 GMT+0000 (UTC)",
      "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab",
      "meta:classTitle": "Sample Class",
      "version": "1.1"
    }
 ],
 "classUsage": {
    "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab": [
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
        "title": "Tenant Data Schema",
        "description": "Schema for tenant-specific data."
      }
    ],
    "https://ns.adobe.com/xdm/context/profile": [
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/3ac6499f0a43618bba6b138226ae3542",
        "title": "Simple Profile",
        "description": "A simple profile schema."
      },
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "title": "Program Schema",
        "description": "Schema for program-related data."
      },
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/4025a705890c6d4a4a06b16f8cf6f4ca",
        "title": "Sample Schema",
        "description": "A sample schema."
      }
    ]
  }
 }

Comprendre le CONTAINER_ID container

Les appels à l’API Schema Registry nécessitent l’utilisation d’un CONTAINER_ID. Il existe deux conteneurs sur lesquels vous pouvez effectuer des appels API : le conteneur global et le conteneur tenant.

Conteneur mondial

Le conteneur global contient toutes les classes d’Adobe standard et Experience Platform fournies par les partenaires, les groupes de champs de schéma, les types de données et les schémas. Vous pouvez uniquement effectuer des requêtes de liste et de recherche (GET) sur le conteneur global.

Voici un exemple d’appel qui utilise le conteneur global :

GET /global/classes

Conteneur client

À ne pas confondre avec votre TENANT_ID unique, le conteneur tenant contient toutes les classes, tous les groupes de champs, tous les types de données, tous les schémas et tous les descripteurs définis par une organisation. Elles sont propres à chaque organisation, ce qui signifie qu’elles ne sont pas visibles ou gérables par d’autres organisations. Vous pouvez effectuer toutes les opérations CRUD (GET, POST, PUT, PATCH, DELETE) sur les ressources que vous créez dans le conteneur tenant.

Voici un exemple d’appel qui utilise le conteneur tenant :

POST /tenant/fieldgroups

Lorsque vous créez une classe, un groupe de champs, un schéma ou un type de données dans le conteneur tenant, il est enregistré dans le conteneur Schema Registry et se voit attribuer un URI $id qui inclut votre TENANT_ID. Cet $id est utilisé sur l’ensemble de l’API pour faire référence à des ressources spécifiques. Des exemples de valeurs $id sont fournis à la section suivante.

Identification des ressources resource-identification

Les ressources XDM sont identifiées avec un attribut $id sous la forme d’un URI, comme les exemples suivants :

Pour rendre l’URI plus REST-friendly, les schémas possèdent également un encodage de notation à point de l’URI dans une propriété intitulée meta:altId :

Les appels à l’API Schema Registry prennent en charge l’URI $id encodé par l’URL ou le meta:altId (format de notation par points). La bonne pratique est d’utiliser l’URI $id encodé par l’URL lorsque vous passez un appel REST à l’API, comme :

En-tête Accept accept

Lors des opérations de liste et de recherche (GET) dans l’API Schema Registry, un en-tête Accept est nécessaire pour déterminer le format des données renvoyées par l’API. Lors de la recherche de ressources spécifiques, un numéro de version doit également être inclus dans l’en-tête Accept.

Le tableau suivant répertorie les valeurs d’en-tête Accept compatibles, y compris celles avec des numéros de version, ainsi que des descriptions de ce que l’API renverra lorsqu’elles sont utilisées.

Contrôle de version des schémas versioning

Les versions des schémas sont référencées par les en-têtes Accept de l’API Schema Registry et dans les propriétés schemaRef.contentType des payloads de l’API du service Platform en aval.

Actuellement, Platform ne prend en charge qu’une seule version majeure (1) pour chaque schéma. Selon les règles d’évolution du schéma, chaque mise à jour d’un schéma doit être non destructive, ce qui signifie que de nouvelles versions mineures d’un schéma (1.2, 1.3, etc.) sont toujours rétrocompatibles avec les versions mineures précédentes. Par conséquent, lors de la spécification de version=1, le registre des schémas renvoie toujours la dernière version majeure 1 d’un schéma, ce qui signifie que les versions mineures précédentes ne sont pas renvoyées.

Contraintes de champ XDM et bonnes pratiques

Les champs d’un schéma sont répertoriés dans son objet properties. Chaque champ est lui-même un objet, contenant des attributs pour décrire et contraindre les données que le champ peut contenir. Reportez-vous au guide sur la définition de champs personnalisés dans l’API pour obtenir des exemples de code et des contraintes facultatives pour les types de données les plus couramment utilisés.

Le champ d’exemple suivant illustre un champ XDM formaté correctement avec de plus amples détails sur les contraintes de dénomination et les bonnes pratiques fournies ci-dessous. Ces pratiques peuvent également s’appliquer lorsque vous définissez les autres ressources pouvant contenir des attributs similaires.

"fieldName": {
    "title": "Field Name",
    "type": "string",
    "format": "date-time",
    "examples": [
        "2004-10-23T12:00:00-06:00"
    ],
    "description": "Full sentence describing the field, using proper grammar and punctuation.",
}

Étapes suivantes

Pour commencer à effectuer des appels à l’aide de l’API Schema Registry, sélectionnez l’un des guides de point d’entrée disponibles.