Endpoint schema

Uno schema può essere considerato come il modello per i dati da inserire in Adobe Experience Platform. Ogni schema è composto da una classe e da zero o più mixin. L'endpoint /schemas nell'API Schema Registry consente di gestire gli schemi a livello di programmazione all'interno dell'applicazione dell'esperienza.

Introduzione

L'endpoint API utilizzato in questa guida fa parte dell' Schema Registry API. Prima di continuare, consultare la guida introduttiva per i collegamenti alla documentazione correlata, una guida alla lettura delle chiamate API di esempio in questo documento e informazioni importanti sulle intestazioni richieste necessarie per eseguire correttamente chiamate a qualsiasi API Experience Platform.

Recupera un elenco di schemi

È possibile elencare tutti gli schemi sotto il contenitore global o tenant effettuando una richiesta di GET rispettivamente a /global/schemas o /tenant/schemas.

NOTA

Quando si elencano le risorse, il Registro di sistema dello schema limita i set di risultati a 300 elementi. Per restituire risorse oltre questo limite, è necessario utilizzare i parametri di paging. È inoltre consigliabile utilizzare parametri di query aggiuntivi per filtrare i risultati e ridurre il numero di risorse restituite. Per ulteriori informazioni, vedere la sezione relativa ai parametri di query nel documento dell'appendice.

Formato API

GET /{CONTAINER_ID}/schemas?{QUERY_PARAMS}
Parametro Descrizione
{CONTAINER_ID} Contenitore che contiene gli schemi da recuperare: global per schemi creati dal Adobe o tenant per gli schemi di proprietà dell'organizzazione.
{QUERY_PARAMS} Parametri di query facoltativi per filtrare i risultati per. Per un elenco dei parametri disponibili, vedere il documento dell'appendice.

Richiesta

La richiesta seguente recupera un elenco di schemi dal contenitore tenant, utilizzando un parametro di query orderby per ordinare i risultati in base all'attributo title.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas?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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Il formato della risposta dipende dall'intestazione Accept inviata nella richiesta. Per elencare gli schemi sono disponibili le seguenti intestazioni Accept:

Accept header Descrizione
application/vnd.adobe.xed-id+json Restituisce un breve riepilogo di ciascuna risorsa. Intestazione consigliata per elencare le risorse. (Limite: 300)
application/vnd.adobe.xed+json Restituisce lo schema JSON completo per ogni risorsa, con $ref originale e allOf inclusi. (Limite: 300)

Risposta

La richiesta precedente ha utilizzato l'intestazione application/vnd.adobe.xed-id+json Accept, pertanto la risposta include solo gli attributi title, $id, meta:altId e version per ogni schema. L'utilizzo dell'altra intestazione Accept (application/vnd.adobe.xed+json) restituisce tutti gli attributi di ogni schema. Selezionate l'intestazione Accept appropriata a seconda delle informazioni richieste nella risposta.

{
  "results": [
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/0238be93d3e7a06aec5e0655955901ec",
      "meta:altId": "_{TENANT_ID}.schemas.0238be93d3e7a06aec5e0655955901ec",
      "version": "1.4",
      "title": "Hotels"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/0ef4ce0d390f0809fad490802f53d30b",
      "meta:altId": "_{TENANT_ID}.schemas.0ef4ce0d390f0809fad490802f53d30b",
      "version": "1.0",
      "title": "Loyalty Members"
    }
  ],
  "_page": {
        "orderby": "title",
        "next": null,
        "count": 2
    },
    "_links": {
        "next": null,
        "global_schemas": {
            "href": "https://platform.adobe.io/data/foundation/schemaregistry/global/schemas"
        }
    }
}

Cercare uno schema

È possibile ricercare uno schema specifico effettuando una richiesta di GET che includa l'ID dello schema nel percorso.

Formato API

GET /{CONTAINER_ID}/schemas/{SCHEMA_ID}
Parametro Descrizione
{CONTAINER_ID} Contenitore che contiene lo schema da recuperare: global per uno schema creato Adobe o tenant per uno schema di proprietà dell'organizzazione.
{SCHEMA_ID} meta:altId o $id con codifica URL dello schema da ricercare.

