Endpoint descrittori

Gli schemi definiscono una visualizzazione statica delle entità dati, ma non forniscono dettagli specifici sul modo in cui i dati basati su questi schemi (ad esempio, i set di dati) possono essere correlati tra loro. Adobe Experience Platform ti consente di descrivere queste relazioni e altri metadati interpretativi su uno schema utilizzando i descrittori.

I descrittori di schema sono metadati a livello di tenant, il che significa che sono univoci per la tua organizzazione IMS e che tutte le operazioni dei descrittori hanno luogo nel contenitore tenant.

A ogni schema può essere applicata una o più entità descrittrici di schema. Ogni entità descrittrice dello schema include un descrittore @type e sourceSchema a cui si applica. Una volta applicati, questi descrittori verranno applicati a tutti i set di dati creati utilizzando lo schema.

La /descriptors punto finale Schema Registry L’API ti consente di gestire in modo programmatico i descrittori 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 descrittori

Puoi elencare tutti i descrittori definiti dalla tua 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xdm-link+json'

Il formato della risposta dipende dal Accept intestazione inviata nella richiesta. Tieni presente che /descriptors utilizzi endpoint Accept intestazioni diverse da tutti gli altri endpoint nel Schema Registry API.

IMPORTANTE

I descrittori richiedono un valore univoco Accept intestazioni che sostituiscono xed con xdme offre anche link opzione univoca per i descrittori. Il Accept le intestazioni sono state incluse nelle chiamate di esempio riportate di seguito, ma presta molta attenzione a garantire che vengano utilizzate le intestazioni corrette quando lavori con i descrittori.

Accept header Descrizione
application/vnd.adobe.xdm-id+json Restituisce una matrice di ID descrittori
application/vnd.adobe.xdm-link+json Restituisce una matrice di percorsi API descrittivi
application/vnd.adobe.xdm+json Restituisce una matrice di oggetti descrittivi espansi
application/vnd.adobe.xdm-v2+json Questo Accept Per utilizzare le funzionalità di paging, è necessario utilizzare l'intestazione .

Risposta

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

Quando utilizzi link Accept intestazione, 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

Se desideri visualizzare i dettagli di un descrittore specifico, puoi cercare (GET) un singolo descrittore utilizzando il relativo @id.

Formato API

GET /tenant/descriptors/{DESCRIPTOR_ID}
Parametro Descrizione
{DESCRIPTOR_ID} La @id del descrittore che si desidera cercare.

Richiesta

La seguente richiesta recupera un descrittore dalla relativa @id valore. I descrittori non dispongono di versioni, pertanto non sono disponibili Accept L’intestazione è obbligatoria 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

Una risposta corretta restituisce i dettagli del descrittore, incluso il relativo @type e sourceSchema, nonché informazioni aggiuntive che variano a seconda del tipo di descrittore. Il restituito @id deve corrispondere al descrittore @id 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

Puoi creare un nuovo descrittore effettuando una richiesta POST al /tenant/descriptors punto finale.

IMPORTANTE

La Schema Registry consente di definire diversi tipi di descrittori. Ogni tipo di descrittore richiede che i propri campi specifici siano inviati nel corpo della richiesta. Consulta la sezione appendice per un elenco completo dei descrittori e dei campi necessari per definirli.

Formato API

POST /tenant/descriptors

Richiesta

La richiesta seguente definisce un descrittore di identità su un campo "Indirizzo e-mail" in uno schema di esempio. Questo è Experience Platform utilizzare l’indirizzo e-mail come identificatore per unire le 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 il relativo @id. La @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

È possibile aggiornare un descrittore includendo il relativo @id nel percorso di una richiesta PUT.

Formato API

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

Richiesta

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

IMPORTANTE

Come per la creazione di descrittori utilizzando le richieste di POST, ogni tipo di descrittore richiede l’invio di campi specifici nei payload di richiesta PUT. Consulta la sezione appendice per un elenco completo dei descrittori e dei campi necessari per definirli.

Nell'esempio seguente viene aggiornato un descrittore di identità per fare riferimento a un diverso xdm:sourceProperty (mobile phone) e modifica il xdm:namespace a 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 il @id del descrittore aggiornato (che deve corrispondere al @id inviato nella richiesta).

