Show Menu
ARGOMENTI×

Descrittori

Gli schemi definiscono una visualizzazione statica delle entità di dati, ma non forniscono dettagli specifici su come i dati basati su tali schemi (ad esempio, set di dati) possono essere correlati tra loro. Adobe Experience Platform consente di descrivere queste relazioni e altri metadati interpretativi di uno schema utilizzando i descrittori.
I descrittori dello schema sono metadati a livello di tenant, il che significa che sono univoci per l'organizzazione IMS e che tutte le operazioni del descrittore hanno luogo nel contenitore tenant.
A ogni schema può essere applicata una o più entità descrittori dello schema. Ogni entità descrittore dello schema include un descrittore @type e l' sourceSchema oggetto a cui si applica. Una volta applicati, questi descrittori verranno applicati a tutti i set di dati creati utilizzando lo schema.
Questo documento fornisce esempi di chiamate API per descrittori, oltre a un elenco completo di descrittori disponibili e i campi richiesti per la definizione di ciascun tipo.
I descrittori richiedono intestazioni Accetto univoche che sostituiscono xed con xdm , ma che hanno un aspetto molto simile a Accetta intestazioni utilizzate altrove in Schema Registry. Le intestazioni Accetta corrette sono state incluse nelle chiamate di esempio riportate di seguito, ma prestate particolare attenzione a verificare che vengano utilizzate le intestazioni corrette.

Descrittori elenco

Una singola richiesta di GET può essere utilizzata per restituire un elenco di tutti i descrittori definiti dall'organizzazione.
Formato API
GET /tenant/descriptors

Richiesta
curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -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 'Accept: application/vnd.adobe.xdm-link+json'

Il formato della risposta dipende dall’intestazione Accetta inviata nella richiesta. L' /descriptors endpoint utilizza intestazioni Accept diverse da tutti gli altri endpoint nell' Schema Registry API.
Il descrittore Accetta intestazioni sostituisce xed con xdm , e offre un' link opzione univoca per i descrittori.
Accetta
Descrizione
application/vnd.adobe.xdm-id+json
Restituisce un array di ID descrittori
application/vnd.adobe.xdm-link+json
Restituisce un array di percorsi API del descrittore
application/vnd.adobe.xdm+json
Restituisce un array di oggetti descrittori espansi
Risposta
La risposta include un array per ciascun tipo di descrittore con descrittori definiti. In altre parole, se non esistono descrittori di un certo tipo @type definito, il Registro di sistema non restituirà una matrice vuota per quel tipo di descrittore.
Quando si utilizza l'intestazione link Accetto, ogni descrittore viene visualizzato come un elemento di array nel formato /{CONTAINER}/descriptors/{DESCRIPTOR_ID}
{
  "xdm:alternateDisplayInfo": [
    "/tenant/descriptors/85dc1bc8b91516ac41163365318e38a9f1e4f351",
    "/tenant/descriptors/49bd5abb5a1310ee80ebc1848eb508d383a462cf",
    "/tenant/descriptors/b3b3e548f1c653326bcf5459ceac4140fc0b9e08"
  ],
  "xdm:descriptorIdentity": [
    "/tenant/descriptors/f7a4bc25429496c4740f8f9a7a49ba96862c5379"
  ],
  "xdm:descriptorOneToOne": [
    "/tenant/descriptors/cb509fd6f8ab6304e346905441a34b58a0cd481a"
  ]
}

Cercare un descrittore

Se desiderate visualizzare i dettagli di un descrittore specifico, potete cercare (GET) un singolo descrittore utilizzando il relativo @id .
Formato API
GET /tenant/descriptors/{DESCRIPTOR_ID}

