Endpoint "class"
Tutti gli schemi Experience Data Model (XDM) devono essere basati su una classe. Una classe determina la struttura di base delle proprietà comuni che tutti gli schemi basati su tale classe devono contenere, nonché i gruppi di campi di schema idonei per l’utilizzo in tali schemi. Inoltre, la classe di uno schema determina gli aspetti comportamentali dei dati che uno schema conterrà, di cui esistono due tipi:
- Record: fornisce informazioni sugli attributi di un oggetto. Un soggetto potrebbe essere un'organizzazione o un individuo.
- Serie temporale: fornisce un'istantanea del sistema nel momento in cui un oggetto record ha eseguito un'azione direttamente o indirettamente.
L'endpoint /classes
nell'API Schema Registry consente di gestire in modo programmatico le classi all'interno dell'applicazione Experience.
Introduzione
L'endpoint utilizzato in questa guida fa parte dell'Schema Registry API. Prima di continuare, consulta la guida introduttiva per i collegamenti alla documentazione correlata, una guida alla lettura delle chiamate API di esempio in questo documento e per le informazioni importanti sulle intestazioni necessarie per effettuare correttamente le chiamate a qualsiasi API di Experience Platform.
Recuperare un elenco di classi list
È possibile elencare tutte le classi nel contenitore global
o tenant
effettuando una richiesta GET rispettivamente a /global/classes
o /tenant/classes
.
Formato API
GET /{CONTAINER_ID}/classes?{QUERY_PARAMS}
{CONTAINER_ID}
global
per le classi create dall'Adobe o tenant
per le classi appartenenti all'organizzazione.{QUERY_PARAMS}
Richiesta
La richiesta seguente recupera un elenco di classi dal contenitore tenant
, utilizzando un parametro di query orderby
per ordinare le classi in base al relativo attributo title
.
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/classes?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: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Il formato della risposta dipende dall'intestazione Accept
inviata nella richiesta. Le seguenti intestazioni Accept
sono disponibili per l'elenco delle classi:
Accept
application/vnd.adobe.xed-id+json
application/vnd.adobe.xed+json
$ref
e allOf
originali. (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 classe. L'utilizzo dell'altra intestazione Accept
(application/vnd.adobe.xed+json
) restituisce tutti gli attributi di ciascuna classe. Selezionare l'intestazione Accept
appropriata in base alle informazioni richieste nella risposta.
{
"results": [
{
"$id": "https://ns.adobe.com/{TENANT_ID}/classes/01b7b1745e8ac4ed1e8784ec91b6afa7",
"meta:altId": "_{TENANT_ID}.classes.01b7b1745e8ac4ed1e8784ec91b6afa7",
"version": "1.0",
"title": "Hotel"
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/classes/d43b86253676af50da3f671ecdd26ff9",
"meta:altId": "_{TENANT_ID}.classes.d43b86253676af50da3f671ecdd26ff9",
"version": "1.1",
"title": "Property"
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/classes/366f015dbfea802455fbc46c3b27f771",
"meta:altId": "_{TENANT_ID}.classes.366f015dbfea802455fbc46c3b27f771",
"version": "1.0",
"title": "Subscription"
}
],
"_page": {
"orderby": "title",
"next": null,
"count": 3
},
"_links": {
"next": null,
"global_schemas": {
"href": "https://platform.adobe.io/data/foundation/schemaregistry/global/classes"
}
}
}
Cercare una classe lookup
Per cercare una classe specifica, devi includere l’ID della classe nel percorso di una richiesta GET.
Formato API
GET /{CONTAINER_ID}/classes/{CLASS_ID}
{CONTAINER_ID}
global
per una classe creata da un Adobe o tenant
per una classe di proprietà dell'organizzazione.{CLASS_ID}
meta:altId
o $id
con codifica URL della classe che si desidera cercare.Richiesta
La richiesta seguente recupera una classe in base al valore meta:altId
fornito nel percorso.
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/classes/_{TENANT_ID}.classes.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: {ORG_ID}' \
-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 version
nell'intestazione Accept
. Sono disponibili le seguenti Accept
intestazioni:
Accept
application/vnd.adobe.xed+json; version=1
$ref
e allOf
, con titoli e descrizioni.application/vnd.adobe.xed-full+json; version=1
$ref
e allOf
risolti, con titoli e descrizioni.application/vnd.adobe.xed-notext+json; version=1
$ref
e allOf
, nessun titolo o descrizione.application/vnd.adobe.xed-full-notext+json; version=1
$ref
e allOf
risolti, nessun titolo o descrizione.application/vnd.adobe.xed-full-desc+json; version=1
$ref
e allOf
risolti, descrittori inclusi.Risposta
In caso di esito positivo, la risposta restituisce i dettagli della classe. I campi restituiti dipendono dall'intestazione Accept
inviata nella richiesta. Prova a confrontare le risposte con intestazioni Accept
diverse e a determinare quale sia il migliore per il tuo caso d'uso.
{
"$id":"https://ns.adobe.com/{TENANT_ID}/classes/f8bbdc3c49d49eae62d1c17e867230ac3de6b5b63b0615ce",
"meta:altId":"_{TENANT_ID}.classes.f8bbdc3c49d49eae62d1c17e867230ac3de6b5b63b0615ce",
"meta:resourceType":"classes",
"version":"1.1",
"title":"Hotel",
"type":"object",
"description":"Base class for the Hotels schema",
"definitions":{
"customFields":{
"type":"object",
"properties":{
"_{TENANT_ID}":{
"type":"object",
"properties":{
"Address":{
"title":"Address",
"description":"",
"isRequired":false,
"$ref":"https://ns.adobe.com/xdm/common/address",
"type":"object",
"meta:xdmType":"object"
},
"phoneNumber":{
"title":"Phone Number",
"description":"",
"isRequired":false,
"$ref":"https://ns.adobe.com/xdm/context/phonenumber",
"type":"object",
"meta:xdmType":"object"
},
"brand":{
"title":"Brand",
"description":"",
"type":"string",
"isRequired":false,
"meta:xdmType":"string"
},
"hotelId":{
"title":"Hotel ID",
"description":"",
"type":"string",
"isRequired":false,
"meta:xdmType":"string"
}
},
"meta:xdmType":"object"
}
},
"meta:xdmType":"object"
}
},
"allOf":[
{
"$ref":"https://ns.adobe.com/xdm/data/record",
"type":"object",
"meta:xdmType":"object"
},
{
"$ref":"#/definitions/customFields",
"type":"object",
"meta:xdmType":"object"
}
],
"imsOrg":"{ORG_ID}",
"meta:extensible":true,
"meta:abstract":true,
"meta:extends":[
"https://ns.adobe.com/xdm/data/record"
],
"meta:xdmType":"object",
"meta:registryMetadata":{
"repo:createdDate":1593643258779,
"repo:lastModifiedDate":1597246362579,
"xdm:createdClientId":"{CLIENT_ID}",
"xdm:lastModifiedClientId":"{CLIENT_ID}",
"xdm:createdUserId":"{USER_ID}",
"xdm:lastModifiedUserId":"{USER_ID}",
"eTag":"502f89ee16b8ab2e6b4ea09ecf0ab1e5614907db755051c1f3c65a273001d725",
"meta:globalLibVersion":"1.15.4"
},
"meta:containerId":"tenant",
"meta:tenantNamespace":"_{TENANT_ID}"
}
Creare una classe create
È possibile definire una classe personalizzata nel contenitore tenant
effettuando una richiesta POST.
meta:intendedToExtend
. Una volta iniziata la definizione dei gruppi di campi compatibili con la nuova classe (utilizzando $id
della nuova classe nel campo meta:intendedToExtend
del gruppo di campi), sarà possibile riutilizzare tali gruppi di campi ogni volta che si definisce uno schema che implementa la classe definita. Per ulteriori informazioni, consulta le sezioni su creazione di gruppi di campi e creazione di schemi nelle rispettive guide degli endpoint.Formato API
POST /tenant/classes
Richiesta
La richiesta di creazione (POST) di una classe deve includere un attributo allOf
contenente un valore $ref
in uno dei due valori seguenti: https://ns.adobe.com/xdm/data/record
o https://ns.adobe.com/xdm/data/time-series
. Questi valori rappresentano il comportamento su cui si basa la classe (rispettivamente record o serie temporali). Per ulteriori informazioni sulle differenze tra i dati dei record e i dati delle serie temporali, vedere la sezione sui tipi di comportamento all'interno delle nozioni di base sulla composizione dello schema.
Quando si definisce una classe, è possibile includere anche gruppi di campi o campi personalizzati all'interno della definizione della classe. In questo modo, i gruppi di campi e i campi aggiunti verrebbero inclusi in tutti gli schemi che implementano la classe. L’esempio di richiesta seguente definisce una classe denominata "Property" (Proprietà), che acquisisce informazioni relative a diverse proprietà possedute e gestite da un’azienda. Include un campo propertyId
da includere ogni volta che la classe viene utilizzata.
curl -X POST \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/classes \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"title":"Property",
"description":"Properties owned and operated by the company.",
"type":"object",
"definitions": {
"property": {
"properties": {
"_{TENANT_ID}": {
"type": "object",
"properties": {
"property": {
"title": "Property Information",
"type": "object",
"description": "Information about different owned and operated properties.",
"properties": {
"propertyId": {
"title": "Property Identification Number",
"type": "string",
"description": "Unique Property identification number"
}
}
}
}
}
},
"type": "object"
}
},
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/data/record"
},
{
"$ref": "#/definitions/property"
}
]
}'
_{TENANT_ID}
TENANT_ID
per la tua organizzazione. Tutte le risorse create dall'organizzazione devono includere questa proprietà per evitare conflitti con altre risorse in Schema Registry.allOf
$ref
nell'array definisce il comportamento della classe. In questo esempio, la classe eredita il comportamento "record".Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 201 (Creato) e un payload contenente i dettagli della classe appena creata, inclusi $id
, meta:altId
e version
. Questi tre valori sono di sola lettura e sono assegnati da Schema Registry.
{
"title": "Property",
"description": "Properties owned and operated by the company.",
"type": "object",
"definitions": {
"property": {
"properties": {
"_{TENANT_ID}": {
"type": "object",
"properties": {
"property": {
"title": "Property Information",
"type": "object",
"description": "Information about different owned and operated properties.",
"properties": {
"propertyId": {
"title": "Property Identification Number",
"type": "string",
"description": "Unique Property identification number",
"meta:xdmType": "string"
}
},
"meta:xdmType": "object"
}
},
"meta:xdmType": "object"
}
},
"type": "object",
"meta:xdmType": "object"
}
},
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/data/record"
},
{
"$ref": "#/definitions/property"
}
],
"meta:abstract": true,
"meta:extensible": true,
"meta:extends": [
"https://ns.adobe.com/xdm/data/record"
],
"meta:containerId": "tenant",
"imsOrg": "{ORG_ID}",
"meta:altId": "_{TENANT_ID}.classes.19e1d8b5098a7a76e2c10a81cbc99590",
"meta:xdmType": "object",
"$id": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
"version": "1.0",
"meta:resourceType": "classes",
"meta:registryMetadata": {
"repo:createDate": 1552086405448,
"repo:lastModifiedDate": 1552086405448,
"xdm:createdClientId": "{CREATED_CLIENT}",
"xdm:repositoryCreatedBy": "{CREATED_BY}"
}
}
L'esecuzione di una richiesta di GET per elencare tutte le classi nel contenitore tenant
includerebbe ora la classe Property. È inoltre possibile eseguire una richiesta di ricerca (GET) utilizzando l'URL codificato $id
per visualizzare direttamente la nuova classe.
Aggiornare una classe put
Puoi sostituire un’intera classe tramite un’operazione PUT, essenzialmente riscrivendo la risorsa. Quando si aggiorna una classe tramite una richiesta PUT, il corpo deve includere tutti i campi necessari per la creazione di una nuova classe in una richiesta POST.
Formato API
PUT /tenant/classes/{CLASS_ID}
{CLASS_ID}
meta:altId
o $id
con codifica URL della classe che si desidera riscrivere.Richiesta
La richiesta seguente riscrive una classe esistente, modificandone description
e title
di uno dei suoi campi.
curl -X PUT \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/classes/_{TENANT_ID}.classes.19e1d8b5098a7a76e2c10a81cbc99590 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"title": "Property",
"description": "Base class for properties operated by a company.",
"type": "object",
"definitions": {
"property": {
"properties": {
"_{TENANT_ID}": {
"type": "object",
"properties": {
"property": {
"title": "Property Information",
"type": "object",
"description": "Information about different owned and operated properties.",
"properties": {
"propertyId": {
"title": "Property ID",
"type": "string",
"description": "Unique Property ID string."
}
}
}
}
}
},
"type": "object"
}
},
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/data/record"
},
{
"$ref": "#/definitions/property"
}
]
}'
Risposta
In caso di esito positivo, la risposta restituisce i dettagli della classe aggiornata.
{
"title": "Property",
"description": "Base class for properties operated by a company.",
"type": "object",
"definitions": {
"property": {
"properties": {
"_{TENANT_ID}": {
"type": "object",
"properties": {
"property": {
"title": "Property Information",
"type": "object",
"description": "Information about different owned and operated properties.",
"properties": {
"propertyId": {
"title": "Property ID",
"type": "string",
"description": "Unique Property ID string",
"meta:xdmType": "string"
}
},
"meta:xdmType": "object"
}
},
"meta:xdmType": "object"
}
},
"type": "object",
"meta:xdmType": "object"
}
},
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/data/record"
},
{
"$ref": "#/definitions/property"
}
],
"meta:abstract": true,
"meta:extensible": true,
"meta:extends": [
"https://ns.adobe.com/xdm/data/record"
],
"meta:containerId": "tenant",
"imsOrg": "{ORG_ID}",
"meta:altId": "_{TENANT_ID}.classes.19e1d8b5098a7a76e2c10a81cbc99590",
"meta:xdmType": "object",
"$id": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
"version": "1.0",
"meta:resourceType": "classes",
"meta:registryMetadata": {
"repo:createDate": 1552086405448,
"repo:lastModifiedDate": 1552086405448,
"xdm:createdClientId": "{CREATED_CLIENT}",
"xdm:repositoryCreatedBy": "{CREATED_BY}"
}
}
Aggiornare una parte di una classe patch
È possibile aggiornare una parte di una classe utilizzando una richiesta PATCH. Schema Registry 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/class/{CLASS_ID}
{CLASS_ID}
$id
con codifica URL o meta:altId
della classe da aggiornare.Richiesta
La richiesta di esempio seguente aggiorna il description
di una classe esistente e il title
di uno dei suoi campi.
Il corpo della richiesta è un array e ogni oggetto elencato rappresenta una modifica specifica di un singolo campo. Ogni oggetto include l'operazione da eseguire (op
), il campo in cui deve essere eseguita l'operazione (path
) e le informazioni da includere nell'operazione (value
).
curl -X PATCH \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/classes/_{TENANT_ID}.classes.19e1d8b5098a7a76e2c10a81cbc99590 \
-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": "replace", "path": "/description", "value": "Base class for properties operated by a company."},
{ "op": "replace", "path": "/definitions/property/properties/_{TENANT_ID}/properties/property/properties/propertyId/title", "value": "Unique Property ID string" }
]'
Risposta
La risposta mostra che entrambe le operazioni sono state eseguite correttamente. description
è stato aggiornato insieme a title
del campo propertyId
.
{
"title": "Property",
"description": "Base class for properties operated by a company.",
"type": "object",
"definitions": {
"property": {
"properties": {
"_{TENANT_ID}": {
"type": "object",
"properties": {
"property": {
"title": "Property Information",
"type": "object",
"description": "Information about different owned and operated properties.",
"properties": {
"propertyId": {
"title": "Property ID",
"type": "string",
"description": "Unique Property ID string",
"meta:xdmType": "string"
}
},
"meta:xdmType": "object"
}
},
"meta:xdmType": "object"
}
},
"type": "object",
"meta:xdmType": "object"
}
},
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/data/record"
},
{
"$ref": "#/definitions/property"
}
],
"meta:abstract": true,
"meta:extensible": true,
"meta:extends": [
"https://ns.adobe.com/xdm/data/record"
],
"meta:containerId": "tenant",
"imsOrg": "{ORG_ID}",
"meta:altId": "_{TENANT_ID}.classes.19e1d8b5098a7a76e2c10a81cbc99590",
"meta:xdmType": "object",
"$id": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590",
"version": "1.0",
"meta:resourceType": "classes",
"meta:registryMetadata": {
"repo:createDate": 1552086405448,
"repo:lastModifiedDate": 1552086405448,
"xdm:createdClientId": "{CREATED_CLIENT}",
"xdm:repositoryCreatedBy": "{CREATED_BY}"
}
}
Eliminare una classe delete
A volte può essere necessario rimuovere una classe dal registro degli schemi. Questa operazione viene eseguita eseguendo una richiesta DELETE con l’ID di classe fornito nel percorso.
Formato API
DELETE /tenant/classes/{CLASS_ID}
{CLASS_ID}
$id
con codifica URL o meta:altId
della classe che si desidera eliminare.Richiesta
curl -X DELETE \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/classes/_{TENANT_ID}.classes.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}'
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 204 (nessun contenuto) e un corpo vuoto.
È possibile confermare l'eliminazione tentando una richiesta di ricerca (GET) per la classe. È necessario includere un'intestazione Accept
nella richiesta, ma dovrebbe ricevere lo stato HTTP 404 (Non trovato) perché la classe è stata rimossa dal registro degli schemi.