Endpoint 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 relativi a 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 la sourceSchema a cui si applica. Una volta applicati, questi descrittori verranno applicati a tutti i set di dati creati utilizzando lo schema.

L'endpoint /descriptors nell'API Schema Registry consente di gestire i descrittori a livello di programmazione all'interno dell'applicazione dell'esperienza.

Introduzione

L'endpoint 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 descrittori

Potete elencare tutti i descrittori definiti dall'organizzazione effettuando una richiesta di GET a /tenant/descriptors.

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 Accept inviata nella richiesta. Tenere presente che l'endpoint /descriptors utilizza intestazioni Accept diverse da tutti gli altri endpoint nell'API Schema Registry.

IMPORTANTE

I descrittori richiedono intestazioni Accept univoche che sostituiscono xed con xdm e offrono anche un'opzione link univoca per i descrittori. Le intestazioni Accept corrette sono state incluse nelle chiamate di esempio riportate di seguito, ma prestate molta attenzione nell'assicurare che vengano utilizzate le intestazioni corrette quando lavorate con i descrittori.

Accept header 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
application/vnd.adobe.xdm-v2+json Questa intestazione Accept deve essere utilizzata per utilizzare le funzionalità di paging.

Risposta

La risposta include un array per ciascun tipo di descrittore con descrittori definiti. In altre parole, se non sono presenti descrittori di un determinato @type definito, il Registro di sistema non restituirà una matrice vuota per quel tipo di descrittore.

Quando si utilizza l'intestazione link Accept, 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} Il @id del descrittore che si desidera cercare.

Richiesta

La richiesta seguente recupera un descrittore per il valore @id. I descrittori non dispongono di una versione, pertanto nella richiesta di ricerca non è necessaria alcuna intestazione Accept.

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 dettagli @type e sourceSchema, nonché informazioni aggiuntive che variano a seconda del tipo di descrittore. La @id restituita 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

Potete creare un nuovo descrittore effettuando una richiesta di POST all'endpoint /tenant/descriptors.

IMPORTANTE

Schema Registry consente di definire diversi tipi di descrittori. Ogni tipo di descrittore richiede l'invio di campi specifici nel corpo della richiesta. Vedere l' appendice per un elenco completo dei descrittori e i campi necessari per definirli.

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 a Experience Platform di utilizzare l'indirizzo e-mail come identificatore per unire informazioni sull'utente.

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. @id è un campo di sola lettura assegnato da 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"
}

Aggiornare un descrittore

Potete aggiornare un descrittore inserendo il relativo @id nel percorso di una richiesta di PUT.

Formato API

PUT /tenant/descriptors/{DESCRIPTOR_ID}
Parametro Descrizione
{DESCRIPTOR_ID} Il @id del descrittore da aggiornare.

Richiesta

La richiesta riscrive essenzialmente 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.

IMPORTANTE

Come per la creazione di descrittori tramite richieste di POST, ogni tipo di descrittore richiede l'invio di campi specifici in payload di richieste di PUT. Vedere l' appendice per un elenco completo dei descrittori e i campi necessari per definirli.

L'esempio seguente aggiorna un descrittore di identità per fare riferimento a un xdm:sourceProperty diverso (mobile phone) e modifica il xdm:namespace in Phone.

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
      }'

Risposta

Una risposta corretta restituisce lo stato HTTP 201 (Creato) e la @id del descrittore aggiornato (che deve corrispondere alla @id inviata 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.

Eliminare un descrittore

Talvolta potrebbe essere necessario rimuovere un descrittore definito dall' Schema Registry. Questa operazione viene eseguita eseguendo una richiesta di DELETE che fa riferimento alla @id del descrittore che si desidera rimuovere.

Formato API

DELETE /tenant/descriptors/{DESCRIPTOR_ID}
Parametro Descrizione
{DESCRIPTOR_ID} Il @id del descrittore da eliminare.

Richiesta

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, è possibile eseguire una richiesta di ricerca rispetto al descrittore @id. La risposta restituisce lo stato HTTP 404 (non trovato) perché il descrittore è stato rimosso dalla directory Schema Registry.

Appendice

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

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" di "sourceSchema" è un campo Identity come descritto da Adobe Experience Platform Identity Service.

{
  "@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 dell'identità. È possibile trovare un elenco di spazi dei nomi utilizzando il percorso Identity Service API.
xdm:property xdm:id o xdm:code, a seconda della xdm:namespace utilizzata.
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 valori title, description e meta:enum 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'interfaccia di Experience Platform. È importante notare che meta:enum non 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 proprietà meta:enum del campo direttamente tramite una richiesta di PATCH alla risorsa padre del campo.

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 su 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. Per poter applicare un descrittore di riferimento, i campi devono già essere etichettati con un descrittore di identità.

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

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
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now