Endpoint "descriptors"

Gli schemi definiscono la struttura delle entità dati, ma non specificano la correlazione tra i set di dati creati da questi schemi. In Adobe Experience Platform, puoi utilizzare i descrittori per descrivere queste relazioni e aggiungere metadati interpretativi a uno schema.

I descrittori sono oggetti di metadati a livello di tenant applicati agli schemi in Adobe Experience Platform. Definiscono relazioni strutturali, chiavi e campi comportamentali (come marche temporali o controllo delle versioni) che influenzano il modo in cui i dati vengono convalidati, uniti o interpretati a valle.

Uno schema può avere uno o più descrittori. Ogni descrittore definisce un @type e il sourceSchema a cui si applica. Il descrittore si applica automaticamente a tutti i set di dati creati da tale schema.

In Adobe Experience Platform, un descrittore è un metadati che aggiunge regole comportamentali o un significato strutturale a uno schema.
Esistono diversi tipi di descrittori, tra cui:

L'endpoint /descriptors nell'API Schema Registry consente di gestire in modo programmatico i descrittori 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.

Oltre ai descrittori standard, Schema Registry supporta i tipi di descrittori per gli schemi basati su modelli, ad esempio chiave primaria, versione e timestamp. Questi applicano l’univocità, controllano il controllo delle versioni e definiscono i campi di serie temporali a livello di schema. Se non conosci gli schemi basati su modelli, controlla la panoramica di Data Mirror e la documentazione tecnica sugli schemi basati su modelli prima di continuare.

Recuperare un elenco di descrittori list

È possibile elencare tutti i descrittori definiti dall'organizzazione effettuando una richiesta 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: {ORG_ID}' \
  -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. L'endpoint /descriptors utilizza intestazioni Accept diverse da tutti gli altri endpoint nell'API Schema Registry.

Risposta

La risposta include un array per ogni tipo di descrittore che ha definito i descrittori. 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 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 lookup

Per visualizzare i dettagli di un descrittore specifico, invia una richiesta GET utilizzando il relativo @id.

Formato API

GET /tenant/descriptors/{DESCRIPTOR_ID}

Richiesta

La richiesta seguente recupera un descrittore dal suo valore @id. I descrittori non dispongono di versioni, pertanto non è richiesta alcuna intestazione Accept nella richiesta di ricerca.

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

In caso di esito positivo, la risposta restituisce i dettagli del descrittore, inclusi @type e sourceSchema, nonché ulteriori informazioni 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": "{ORG_ID}",
  "createdClient": "{CREATED_CLIENT}",
  "updatedUser": "{UPDATED_USER}",
  "created": 1548899346989,
  "updated": 1548899346989,
  "meta:containerId": "tenant",
  "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Creare un descrittore create

È possibile creare un nuovo descrittore effettuando una richiesta POST all'endpoint /tenant/descriptors.

Formato API

POST /tenant/descriptors

Richiesta

La seguente richiesta definisce un descrittore di identità in un campo "indirizzo e-mail" in uno schema di esempio. Questo comunica a Experience Platform di utilizzare l'indirizzo e-mail come identificatore per unire le informazioni sulla persona.

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

In caso di esito positivo, la risposta 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 put

Per aggiornare un descrittore, devi includere @id nel percorso di una richiesta PUT.

Formato API

PUT /tenant/descriptors/{DESCRIPTOR_ID}

Richiesta

Questa 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 della richiesta per aggiornare (PUT) un descrittore è lo stesso del payload per creare (POST) un descrittore dello stesso tipo.

Nell'esempio seguente viene aggiornato un descrittore di identità in modo che faccia riferimento a un altro xdm:sourceProperty (mobile phone) e viene modificato 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: {ORG_ID}' \
  -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

In caso di esito positivo, la risposta restituisce lo stato HTTP 201 (Creato) e il @id del descrittore aggiornato (che deve corrispondere al @id inviato nella richiesta).

