Endpoint delle classi

Tutti gli schemi Experience Data Model (XDM) devono essere basati su una classe . Una classe determina la struttura di base delle proprietà comuni che devono contenere tutti gli schemi basati su tale classe, nonché i gruppi di campi dello schema idonei all'utilizzo in tali schemi. Inoltre, la classe di uno schema determina gli aspetti comportamentali dei dati contenuti in uno schema, di cui esistono due tipi:

  • Record: Fornisce informazioni sugli attributi di un oggetto. Un soggetto potrebbe essere un'organizzazione o un individuo.
  • Serie temporali: Fornisce un'istantanea del sistema al momento in cui un'azione è stata eseguita direttamente o indirettamente da un soggetto del record.
NOTA

Per ulteriori classi di informazioni sui comportamenti dei dati in termini di come influiscono sulla composizione dello schema, consulta nozioni di base sulla composizione dello schema.

La /classes punto finale Schema Registry L’API ti consente di gestire le classi a livello di programmazione all’interno dell’applicazione di esperienza.

Introduzione

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

Recupera un elenco di classi

È possibile elencare tutte le classi nella sezione global o tenant effettuando una richiesta GET a /global/classes o /tenant/classes, rispettivamente.

NOTA

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

Formato API

GET /{CONTAINER_ID}/classes?{QUERY_PARAMS}
Parametro Descrizione
{CONTAINER_ID} Il contenitore da cui si desidera recuperare le classi: global per classi create da Adobi o tenant per le classi di proprietà della tua organizzazione.
{QUERY_PARAMS} Parametri di query opzionali per filtrare i risultati in base a. Consulta la sezione documento appendice per un elenco dei parametri disponibili.

Richiesta

La richiesta seguente recupera un elenco di classi dalla tenant contenitore, utilizzando un orderby parametro di query per ordinare le classi in base alle rispettive title attributo.

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 dal Accept intestazione inviata nella richiesta. I seguenti Accept le intestazioni sono disponibili per le classi di elenco:

Accept header Descrizione
application/vnd.adobe.xed-id+json Restituisce un breve riepilogo di ciascuna risorsa. Intestazione consigliata per l’elenco delle risorse. (Limite: 300)
application/vnd.adobe.xed+json Restituisce la classe JSON completa per ogni risorsa, con originale $ref e allOf incluso. (Limite: 300)

Risposta

La richiesta di cui sopra ha utilizzato il application/vnd.adobe.xed-id+json Accept , quindi la risposta include solo l’ title, $id, meta:altIde version attributi per ogni classe. Utilizzo dell'altro Accept header (application/vnd.adobe.xed+json) restituisce tutti gli attributi di ogni classe. Selezionare il Accept a seconda delle 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"
    }
  }
}

Cerca una classe

Puoi cercare una classe specifica includendo l’ID della classe nel percorso di una richiesta GET.

Formato API

GET /{CONTAINER_ID}/classes/{CLASS_ID}
Parametro Descrizione
{CONTAINER_ID} Il contenitore che ospita la classe da recuperare: global per una classe creata da un Adobe o tenant per una classe di proprietà della tua organizzazione.
{CLASS_ID} La meta:altId o con codifica URL $id della classe che si desidera cercare.

Richiesta

La richiesta seguente recupera una classe dalla relativa meta:altId 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 dal Accept intestazione inviata nella richiesta. Tutte le richieste di ricerca richiedono un version sono inclusi nella Accept intestazione. I seguenti Accept le intestazioni sono disponibili:

Accept header Descrizione
application/vnd.adobe.xed+json; version=1 Raw con $ref e allOf, include titoli e descrizioni.
application/vnd.adobe.xed-full+json; version=1 $ref e allOf risolto, con titoli e descrizioni.
application/vnd.adobe.xed-notext+json; version=1 Raw con $ref e allOf, senza titoli o descrizioni.
application/vnd.adobe.xed-full-notext+json; version=1 $ref e allOf risolto, senza titoli o descrizioni.
application/vnd.adobe.xed-full-desc+json; version=1 $ref e allOf risolti, descrittori inclusi.

Risposta

Una risposta corretta restituisce i dettagli della classe. I campi restituiti dipendono dal Accept intestazione inviata nella richiesta. Esperimento con diversi Accept intestazioni per confrontare le risposte e determinare quale intestazione è 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

È possibile definire una classe personalizzata sotto la tenant effettuando una richiesta di POST.

IMPORTANTE

Quando si compone uno schema basato su una classe personalizzata definita dall'utente, non è possibile utilizzare gruppi di campi standard. Ogni gruppo di campi definisce le classi con le quali è compatibile meta:intendedToExtend attributo. Una volta iniziato a definire gruppi di campi compatibili con la nuova classe, utilizzando $id della tua nuova classe meta:intendedToExtend campo del gruppo di campi), sarà possibile riutilizzare tali gruppi di campi ogni volta che si definisce uno schema che implementa la classe definita. Consulta le sezioni creazione di gruppi di campi e creazione di schemi nelle rispettive guide dei punti finali per ulteriori informazioni.

