Annexe du guide de l’API Schema Registry

Ce document fournit des informations supplémentaires relatives à l’utilisation de la fonction Schema Registry API.

Utilisation des paramètres de requête

Le Schema Registry prend en charge l’utilisation de paramètres de requête pour la page et le filtrage des résultats lors de la liste des ressources.

REMARQUE

Lorsque vous combinez plusieurs paramètres de requête, ceux-ci doivent être séparés par des esperluettes (&).

Pagination

Les paramètres de requête les plus courants pour la pagination sont les suivants :

Paramètre Description
orderby Triez les résultats en fonction d'une propriété spécifique. Exemple : orderby=title triera les résultats par titre dans l’ordre croissant (A-Z). Ajouter un - avant la valeur du paramètre (orderby=-title) triera les éléments par titre dans l’ordre décroissant (Z-A).
limit Lorsqu’il est utilisé conjointement avec une variable orderby paramètre, limit limite le nombre maximal d’éléments à renvoyer pour une requête donnée. Ce paramètre ne peut pas être utilisé sans un orderby paramètre présent.

Le limit spécifie un entier positif (entre 0 et 500) as a hint en ce qui concerne le nombre maximal d’éléments à renvoyer. Par exemple : limit=5 renvoie uniquement cinq ressources de la liste. Cependant, cette valeur n’est pas strictement respectée. La taille réelle de la réponse peut être plus petite ou plus grande en raison de la nécessité de fournir un fonctionnement fiable de la fonction start , le cas échéant.
start Lorsqu’il est utilisé conjointement avec une variable orderby paramètre, start indique où la liste des éléments sous-définie doit commencer. Ce paramètre ne peut pas être utilisé sans un orderby paramètre présent. Cette valeur peut être obtenue à partir de la variable _page.next d’une réponse list et utilisé pour accéder à la page de résultats suivante. Si la variable _page.next est nulle, alors aucune page supplémentaire n’est disponible.

En règle générale, ce paramètre est omis afin d’obtenir la première page de résultats. Après cela, start doit être défini sur la valeur maximale de la propriété de tri Principal de la propriété orderby champ reçu dans la page précédente. La réponse de l’API renvoie ensuite les entrées commençant par celles dont la propriété de tri est Principale à partir de orderby strictement supérieur (pour l’ordre croissant) ou strictement inférieur (pour l’ordre décroissant) à la valeur spécifiée.

Par exemple, si la variable orderby est défini sur orderby=name,firstname, la variable start contient une valeur pour la variable name . Dans ce cas, si vous souhaitez afficher les 20 entrées suivantes d’une ressource immédiatement après le nom "Miller", utilisez : ?orderby=name,firstname&start=Miller&limit=20.

Filtrage

Vous pouvez filtrer les résultats en utilisant la variable property qui est utilisé pour appliquer un opérateur spécifique à une propriété JSON donnée dans les ressources récupérées. Les opérateurs pris en charge sont les suivants :

Opérateur Description Exemple
== Filtre selon si la propriété est égale à la valeur fournie. property=title==test
!= Filtre selon si la propriété n’est pas égale à la valeur fournie. property=title!=test
< Filtre selon si la propriété est inférieure à la valeur fournie. property=version<5
> Filtre selon si la propriété est supérieure ou non à la valeur fournie. property=version>5
<= Filtre selon si la propriété est inférieure ou égale à la valeur fournie. property=version<=5
>= Filtre selon si la propriété est supérieure ou égale à la valeur fournie. property=version>=5
~ Filtre selon si la propriété correspond à une expression régulière fournie. property=title~test$
(Aucun) Le fait de spécifier uniquement le nom de la propriété renvoie uniquement les entrées où la propriété existe. property=title
CONSEIL

Vous pouvez utiliser la variable property pour filtrer les groupes de champs de schéma en fonction de leur classe compatible. Par exemple : property=meta:intendedToExtend==https://ns.adobe.com/xdm/context/profile renvoie uniquement les groupes de champs compatibles avec la variable XDM Individual Profile classe .