{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

L'esecuzione di una richiesta di ricerca (GET) per visualizzare il descrittore indica che i campi sono stati aggiornati per riflettere le modifiche inviate nella richiesta PUT.

Eliminare un descrittore delete

Talvolta potrebbe essere necessario rimuovere un descrittore definito da Schema Registry. A tale scopo, effettuare una richiesta DELETE facendo riferimento a @id del descrittore che si desidera rimuovere.

Formato API

DELETE /tenant/descriptors/{DESCRIPTOR_ID}

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: {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.

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 da Schema Registry.

Appendice appendix

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

Definizione dei descrittori defining-descriptors

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

Descrittore di identità identity-descriptor

Un descrittore di identità segnala che "sourceProperty" di "sourceSchema" è un campo Identity come descritto da 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
}

Descrittore del nome intuitivo friendly-name

I descrittori di nomi descrittivi consentono a un utente di modificare i valori title, description e meta:enum dei campi dello schema della libreria principale. Particolarmente utile quando si lavora con "eVar" e altri campi "generici" che si desidera etichettare come contenenti informazioni specifiche dell’organizzazione. L’interfaccia utente può utilizzarli per mostrare 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"
  },
  "xdm:excludeMetaEnum": {
    "web.formFilledOut": "Web Form Filled Out",
    "media.ping": "Media ping"
  }
}

Descrittore di relazione relationship-descriptor

I descrittori di relazione descrivono una relazione tra due schemi diversi, basata sulle proprietà descritte in xdm:sourceProperty e xdm:destinationProperty. Per ulteriori informazioni, vedere il tutorial su definizione di una relazione tra due schemi.

Utilizzare queste proprietà per dichiarare la relazione tra un campo di origine (chiave esterna) e un campo di destinazione (chiave primaria o chiave candidata).

L’API supporta due modelli:

Relazione uno-a-uno (schemi standard)

Usare questa opzione quando si mantengono integrazioni dello schema standard esistenti che si basano già su xdm:descriptorOneToOne.

{
  "@type": "xdm:descriptorOneToOne",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:destinationVersion": 1,
  "xdm:destinationProperty": "/parentField/subField"
}

Nella tabella seguente sono descritti i campi necessari per definire un descrittore di relazione uno-a-uno.

Relazione generale (schemi basati su modelli e consigliati per i nuovi progetti)

Utilizza questo descrittore per tutte le nuove implementazioni e per gli schemi basati su modelli. Consente di definire la cardinalità della relazione (ad esempio uno a uno o molti a uno), specificare i nomi delle relazioni e collegarsi a un campo di destinazione che non sia la chiave primaria (chiave non primaria).

Gli esempi seguenti mostrano come definire un descrittore di relazione generale.

Esempio minimo:

Questo esempio minimo include solo i campi obbligatori per definire una relazione molti-a-uno tra due schemi.

{
  "@type": "xdm:descriptorRelationship",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceProperty": "/customer_ref",
  "xdm:sourceVersion": 1,
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:cardinality": "M:1"
}

Esempio con tutti i campi facoltativi:

Questo esempio include tutti i campi facoltativi, ad esempio i nomi delle relazioni, i titoli visualizzati e un campo di destinazione esplicito non di chiave primaria.

{
  "@type": "xdm:descriptorRelationship",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SOURCE_SCHEMA_ID}",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/customer_ref",
  "xdm:destinationSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{DEST_SCHEMA_ID}",
  "xdm:destinationProperty": "/customer_id",
  "xdm:sourceToDestinationName": "CampaignToCustomer",
  "xdm:destinationToSourceName": "CustomerToCampaign",
  "xdm:sourceToDestinationTitle": "Customer campaigns",
  "xdm:destinationToSourceTitle": "Campaign customers",
  "xdm:cardinality": "M:1"
}

Scelta di un descrittore di relazione