{
    "@id": "f3a1dfa38a4871cf4442a33074c1f9406a593407"
}

Esecuzione di un richiesta di ricerca (GET) per visualizzare il descrittore, i campi sono stati aggiornati per riflettere le modifiche inviate nella richiesta di PUT.

Eliminare un descrittore

A volte può essere necessario rimuovere un descrittore definito dalla Schema Registry. A questo scopo, invia una richiesta DELETE che fa riferimento al @id del descrittore che si desidera rimuovere.

Formato API

DELETE /tenant/descriptors/{DESCRIPTOR_ID}
Parametro Descrizione
{DESCRIPTOR_ID} La @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, puoi eseguire un richiesta di ricerca contro il descrittore @id. La risposta restituisce lo stato HTTP 404 (Non trovato) perché il descrittore è stato rimosso dalla Schema Registry.

Appendice

La sezione seguente fornisce informazioni aggiuntive sulle operazioni con i descrittori nel Schema Registry API.

Definizione dei descrittori

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

Descrittore di identità

Un descrittore di identità segnala che "sourceProperty" del "sourceSchema" è un Identity campo descritto da Servizio Adobe Experience Platform Identity.

{
  "@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 La $id URI dello schema in cui viene definito il descrittore.
xdm:sourceVersion Versione principale dello schema di origine.
xdm:sourceProperty Percorso della proprietà specifica che sarà l'identità. Il percorso deve iniziare con un "/" e non terminare con uno. Non includere "proprietà" nel percorso (ad esempio, usa "/personalEmail/address" invece di "/properties/personalEmail/properties/address")
xdm:namespace La id o code valore dello spazio dei nomi identità. È possibile trovare un elenco di spazi dei nomi utilizzando Identity Service API.
xdm:property O xdm:id o xdm:code, a seconda del xdm:namespace utilizzato.
xdm:isPrimary Un valore booleano facoltativo. Se true, indica il campo come identità principale. Gli schemi possono contenere una sola identità principale.

descrittore di nome descrittivo

I descrittori di nomi descrittivi consentono a un utente di modificare title, descriptione meta:enum valori 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 della propria organizzazione. L’interfaccia utente può usarli 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"
  }
}
Proprietà Descrizione
@type Il tipo di descrittore da definire.
xdm:sourceSchema La $id URI dello schema in cui viene definito il descrittore.
xdm:sourceVersion Versione principale dello schema di origine.
xdm:sourceProperty Percorso della proprietà specifica che sarà l'identità. Il percorso deve iniziare con un "/" e non terminare con uno. Non includere "proprietà" nel percorso (ad esempio, usa "/personalEmail/address" invece di "/properties/personalEmail/properties/address")
xdm:title Nuovo titolo da 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 di valori suggeriti per il campo nel Experience Platform Interfaccia utente. È 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 da Adobe. Se la proprietà sorgente è un campo personalizzato definito dall'organizzazione, è invece necessario modificare il campo meta:enum direttamente tramite una richiesta di PATCH alla risorsa principale del campo.

Descrittore di relazione

I descrittori di relazione descrivono una relazione tra due schemi diversi, basata sulle proprietà descritte in sourceProperty e destinationProperty. Guarda l’esercitazione su definizione di una relazione tra due schemi per ulteriori informazioni.

{
  "@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 La $id URI dello schema in cui viene definito il descrittore.
xdm:sourceVersion 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 La $id URI dello schema di destinazione con cui questo descrittore sta definendo una relazione.
xdm:destinationVersion 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 di destinazione viene dedotto da qualsiasi campo contenente un descrittore di identità di riferimento corrispondente (vedere di seguito).

Descrittore di identità di riferimento

I descrittori di identità di riferimento forniscono un contesto di riferimento all’identità principale di un campo di schema, consentendo di farvi riferimento da campi di altri schemi. I campi devono essere già etichettati con un descrittore di identità prima di poter essere applicati a 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 La $id URI dello schema in cui viene definito il descrittore.
xdm:sourceVersion 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 Codice dello spazio dei nomi identità per la proprietà sorgente.

In questa pagina