DocumentazioneExperience PlatformGuida di Experience Data Model (XDM)

Aggiungere campi specifici a uno schema utilizzando l’API Schema Registry

Ultimo aggiornamento: 4 aprile 2025
  • Argomenti:

Creato per:

  • Sviluppatore

Gli schemi Experience Data Model (XDM) sono composti da una classe base, con campi aggiuntivi inclusi tramite l’utilizzo di gruppi di campi standard definiti da Adobe e di gruppi di campi personalizzati definiti dalla tua organizzazione.

Durante la creazione di uno schema, è possibile utilizzare alcuni campi di un determinato gruppo di campi escludendo altri dallo stesso gruppo che non sono necessari. Questa esercitazione mostra come aggiungere singoli campi da un gruppo di campi a uno schema utilizzando l’API Schema Registry.

NOTE
Per informazioni su come aggiungere e rimuovere singoli campi dello schema nell'interfaccia utente di Adobe Experience Platform, consulta la guida sui flussi di lavoro basati sui campi (attualmente in versione beta).

Prerequisiti

Questo tutorial prevede l'esecuzione di chiamate all'API Schema Registry. Prima di iniziare, consulta la guida per gli sviluppatori per informazioni importanti che devi conoscere per effettuare correttamente chiamate all'API, tra cui {TENANT_ID}, il concetto di contenitori e le intestazioni necessarie per effettuare le richieste.

Informazioni sul campo meta:refProperty

Per uno schema specifico, la classe e i gruppi di campi che ne costituiscono la struttura fanno riferimento al suo array allOf. Ogni componente è rappresentato come un oggetto contenente una proprietà $ref che fa riferimento all'URI del componente $id.

Il seguente JSON rappresenta uno schema semplificato che utilizza una singola classe (experienceevent) e un gruppo di campi (experienceevent-all):

{
  "title": "My Sample Schema",
  "description": "My Sample Description",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all"
    }
  ]
}

Per qualsiasi oggetto nell'array allOf che fa riferimento a un gruppo di campi, è possibile aggiungere un campo di pari livello meta:refProperty per specificare quali campi del gruppo devono essere inclusi nello schema.

NOTE
Ogni campo viene specificato utilizzando una stringa puntatore JSON che rappresenta il percorso del campo all’interno del rispettivo gruppo di campi. La stringa deve iniziare con una barra iniziale (/) e non deve includere spazi dei nomi properties. Esempio: /_experience/campaign/message/id.

Se incluso come stringa, meta:refProperty può fare riferimento a un singolo campo in un gruppo. È possibile includere altri campi dello stesso gruppo utilizzando lo stesso valore $ref in un altro oggetto con un valore meta:refProperty diverso.

{
  "title": "My Sample Schema",
  "description": "An example schema that uses the XDM ExperienceEvent class.",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
      "meta:refProperty": "/_experience/campaign/message/id"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
      "meta:refProperty": "/_experience/campaign/message/size"
    }
  ]
}

In alternativa, è possibile fornire meta:refProperty come array, consentendo di specificare più campi da includere da un determinato gruppo all'interno di una singola voce di elenco allOf:

{
  "title": "My Sample Schema",
  "description": "An example schema that uses the XDM ExperienceEvent class.",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
      "meta:refProperty": [
        "/_experience/campaign/message/id",
        "/_experience/campaign/message/size",
        "/_experience/campaign/message/variant"
      ]
    }
  ]
}

Aggiungere campi con un’operazione PUT

È possibile utilizzare una richiesta PUT per riscrivere un intero schema e configurare i campi da includere in allOf.

Formato API

PUT /tenant/schemas/{SCHEMA_ID}
Parametro
Descrizione
{SCHEMA_ID}
meta:altId o $id con codifica URL dello schema che si desidera riscrivere.

Richiesta

La richiesta seguente aggiorna i campi specifici inclusi dal gruppo di campi nell'array allOf.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.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}' \
  -H 'Content-Type: application/json' \
  -d '{
        "title": "My Sample Schema",
        "description": "My Sample Description",
        "type": "object",
        "allOf": [
          {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
          },
          {
            "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
            "meta:refProperty": [
              "/_experience/campaign/message/id",
              "/_experience/campaign/message/size",
              "/_experience/campaign/message/variant"
            ]
          }
        ]
      }'