Per decidere quale descrittore di relazione applicare, utilizza le seguenti linee guida:

Confronto delle funzionalità

Nella tabella seguente vengono confrontate le funzionalità dei due tipi di descrittori:

Vincoli e convalida

Segui questi requisiti e raccomandazioni durante la definizione di un descrittore di relazione generale:

Descrittore della chiave primaria primary-key-descriptor

Il descrittore di chiave primaria (xdm:descriptorPrimaryKey) applica vincoli di univocità e non Null a uno o più campi di uno schema.

{
  "@type": "xdm:descriptorPrimaryKey",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": ["/orderId", "/orderLineId"]
}

Descrittore versione version-descriptor

Il descrittore di versione (xdm:descriptorVersion) designa un campo per rilevare e impedire conflitti da eventi di modifica fuori ordine.

{
  "@type": "xdm:descriptorVersion",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": "/versionNumber"
}

Descrittore marca temporale timestamp-descriptor

Il descrittore timestamp (xdm:descriptorTimestamp) indica un campo data-ora come timestamp per gli schemi con "meta:behaviorType": "time-series".

{
  "@type": "xdm:descriptorTimestamp",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
  "xdm:sourceProperty": "/eventTime"
}

Descrittore di relazione B2B B2B-relationship-descriptor

Real-Time CDP B2B edition introduce un modo alternativo di definire le relazioni tra schemi, che consente di creare relazioni molti-a-uno. Questa nuova relazione deve avere il tipo @type: xdm:descriptorRelationship e il payload deve includere più campi rispetto alla relazione @type: xdm:descriptorOneToOne. Per ulteriori informazioni, vedere il tutorial su definizione di una relazione di schema per B2B edition.

{
   "@type": "xdm:descriptorRelationship",
   "xdm:sourceSchema" : "https://ns.adobe.com/{TENANT_ID}/schemas/9f2b2f225ac642570a110d8fd70800ac0c0573d52974fa9a",
   "xdm:sourceVersion" : 1,
   "xdm:sourceProperty" : "/person-ref",
   "xdm:destinationSchema" : "https://ns.adobe.com/{TENANT_ID/schemas/628427680e6b09f1f5a8f63ba302ee5ce12afba8de31acd7",
   "xdm:destinationVersion" : 1,
   "xdm:destinationProperty": "/personId",
   "xdm:destinationNamespace" : "People",
   "xdm:destinationToSourceTitle" : "Opportunity Roles",
   "xdm:sourceToDestinationTitle" : "People",
   "xdm:cardinality": "M:1"
}

Descrittore dell’identità di riferimento

I descrittori di identità di riferimento forniscono un contesto di riferimento all’identità primaria di un campo schema, consentendo che i campi di altri schemi vi facciano riferimento. Lo schema di riferimento deve avere già un campo di identità primaria definito prima che altri schemi possano farvi riferimento tramite questo descrittore.

{
  "@type": "xdm:descriptorReferenceIdentity",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/78bab6346b9c5102b60591e15e75d254",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/parentField/subField",
  "xdm:identityNamespace": "Email"
}

Descrittore di campo obsoleto

È possibile rendere obsoleto un campo all'interno di una risorsa XDM personalizzata aggiungendo un attributo meta:status impostato su deprecated al campo in questione. Tuttavia, se desideri rendere obsoleti i campi forniti dalle risorse XDM standard negli schemi, puoi assegnare allo schema in questione un descrittore di campo obsoleto per ottenere lo stesso effetto. Utilizzando l'intestazione Acceptcorretta, puoi visualizzare quali campi standard sono obsoleti per uno schema quando lo cerchi nell'API.

{
  "@type": "xdm:descriptorDeprecated",
  "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/c65ddf08cf2d4a2fe94bd06113bf4bc4c855e12a936410d5",
  "xdm:sourceVersion": 1,
  "xdm:sourceProperty": "/faxPhone"
}