Mode de compatibilité

Experience Data Model (XDM) est une spécification documentée publiquement, conçue par Adobe pour améliorer l’interopérabilité, l’expressivité et la puissance des expériences numériques. Adobe conserve le code source et les définitions formelles XDM dans un projet open source sur GitHub. Ces définitions sont écrites dans la notation standard XDM, et utilisent JSON-LD (JavaScript Object Notation for Linked Data) et le schéma JSON comme grammaire de définition des schémas XDM.

Lorsque vous examinez les définitions XDM formelles dans le référentiel public, vous pouvez voir que le XDM standard est différent de ce que vous voyez dans Adobe Experience Platform. Ce que vous voyez dans Experience Platform s’appelle Mode de compatibilité et fournit un mappage simple entre le XDM standard et la manière dont il est utilisé dans Platform.

Fonctionnement du mode de compatibilité

Le mode de compatibilité permet au modèle XDM JSON-LD de fonctionner avec une infrastructure de données existante en modifiant les valeurs du XDM standard tout en conservant la même sémantique. Il utilise une structure JSON imbriquée en affichant les schémas dans un format de type arbre.

La principale différence que vous noterez entre le XDM standard et le mode de compatibilité est la suppression du préfixe « xdm: » devant les noms des champs.

Le tableau ci-dessous contient une comparaison côte à côte affichant les champs associés à la date de naissance (dont les attributs « description » ont été supprimés) aux formats XDM standard et Mode de compatibilité. Notez que les champs Mode de compatibilité incluent une référence au champ XDM et à son type de données dans les attributs « meta:xdmField » et « meta:xdmType ».

XDM standard Mode de compatibilité
{ "xdm:birthDate": { "title": "Date de naissance", "type": "string", "format": "date" }, "xdm:birthDayAndMonth": { "title": "Date de naissance", "type": "string", "pattern": "[0-1][0-9]-[0-9][0-9]" }, "xdm:birthYear" : { "title": "Année de naissance", "type" : "integer", "minimum" : 1, "maximum": 32767 } }
  
{
  "birthDate": {
              "title": "Birth Date",
              "type": "string",
              "format": "date",
              "meta:xdmField": "xdm:birthDate",
              "meta:xdmType": "date"
          },
          "birthDayAndMonth": {
              "title": "Birth Date",
              "type": "string",
              "pattern": "[0-1][0-9]-[0-9][0-9]",
              "meta:xdmField": "xdm:birthDayAndMonth",
              "meta:xdmType": "string"
          },
          "birthYear": {
              "title": "Birth year",
              "type": "integer",
              "minimum": 1,
              "maximum": 32767,
              "meta:xdmField": "xdm:birthYear",
              "meta:xdmType": "short"
  }
}
      

Pourquoi le mode de compatibilité est-il nécessaire ?

Adobe Experience Platform est conçu de manière à fonctionner avec plusieurs solutions et services possédant chacun leurs propres défis et limitations techniques (par exemple, la manière dont certaines technologies traitent les caractères spéciaux). Le mode de compatibilité a été développé dans le but de surpasser ces limites.

Le plus Experience Platform services, y compris Catalog, Data Lake, et Real-time Customer Profile use Compatibility Mode au lieu de XDM standard. Le Schema Registry L’API utilise également Compatibility Mode, et les exemples de ce document sont tous affichés à l’aide de Compatibility Mode.

Il est utile de savoir qu’un mappage a lieu entre le XDM standard et la manière dont il est opérationnalisé dans Experience Platform, mais cela ne devrait pas affecter votre utilisation de Platform services.

Le projet open source est à votre disposition, mais lorsqu’il s’agit d’interagir avec des ressources via le Schema Registry, les exemples d’API de ce document fournissent les bonnes pratiques que vous devez connaître et suivre.

Sur cette page