Endpoint degli schemi

Uno schema può essere considerato come il modello per i dati che desideri inserire in Adobe Experience Platform. Ogni schema è composto da una classe e da zero o più gruppi di campi dello schema. La /schemas punto finale Schema Registry L’API ti consente di gestire gli schemi a livello di programmazione all’interno dell’applicazione di esperienza.

Introduzione

L’endpoint API utilizzato in questa guida fa parte del Schema Registry API. 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 schemi

Puoi elencare tutti gli schemi sotto la sezione global o tenant effettuando una richiesta GET a /global/schemas o /tenant/schemas, 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}/schemas?{QUERY_PARAMS}
Parametro Descrizione
{CONTAINER_ID} Il contenitore che ospita gli schemi da recuperare: global per schemi creati da Adobi o tenant per gli schemi di proprietà dell’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 seguente richiesta recupera un elenco di schemi dal tenant contenitore, utilizzando un orderby parametro di query per ordinare i risultati in base ai relativi title attributo.

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: {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 elencare gli schemi:

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 lo schema JSON completo 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 schema. Utilizzo dell'altro Accept header (application/vnd.adobe.xed+json) restituisce tutti gli attributi di ogni schema. Selezionare il Accept 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

Puoi cercare 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} Il contenitore che ospita lo schema da recuperare: global per uno schema creato da un Adobe o tenant per uno schema di proprietà dell'organizzazione.
{SCHEMA_ID} La meta:altId o con codifica URL $id dello schema da cercare.

Richiesta

La richiesta seguente recupera uno schema specificato dai relativi 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: {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 dello schema. 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}/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": "{ORG_ID}",
  "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 con l'assegnazione di una classe. La classe definisce gli aspetti comportamentali chiave dei dati (record o serie temporali), nonché i campi minimi necessari per descrivere i dati che verranno acquisiti.

NOTA

La chiamata di esempio riportata di seguito è solo un esempio di base su come creare uno schema nell’API, con i requisiti di composizione minimi di una classe e nessun gruppo di campi. Per i passaggi completi su come creare uno schema nell’API, incluso come assegnare campi utilizzando gruppi di campi e tipi di dati, vedi esercitazione sulla creazione dello schema.

Formato API

POST /tenant/schemas

Richiesta

La richiesta deve includere un allOf attributo che fa riferimento al $id di una classe. Questo attributo definisce la "classe base" che lo schema implementerà. In questo esempio, la classe base è una classe "Informazioni 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: {ORG_ID}' \
  -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 Matrice di oggetti, con ogni oggetto che fa riferimento a una classe o a un gruppo di campi i cui campi vengono implementati dallo schema. Ogni oggetto contiene una singola proprietà ($ref) il cui valore rappresenta $id della classe o del gruppo di campi che verrà implementato dal nuovo schema. È necessario specificare una classe con zero o più gruppi di campi aggiuntivi. Nell'esempio precedente, il singolo oggetto nel allOf array è la classe dello schema.

Risposta

Una risposta corretta restituisce lo stato HTTP 201 (Creato) e un payload contenente i dettagli dello schema appena creato, tra cui $id, meta:altIde version. Questi valori sono di sola lettura e sono assegnati dal 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": "{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": 1552088461236,
        "xdm:createdClientId": "{CREATED_CLIENT}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    }
}

Esecuzione di una richiesta GET a elencare tutti gli schemi nel contenitore tenant ora includerebbe il nuovo schema. È possibile eseguire un richiesta di ricerca (GET) utilizzando l’URL-encoded $id URI per visualizzare direttamente il nuovo schema.

Per aggiungere campi aggiuntivi a uno schema, è possibile eseguire una Funzionamento PATCH per aggiungere gruppi di campi al allOf e meta:extends array.

Aggiornare uno schema

È possibile sostituire un intero schema tramite un’operazione PUT, essenzialmente riscrivendo la risorsa. Quando si aggiorna uno schema tramite una richiesta di PUT, il corpo deve includere tutti i campi necessari quando creazione di un nuovo schema in una richiesta POST.

NOTA

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

Formato API

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

Richiesta

La seguente richiesta sostituisce uno schema esistente, modificandone il title, descriptione allOf attributi.

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: {ORG_ID}' \
  -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": "{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}"
    }
}

Aggiornare una parte di uno schema

È possibile aggiornare una parte di uno schema utilizzando una richiesta di 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 uno schema con un’operazione PUT.

Una delle operazioni più comuni di PATCH consiste nell’aggiungere a uno schema gruppi di campi definiti in precedenza, come illustrato nell’esempio seguente.

Formato API

PATCH /tenant/schema/{SCHEMA_ID}
Parametro Descrizione
{SCHEMA_ID} L’URL è codificato $id URI o meta:altId dello schema da aggiornare.

Richiesta

Nella richiesta di esempio seguente viene aggiunto un nuovo gruppo di campi a uno schema aggiungendo il gruppo di campi $id sia per meta:extends e allOf array.

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/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": "/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. Gruppo di campi $id è stato aggiunto al meta:extends array e un riferimento ($ref) al gruppo di campi $id ora viene visualizzato in allOf array.

{
    "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": "{ORG_ID}",
    "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}"
    }
}

Abilitare uno schema da utilizzare nel profilo cliente in tempo reale

Al fine di uno schema a cui partecipare Profilo cliente in tempo reale, devi aggiungere un union tag per lo schema meta:immutableTags array. Puoi eseguire questa operazione effettuando una richiesta PATCH per lo schema in questione.

IMPORTANTE

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

Formato API

PATCH /tenant/schema/{SCHEMA_ID}
Parametro Descrizione
{SCHEMA_ID} L’URL è codificato $id URI o meta:altId dello schema che desideri abilitare.

Richiesta

La richiesta di esempio seguente aggiunge un meta:immutableTags a uno schema esistente, fornendo all'array un singolo valore di stringa di union per abilitarlo all’uso in Profilo.

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": "/meta:immutableTags",
          "value": ["union"]
        }
      ]'

Risposta

Una risposta corretta restituisce i dettagli dello schema aggiornato, indicando che il meta:immutableTags è stato aggiunto l’array .

{
    "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": "{ORG_ID}",
    "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 di questo schema per verificare che i campi dello schema siano rappresentati. Consulta la sezione guida all’endpoint sindacati per ulteriori informazioni.

Eliminare uno schema

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

Formato API

DELETE /tenant/schemas/{SCHEMA_ID}
Parametro Descrizione
{SCHEMA_ID} L’URL è codificato $id URI 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: {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 una richiesta di ricerca (GET) allo schema. Sarà necessario includere un Accept intestazione nella richiesta, ma deve ricevere uno stato HTTP 404 (Non trovato) perché lo schema è stato rimosso dal Registro di sistema dello schema.

In questa pagina