Se prevedi di utilizzare schemi basati su classi personalizzate in Profilo cliente in tempo reale, è anche importante tenere presente che gli schemi di unione sono costruiti solo in base a schemi che condividono la stessa classe. Se si desidera includere uno schema di classe personalizzato nell'unione per un'altra classe come Profilo individuale XDM o ExperienceEvent XDM, è necessario stabilire una relazione con un altro schema che utilizza tale classe. Guarda l’esercitazione su creazione di una relazione tra due schemi nell’API per ulteriori informazioni.

Formato API

POST /tenant/classes

Richiesta

La richiesta di creazione di una classe (POST) deve includere un allOf attributo contenente $ref a 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 (record o serie temporali, rispettivamente). Per ulteriori informazioni sulle differenze tra i dati dei record e i dati delle serie temporali, consulta la sezione sui tipi di comportamento all'interno della nozioni di base sulla composizione dello schema.

Quando si definisce una classe, è anche possibile includere gruppi di campi o campi personalizzati nella definizione della classe. In questo modo i gruppi di campi e i campi aggiunti verranno inclusi in tutti gli schemi che implementano la classe. La richiesta di esempio seguente definisce una classe denominata "Property", che acquisisce informazioni relative a proprietà diverse possedute e gestite da un'azienda. Include un propertyId campo 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"
          }
        ]
      }'
Proprietà Descrizione
_{TENANT_ID} La TENANT_ID spazio dei nomi per la tua organizzazione. Tutte le risorse create dall'organizzazione devono includere questa proprietà per evitare conflitti con altre risorse nel Schema Registry.
allOf Elenco di risorse le cui proprietà devono essere ereditate dalla nuova classe. Uno dei $ref gli oggetti all'interno della matrice definiscono il comportamento della classe. In questo esempio, la classe eredita il comportamento "record".

Risposta

Una risposta corretta restituisce lo stato HTTP 201 (Creato) e un payload contenente i dettagli della nuova classe creata, tra cui $id, meta:altIde version. Questi tre valori sono di sola lettura e sono assegnati dal 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}"
  }
}

Esecuzione di una richiesta GET a elenco tutte le classi in tenant Il contenitore ora include la classe Property . È inoltre possibile eseguire una richiesta di ricerca (GET) utilizzando l’URL-encoded $id per visualizzare direttamente la nuova classe.

Aggiornare una classe

È possibile sostituire un'intera classe tramite un'operazione PUT, essenzialmente riscrivendo la risorsa. Quando si aggiorna una classe tramite una richiesta di PUT, il corpo deve includere tutti i campi necessari quando creazione di una nuova classe in una richiesta POST.

NOTA

Se si desidera aggiornare solo parte di una classe anziché sostituirla completamente, vedere la sezione in aggiornamento di una parte di una classe.

Formato API

PUT /tenant/classes/{CLASS_ID}
Parametro Descrizione
{CLASS_ID} La meta:altId o con codifica URL $id della classe che si desidera riscrivere.

Richiesta

La seguente richiesta riscrive una classe esistente, modificandone la relativa 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

Una risposta corretta 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

È possibile aggiornare una parte di una classe utilizzando una richiesta PATCH. La Schema Registry supporta tutte le operazioni standard di patch JSON, tra cui add, removee replace. Per ulteriori informazioni sulla patch JSON, consulta la sezione Guida di base sulle API.

NOTA

Per sostituire un’intera risorsa con nuovi valori anziché aggiornare singoli campi, consulta la sezione sostituzione di una classe utilizzando un’operazione PUT.

Formato API

PATCH /tenant/class/{CLASS_ID}
Parametro Descrizione
{CLASS_ID} L’URL è codificato $id URI o meta:altId della classe da aggiornare.

Richiesta

La richiesta di esempio riportata di seguito aggiorna la description di una classe esistente e title di uno dei suoi campi.

Il corpo della richiesta assume la forma di una matrice, con ogni oggetto elencato che rappresenta una modifica specifica a un singolo campo. Ogni oggetto include l'operazione da eseguire (op), su quale campo deve essere eseguita l'operazione (path) e quali informazioni dovrebbero essere incluse in tale 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 indica che entrambe le operazioni sono state eseguite correttamente. La description è stato aggiornato insieme al title del propertyId campo .

{
  "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

Talvolta può essere necessario rimuovere una classe dal Registro di sistema dello schema. A tal fine, esegui una richiesta DELETE con l’ID classe fornito nel percorso .

Formato API

DELETE /tenant/classes/{CLASS_ID}
Parametro Descrizione
{CLASS_ID} L’URL è codificato $id URI o meta:altId della classe da 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

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

Puoi confermare l'eliminazione tentando un richiesta di ricerca (GET) per la classe. Sarà necessario includere un Accept intestazione nella richiesta, ma deve ricevere uno stato HTTP 404 (Non trovato) perché la classe è stata rimossa dal Registro di sistema dello schema.

In questa pagina