Parametro
Descrizione
{DESCRIPTOR_ID}
Specifica @id del descrittore da cercare.
Richiesta
I descrittori non dispongono di una versione, pertanto nella richiesta di ricerca non è richiesta alcuna intestazione Accetto.
curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -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 i dettagli del descrittore, inclusi i relativi @type e sourceSchema , nonché informazioni aggiuntive che variano a seconda del tipo di descrittore. Il valore restituito @id deve corrispondere al descrittore @id fornito nella richiesta.
{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "createdUser": "{CREATED_USER}",
  "imsOrg": "{IMS_ORG}",
  "createdClient": "{CREATED_CLIENT}",
  "updatedUser": "{UPDATED_USER}",
  "created": 1548899346989,
  "updated": 1548899346989,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Creare un descrittore

Consente di Schema Registry definire diversi tipi di descrittori. Ogni tipo di descrittore richiede l'invio di campi specifici nella richiesta POST. Un elenco completo dei descrittori e i campi necessari per definirli è disponibile nella sezione appendice sulla definizione dei descrittori .
Formato API
POST /tenant/descriptors

Richiesta
La richiesta seguente definisce un descrittore di identità in un campo "indirizzo e-mail" in uno schema di esempio. Questo indica Experience Platform di utilizzare l'indirizzo e-mail come identificatore per unire insieme le informazioni sull'individuo.
curl -X POST \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -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 '
      {
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/personalEmail/address",
        "xdm:namespace": "Email",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

Risposta
Una risposta corretta restituisce lo stato HTTP 201 (Creato) e i dettagli del descrittore appena creato, incluso @id il relativo. Il campo @id è di sola lettura assegnato dal Schema Registry e utilizzato per fare riferimento al descrittore nell'API.
{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Descrittore di aggiornamento

Potete aggiornare un descrittore effettuando una richiesta di PUT che fa riferimento al descrittore @id da aggiornare nel percorso della richiesta.
Formato API
PUT /tenant/descriptors/{DESCRIPTOR_ID}

Parametro
Descrizione
{DESCRIPTOR_ID}
Indica @id il nome del descrittore da aggiornare.
Richiesta
Questa richiesta riscrive in sostanza il descrittore, pertanto il corpo della richiesta deve includere tutti i campi necessari per definire un descrittore di quel tipo. In altre parole, il payload di richiesta per aggiornare (PUT) un descrittore è lo stesso del payload per creare (POST) un descrittore dello stesso tipo.
In questo esempio, il descrittore di identità viene aggiornato per fare riferimento a un altro xdm:sourceProperty ("telefono cellulare") e cambiare il xdm:namespace nome in "telefono".
curl -X PUT \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/f3a1dfa38a4871cf4442a33074c1f9406a593407 \
  -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 '{
        "@type": "xdm:descriptorIdentity",
        "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "xdm:sourceVersion": 1,
        "xdm:sourceProperty": "/mobilePhone/number",
        "xdm:namespace": "Phone",
        "xdm:property": "xdm:code",
        "xdm:isPrimary": false
      }'

I dettagli relativi alle proprietà xdm:namespace e xdm:property , comprese le modalità di accesso, sono disponibili nella sezione dell'appendice relativa alla definizione dei descrittori .
Risposta
Una risposta corretta restituisce lo stato HTTP 201 (Creato) e il @id valore del descrittore aggiornato (che deve corrispondere a quello @id inviato nella richiesta).
{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Se si esegue una richiesta di ricerca (GET) per visualizzare il descrittore, i campi vengono ora aggiornati per riflettere le modifiche inviate nella richiesta di PUT.

Elimina descrittore

Talvolta potrebbe essere necessario rimuovere un descrittore definito dall' Schema Registry. Questa operazione viene eseguita effettuando una richiesta di DELETE che fa riferimento al descrittore @id da rimuovere.
Formato API
DELETE /tenant/descriptors/{DESCRIPTOR_ID}

Parametro
Descrizione
{DESCRIPTOR_ID}
Indica @id il nome del descrittore da eliminare.
Richiesta
Accetta intestazioni non è necessaria quando si eliminano descrittori.
curl -X DELETE \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors/ca921946fb5281cbdb8ba5e07087486ce531a1f2  \
  -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.
Per confermare che il descrittore è stato eliminato, potete eseguire una richiesta di ricerca rispetto al descrittore @id . La risposta restituisce lo stato HTTP 404 (non trovato) perché il descrittore è stato rimosso dall' Schema Registry.

Appendice

La sezione seguente fornisce informazioni aggiuntive sull'utilizzo dei descrittori nell' Schema Registry API.

Definizione dei descrittori

Le sezioni seguenti forniscono una panoramica dei tipi di descrittori disponibili, compresi i campi richiesti per la definizione di un descrittore di ciascun tipo.

Descrittore identità

Un descrittore di identità segnala che "sourceProperty" del "sourceSchema" è un Identity campo come descritto da Servizio identità Adobe Experience Platform.
{
  "@type": "xdm:descriptorIdentity",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/personalEmail/address",
  "xdm:namespace": "Email",
  "xdm:property": "xdm:code",
  "xdm:isPrimary": false
}

Proprietà
Descrizione
@type
Il tipo di descrittore da definire.
xdm:sourceSchema
URI $id dello schema in cui viene definito il descrittore.
xdm:sourceVersion
La versione principale dello schema di origine.
xdm:sourceProperty
Percorso della proprietà specifica che sarà l'identità. Il percorso deve iniziare con "/" e non terminare con uno. Non includere "proprietà" nel percorso (ad esempio, utilizzare "/personalEmail/address" invece di "/properties/personalEmail/properties/address")
xdm:namespace
Il valore id o code dello spazio dei nomi identità. È possibile trovare un elenco di spazi dei nomi utilizzando l' Identity Service API .
xdm:property
O xdm:id o xdm:code , a seconda dell' xdm:namespace utilizzo.
xdm:isPrimary
Un valore booleano facoltativo. Se true, indica il campo come identità principale. Gli schemi possono contenere una sola identità primaria.

descrittore di nome descrittivo

I descrittori di nomi descrittivi descrittivi consentono all'utente di modificare i title , description e meta:enum i valori dei campi dello schema della libreria di base. Particolarmente utile quando si utilizzano "eVar" e altri campi "generici" che si desidera etichettare come contenenti informazioni specifiche per la propria organizzazione. L’interfaccia utente può utilizzarli per visualizzare un nome più descrittivo o per mostrare solo i campi con un nome descrittivo.
{
  "@type": "xdm:alternateDisplayInfo",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/xdm:eventType",
  "xdm:title": {
    "en_us": "Event Type"
  },
  "xdm:description": {
    "en_us": "The type of experience event detected by the system."
  },
  "meta:enum": {
    "click": "Mouse Click",
    "addCart": "Add to Cart",
    "checkout": "Cart Checkout"
  }
}

Proprietà
Descrizione
@type
Il tipo di descrittore da definire.
xdm:sourceSchema
URI $id dello schema in cui viene definito il descrittore.
xdm:sourceVersion
La versione principale dello schema di origine.
xdm:sourceProperty
Percorso della proprietà specifica che sarà l'identità. Il percorso deve iniziare con "/" e non terminare con uno. Non includere "proprietà" nel percorso (ad esempio, utilizzare "/personalEmail/address" invece di "/properties/personalEmail/properties/address")
xdm:title
Il nuovo titolo che si desidera visualizzare per questo campo, scritto in Case titolo.
xdm:description
È possibile aggiungere una descrizione facoltativa insieme al titolo.
meta:enum
Se il campo indicato da xdm:sourceProperty è un campo stringa, meta:enum determina l'elenco dei valori consigliati per il campo nell' Experience Platform interfaccia utente. È importante notare che non meta:enum dichiara un'enumerazione né fornisce alcuna convalida di dati per il campo XDM.
Deve essere utilizzato solo per i campi XDM di base definiti dal Adobe . Se la proprietà source è un campo personalizzato definito dall'organizzazione, è necessario modificare la meta:enum proprietà del campo direttamente tramite una richiesta di PATCH.

Descrittore della relazione

I descrittori delle relazioni descrivono una relazione tra due schemi diversi, basata sulle proprietà descritte in sourceProperty e destinationProperty . Per ulteriori informazioni, vedere l'esercitazione sulla definizione di una relazione tra due schemi .
{
  "@type": "xdm:descriptorOneToOne",
  "xdm:sourceSchema":
    "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:destinationSchema": 
    "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:destinationVersion": 1,
  "xdm:destinationProperty": "/parentField/subField"
}

Proprietà
Descrizione
@type
Il tipo di descrittore da definire.
xdm:sourceSchema
URI $id dello schema in cui viene definito il descrittore.
xdm:sourceVersion
La versione principale dello schema di origine.
xdm:sourceProperty
Percorso del campo nello schema di origine in cui viene definita la relazione. Deve iniziare con un "/" e non terminare con uno. Non includere "proprietà" nel percorso (ad esempio, "/personalEmail/address" invece di "/properties/personalEmail/properties/address").
xdm:destinationSchema
URI $id dello schema di destinazione con cui il descrittore sta definendo una relazione.
xdm:destinationVersion
La versione principale dello schema di destinazione.
xdm:destinationProperty
Percorso facoltativo di un campo di destinazione nello schema di destinazione. Se questa proprietà viene omessa, il campo target viene ricavato da tutti i campi che contengono un descrittore di identità di riferimento corrispondente (vedere di seguito).

Descrittore identità di riferimento

I descrittori di identità di riferimento forniscono un contesto di riferimento all'identità primaria di un campo dello schema, consentendo di farvi riferimento dai campi di altri schemi. I campi devono essere già etichettati con un descrittore di identità prima di potervi applicare un descrittore di riferimento.
{
  "@type": "xdm:descriptorReferenceIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:identityNamespace": "Email"
}

Proprietà
Descrizione
@type
Il tipo di descrittore da definire.
xdm:sourceSchema
URI $id dello schema in cui viene definito il descrittore.
xdm:sourceVersion
La versione principale dello schema di origine.
xdm:sourceProperty
Percorso del campo nello schema di origine in cui viene definito il descrittore. Deve iniziare con un "/" e non terminare con uno. Non includere "proprietà" nel percorso (ad esempio, "/personalEmail/address" invece di "/properties/personalEmail/properties/address").
xdm:identityNamespace
Il codice dello spazio dei nomi dell'identità per la proprietà source.