Risposta

In caso di esito positivo, la risposta restituisce i dettagli dello schema aggiornato.

{
  "title": "My Sample Schema",
  "description": "My Sample Description",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
      "meta:refProperty": [
        "/_experience/campaign/message/id",
        "/_experience/campaign/message/size",
        "/_experience/campaign/message/variant"
      ]
    }
  ],
  "meta:class": "https://ns.adobe.com/xdm/context/experienceevent",
  "meta:abstract": false,
  "meta:extensible": false,
  "meta:extends": [
      "https://ns.adobe.com/xdm/context/experienceevent",
      "https://ns.adobe.com/xdm/data/time-series"
  ],
  "meta:containerId": "tenant",
  "imsOrg": "{ORG_ID}",
  "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
  "meta:xdmType": "object",
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
  "version": "1.0",
  "meta:resourceType": "schemas",
  "meta:registryMetadata": {
      "repo:createDate": 1552088461236,
      "repo:lastModifiedDate": 1552088470592,
      "xdm:createdClientId": "{CREATED_CLIENT}",
      "xdm:repositoryCreatedBy": "{CREATED_BY}"
  }
}
NOTE
Per informazioni più dettagliate sulle richieste di PUT per gli schemi, consulta la guida dell'endpoint degli schemi.

Aggiungere campi con un’operazione PATCH

È possibile utilizzare una richiesta PATCH per aggiungere singoli campi a uno schema senza sovrascriverne altri. Il registro dello schema supporta tutte le operazioni Patch JSON standard, inclusi add, remove e replace. Per ulteriori informazioni sulla patch JSON, consulta la guida delle API fondamentali.

Formato API

PATCH /tenant/schemas/{SCHEMA_ID}
Parametro
Descrizione
{SCHEMA_ID}
meta:altId o $id con codifica URL dello schema che si desidera riscrivere.

Richiesta

La richiesta seguente aggiunge un nuovo oggetto all'array allOf dello schema, specificando i campi da aggiungere.

curl -X PATCH \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.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}' \
  -H 'Content-Type: application/json' \
  -d '[
        {
          "op": "add",
          "path": "/allOf/-",
          "value":  {
            "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
            "meta:refProperty": [
              "/_experience/campaign/message/id",
              "/_experience/campaign/message/size",
              "/_experience/campaign/message/variant"
            ]
          }
        }
      ]'

Risposta

In caso di esito positivo, la risposta restituisce i dettagli dello schema aggiornato.

{
  "title": "My Sample Schema",
  "description": "My Sample Description",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
    },
    {
      "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-all",
      "meta:refProperty": [
        "/_experience/campaign/message/id",
        "/_experience/campaign/message/size",
        "/_experience/campaign/message/variant"
      ]
    }
  ],
  "meta:class": "https://ns.adobe.com/xdm/context/experienceevent",
  "meta:abstract": false,
  "meta:extensible": false,
  "meta:extends": [
      "https://ns.adobe.com/xdm/context/experienceevent",
      "https://ns.adobe.com/xdm/data/time-series"
  ],
  "meta:containerId": "tenant",
  "imsOrg": "{ORG_ID}",
  "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
  "meta:xdmType": "object",
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
  "version": "1.0",
  "meta:resourceType": "schemas",
  "meta:registryMetadata": {
      "repo:createDate": 1552088461236,
      "repo:lastModifiedDate": 1552088470592,
      "xdm:createdClientId": "{CREATED_CLIENT}",
      "xdm:repositoryCreatedBy": "{CREATED_BY}"
  }
}
NOTE
Per informazioni più dettagliate sulle richieste di PATCH per gli schemi, consulta la guida dell'endpoint degli schemi.

Passaggi successivi

Questa guida illustra come utilizzare le chiamate API per aggiungere singoli campi da un gruppo di campi esistente a uno schema. Per informazioni dettagliate su come eseguire attività simili basate sui campi nell'interfaccia utente di Experience Platform, consulta la guida sui flussi di lavoro basati sui campi.

Per ulteriori informazioni sulle funzionalità dell'API Schema Registry, fare riferimento alla panoramica API per un elenco completo degli endpoint e dei processi.

recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07