Richiesta

La richiesta seguente recupera uno schema specificato dal relativo valore meta:altId nel percorso.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.f579a0b5f992c69458ea408ec36571f7da9de15901bab116 \
  -H 'Accept: application/vnd.adobe.xed+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Il formato della risposta dipende dall'intestazione Accept inviata nella richiesta. Tutte le richieste di ricerca richiedono l'inclusione di un elemento version nell'intestazione Accept. Sono disponibili le seguenti intestazioni Accept:

Accept header Descrizione
application/vnd.adobe.xed+json; version={MAJOR_VERSION} Raw con $ref e allOf, ha titoli e descrizioni.
application/vnd.adobe.xed-full+json; version={MAJOR_VERSION} $ref e allOf risolto, con titoli e descrizioni.
application/vnd.adobe.xed-notext+json; version={MAJOR_VERSION} Raw con $ref e allOf, senza titoli o descrizioni.
application/vnd.adobe.xed-full-notext+json; version={MAJOR_VERSION} $ref e allOf risolto, nessun titolo o descrizione.
application/vnd.adobe.xed-full-desc+json; version={MAJOR_VERSION} $ref e allOf risolti, descrittori inclusi.

Risposta

Una risposta corretta restituisce i dettagli dello schema. I campi restituiti dipendono dall'intestazione Accept inviata nella richiesta. Sperimentate con diverse intestazioni Accept per confrontare le risposte e determinare quale intestazione è più adatta all'uso da parte dell'utente.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/20af3f1d4b175f27ba59529d1b51a0c79fc25df454117c80",
  "meta:altId": "_{TENANT_ID}.schemas.20af3f1d4b175f27ba59529d1b51a0c79fc25df454117c80",
  "meta:resourceType": "schemas",
  "version": "1.1",
  "title": "Example schema",
  "type": "object",
  "description": "An example schema created within the tenant container.",
  "allOf": [
      {
          "$ref": "https://ns.adobe.com/xdm/context/profile",
          "type": "object",
          "meta:xdmType": "object"
      },
      {
          "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/443fe51457047d958f4a97853e64e0eca93ef34d7990583b",
          "type": "object",
          "meta:xdmType": "object"
      }
  ],
  "imsOrg": "{IMS_ORG}",
  "meta:extensible": false,
  "meta:abstract": false,
  "meta:extends": [
      "https://ns.adobe.com/{TENANT_ID}/mixins/443fe51457047d958f4a97853e64e0eca93ef34d7990583b",
      "https://ns.adobe.com/xdm/common/auditable",
      "https://ns.adobe.com/xdm/data/record",
      "https://ns.adobe.com/xdm/context/profile"
  ],
  "meta:xdmType": "object",
  "meta:registryMetadata": {
      "repo:createdDate": 1602872911226,
      "repo:lastModifiedDate": 1603381419889,
      "xdm:createdClientId": "{CLIENT_ID}",
      "xdm:lastModifiedClientId": "{CLIENT_ID}",
      "xdm:createdUserId": "{USER_ID}",
      "xdm:lastModifiedUserId": "{USER_ID}",
      "eTag": "84b4da79b7445a4bf1c59269e718065effddb983c492f48e223d49c049c6d589",
      "meta:globalLibVersion": "1.15.4"
  },
  "meta:class": "https://ns.adobe.com/xdm/context/profile",
  "meta:containerId": "tenant",
  "meta:sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
  "meta:sandboxType": "production",
  "meta:tenantNamespace": "_{TENANT_ID}"
}

Creare uno schema

Il processo di composizione dello schema inizia assegnando una classe. La classe definisce gli aspetti comportamentali chiave dei dati (record o serie temporali), nonché i campi minimi richiesti per descrivere i dati che saranno acquisiti.

NOTA

