Principes fondamentaux des API Experience Platform

Dernière mise à jour : 2023-01-07
  • Créé pour :
  • Developer
    User
    Admin
    Leader

Les API Adobe Experience Platform utilisent plusieurs technologies et syntaxes sous-jacentes importantes à comprendre pour gérer efficacement les fichiers JSON. Platform ressources. Ce document apporte un aperçu rapide de ces technologies ainsi que des liens vers de la documentation externe pour vous apporter de plus amples informations.

JSON Pointer

JSON Pointer est une syntaxe de chaîne normalisée (RFC 6901) qui permet d’identifier des valeurs spécifiques dans des documents JSON. Un pointeur JSON est une chaîne de jetons séparés par des caractères / qui précisent soit les clés d’objet soit les index de tableau ainsi que les jetons pouvant être une chaîne ou un nombre. Les chaînes JSON Pointer sont utilisées dans de nombreuses opérations de PATCH pour Platform API, comme décrit plus loin dans ce document. Pour plus d’informations sur JSON Pointer, reportez-vous à la documentation de présentation de JSON Pointer.

Exemple d’objet de schéma JSON

Le fichier JSON suivant représente un schéma XDM simplifié dont les champs peuvent être référencés à l’aide de chaînes de pointeur JSON. Notez que tous les champs qui ont été ajoutés à l’aide de groupes de champs de schéma personnalisés (tels que loyaltyLevel) sont des espaces de noms sous un _{TENANT_ID} , tandis que les champs qui ont été ajoutés à l’aide de groupes de champs principaux (tels que fullName) ne le sont pas.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/85a4bdaa168b01bf44384e049fbd3d2e9b2ffaca440d35b9",
  "meta:altId": "_{TENANT_ID}.schemas.85a4bdaa168b01bf44384e049fbd3d2e9b2ffaca440d35b9",
  "meta:resourceType": "schemas",
  "version": "1.0",
  "title": "Example schema",
  "type": "object",
  "description": "This is an example schema.",
  "properties": {
    "_{TENANT_ID}": {
      "type": "object",
      "properties": {
        "loyaltyLevel": {
          "title": "Loyalty Level",
          "description": "",
          "type": "string",
          "isRequired": false,
          "enum": [
            "platinum",
            "gold",
            "silver",
            "bronze"
          ]
        }
      }
    },
    "person": {
      "title": "Person",
      "description": "An individual actor, contact, or owner.",
      "type": "object",
      "properties": {
        "name": {
          "title": "Full name",
          "description": "The person's full name.",
          "type": "object",
          "properties": {
            "fullName": {
              "title": "Full name",
              "type": "string",
              "description": "The full name of the person, in writing order most commonly accepted in the language of the name.",
            },
            "suffix": {
              "title": "Suffix",
              "type": "string",
              "description": "A group of letters provided after a person's name to provide additional information. The `suffix` is used at the end of someones name. For example Jr., Sr., M.D., PhD, I, II, III, etc.",
            }
          },
          "meta:referencedFrom": "https://ns.adobe.com/xdm/context/person-name",
          "meta:xdmField": "xdm:name"
        }
      }
    }
  }
}

Exemple de pointeurs JSON basés sur l’objet de schéma

JSON Pointer Est résolu sur
"/title" "Example schema"
"/properties/person/properties/name/properties/fullName" (Renvoie une référence à la propriété fullName , fourni par un groupe de champs principal.)
"/properties/_{TENANT_ID}/properties/loyaltyLevel" (Renvoie une référence à la propriété loyaltyLevel , fourni par un groupe de champs personnalisé.)
"/properties/_{TENANT_ID}/properties/loyaltyLevel/enum" ["platinum", "gold", "silver", "bronze"]
"/properties/_{TENANT_ID}/properties/loyaltyLevel/enum/0" "platinum"
REMARQUE

Lorsque vous traitez de la variable xdm:sourceProperty et xdm:destinationProperty attributs de Experience Data Model descripteurs (XDM), tout properties keys doit être excluded à partir de la chaîne JSON Pointer. Voir Schema Registry Sous-guide du développeur d’API sur descripteurs pour plus d’informations.

Correctif JSON

Il existe de nombreuses opérations de PATCH pour Platform API qui acceptent les objets de correctif JSON pour leurs payloads de requête. Le correctif JSON est un format standardisé (RFC 6902) permettant de décrire les modifications apportées à un document JSON. Il vous permet de définir des mises à jour partielles vers JSON sans avoir besoin d’envoyer le document entier dans un corps de requête.

Exemple d’un objet de correctif JSON

{
  "op": "remove",
  "path": "/foo"
}
  • op : le type d’opération de correctif. Bien que le correctif JSON prenne en charge plusieurs types d’opérations différents, toutes les opérations de PATCH ne sont pas incluses dans Platform Les API sont compatibles avec chaque type d’opération. Les types d’opérations disponibles sont :
    • add
    • remove
    • replace
    • copy
    • move
    • test
  • path : la partie de la structure JSON mise à jour, identifiée grâce à la notation JSON Pointer.

En fonction du type d’opération indiqué dans op, l’objet du correctif JSON peut nécessiter des propriétés supplémentaires. Pour plus d’informations sur les différentes opérations de correctif JSON et leur syntaxe obligatoire, reportez-vous à la documentation du correctif JSON.

Schéma JSON

Le schéma JSON est un format utilisé pour décrire et valider la structure des données JSON. Le modèle de données d’expérience (XDM) tire parti des fonctionnalités du schéma JSON pour imposer des contraintes sur la structure et le format des données d’expérience client ingérées. Pour plus d’informations sur le schéma JSON, consultez la documentation officielle.

Étapes suivantes

Ce document a présenté certaines des technologies et syntaxes impliquées dans la gestion des ressources basées sur JSON pour Experience Platform. Reportez-vous à la section guide de prise en main pour plus d’informations sur l’utilisation des API de Platform, y compris les bonnes pratiques. Pour obtenir des réponses aux questions les plus fréquemment posées, reportez-vous à la section Guide de dépannage de Platform.

Sur cette page