La chiamata di esempio riportata di seguito è solo un esempio di base di come creare uno schema nell'API, con i requisiti minimi di composizione di una classe e nessun mixin. Per i passaggi completi su come creare uno schema nell'API, inclusa la modalità di assegnazione dei campi tramite mixin e tipi di dati, vedere l' esercitazione sulla creazione dello schema.

Formato API

POST /tenant/schemas

Richiesta

La richiesta deve includere un attributo allOf che fa riferimento alla classe $id. Questo attributo definisce la "classe base" che lo schema implementerà. In questo esempio, la classe base è una classe "Informazioni sulle proprietà" creata in precedenza.

curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
  -H 'Authorization: Bearer {ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "title":"Property Information",
        "description": "Property-related information.",
        "type": "object",
        "allOf": [ 
          { 
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590" 
          } 
        ]
      }'
Proprietà Descrizione
allOf Un array di oggetti, con ogni oggetto che fa riferimento a una classe o a un mixin i cui campi viene implementato dallo schema. Ciascun oggetto contiene una singola proprietà ($ref) il cui valore rappresenta la $id della classe o il mixin che verrà implementato nel nuovo schema. È necessario specificare una classe con zero o più mixine aggiuntive. Nell'esempio precedente, il singolo oggetto nell'array allOf è la classe dello schema.

Risposta

Una risposta corretta restituisce lo stato HTTP 201 (Creato) e un payload contenente i dettagli dello schema appena creato, inclusi $id, meta:altId e version. Questi valori sono di sola lettura e sono assegnati da Schema Registry.

{
    "title": "Property Information",
    "description": "Property-related information.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
        "https://ns.adobe.com/xdm/data/record"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "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": 1552088461236,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

Se si esegue una richiesta di GET in elencare tutti gli schemi nel contenitore tenant, il nuovo schema viene ora incluso. È possibile eseguire una richiesta di ricerca GET utilizzando l'URI con codifica URL $id per visualizzare direttamente il nuovo schema.

Per aggiungere altri campi a uno schema, è possibile eseguire un'operazione PATCH per aggiungere mixin agli array allOf e meta:extends dello schema.

Aggiornare uno schema

È possibile sostituire un intero schema tramite un'operazione PUT, in sostanza riscrivendo la risorsa. Quando si aggiorna uno schema tramite una richiesta di PUT, il corpo deve includere tutti i campi che sarebbero necessari durante la creazione di un nuovo schema](#create) in una richiesta di POST.[

NOTA

Se si desidera aggiornare solo parte di uno schema invece di sostituirlo completamente, vedere la sezione relativa all' aggiornamento di una parte di uno schema.

Formato API

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

Richiesta

La richiesta seguente sostituisce uno schema esistente, modificandone gli attributi title, description e allOf.

curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67 \
  -H 'Authorization: Bearer {ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "title":"Commercial Property Information",
        "description": "Information related to commercial properties.",
        "type": "object",
        "allOf": [ 
          { 
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7" 
          } 
        ]
      }'

Risposta

Una risposta corretta restituisce i dettagli dello schema aggiornato.

{
    "title":"Commercial Property Information",
    "description": "Information related to commercial properties.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7",
        "https://ns.adobe.com/xdm/data/record"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "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}"
    }
}

Aggiornare una parte di uno schema

È possibile aggiornare una parte di uno schema utilizzando una richiesta di PATCH. Schema Registry supporta tutte le operazioni standard di patch JSON, incluse add, remove e replace. Per ulteriori informazioni sulla patch JSON, consultate la Guida di base delle API.

NOTA

Se si desidera sostituire un'intera risorsa con nuovi valori invece di aggiornare i singoli campi, consultare la sezione relativa alla sostituzione di uno schema con un'operazione PUT](#put).[

Una delle operazioni PATCH più comuni consiste nell'aggiungere mixin definiti in precedenza a uno schema, come illustrato nell'esempio seguente.

Formato API

PATCH /tenant/schema/{SCHEMA_ID} 
Parametro Descrizione
{SCHEMA_ID} URI con codifica URL $id o meta:altId dello schema da aggiornare.

Richiesta

La richiesta di esempio seguente aggiunge un nuovo mixin a uno schema aggiungendo il valore $id del mixin sia agli array meta:extends che agli array allOf.

Il corpo della richiesta assume la forma di una matrice, con ogni oggetto elencato che rappresenta una specifica modifica a un singolo campo. Ciascun oggetto include l'operazione da eseguire (op), il campo in cui deve essere eseguita l'operazione (path) e le informazioni da includere in tale operazione (value).

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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'content-type: application/json' \
  -d '[
        { 
          "op": "add",
          "path": "/meta:extends/-",
          "value":  "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
        },
        {
          "op": "add",
          "path": "/allOf/-",
          "value":  {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
          }
        }
      ]'

Risposta

La risposta indica che entrambe le operazioni sono state eseguite correttamente. Il mixin $id è stato aggiunto all'array meta:extends e un riferimento ($ref) al mixin $id viene ora visualizzato nell'array allOf.

{
    "title": "Property Information",
    "description": "Property-related information.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
    "meta:xdmType": "object",
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
    "version": "1.1",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1552088461236,
        "repo:lastModifiedDate": 1552088649634,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

Abilita uno schema da utilizzare nel profilo cliente in tempo reale

Affinché uno schema possa partecipare a Profilo cliente in tempo reale, è necessario aggiungere un tag union all'array meta:immutableTags dello schema. È possibile eseguire questa operazione eseguendo una richiesta PATCH per lo schema in questione.

IMPORTANTE

I tag immutabili sono tag destinati a essere impostati ma non rimossi.

Formato API

PATCH /tenant/schema/{SCHEMA_ID} 
Parametro Descrizione
{SCHEMA_ID} URI con codifica URL $id o meta:altId dello schema da attivare.

Richiesta

La richiesta di esempio seguente aggiunge un array meta:immutableTags a uno schema esistente, assegnando alla matrice un singolo valore di stringa di union per consentirne l'utilizzo in Profile.

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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'content-type: application/json' \
  -d '[
        {
          "op": "add",
          "path": "/meta:immutableTags",
          "value": ["union"]
        }
      ]'

Risposta

Una risposta corretta restituisce i dettagli dello schema aggiornato, indicando che è stata aggiunta l'array meta:immutableTags.

{
    "title": "Property Information",
    "description": "Property-related information.",
    "type": "object",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
        }
    ],
    "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/{TENANT_ID}/mixins/e49cbb2eec33618f686b8344b4597ecf"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:altId": "_{TENANT_ID}.schemas.d5cc04eb8d50190001287e4c869ebe67",
    "meta:xdmType": "object",
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/d5cc04eb8d50190001287e4c869ebe67",
    "version": "1.1",
    "meta:resourceType": "schemas",
    "meta:registryMetadata": {
        "repo:createDate": 1552088461236,
        "repo:lastModifiedDate": 1552088649634,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    },
    "meta:immutableTags": [
      "union"
    ]
}

È ora possibile visualizzare l'unione per la classe dello schema per confermare che i campi dello schema siano rappresentati. Per ulteriori informazioni, vedere la guida dell'endpoint dei sindacati.

Eliminare uno schema

Può essere talvolta necessario rimuovere uno schema dal Registro di sistema dello schema. A questo scopo, è necessario eseguire una richiesta di DELETE con l'ID dello schema fornito nel percorso.

Formato API

DELETE /tenant/schemas/{SCHEMA_ID}
Parametro Descrizione
{SCHEMA_ID} URI con codifica URL $id o meta:altId dello schema da eliminare.

Richiesta

curl -X DELETE \
  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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

Una risposta corretta restituisce lo stato HTTP 204 (Nessun contenuto) e un corpo vuoto.

È possibile confermare l'eliminazione provando una richiesta di ricerca (GET) allo schema. Sarà necessario includere un'intestazione Accept nella richiesta, ma dovrebbe ricevere uno stato HTTP 404 (non trovato) perché lo schema è stato rimosso dal Registro di sistema dello schema.

In questa pagina

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free