Endpoint Unions

Le unioni (o viste di unione) sono schemi generati dal sistema e di sola lettura che aggregano i campi di tutti gli schemi che condividono la stessa classe (XDM ExperienceEvent o XDM Individual Profile) e sono abilitati per Real-time Customer Profile.

Il presente documento illustra i concetti essenziali per l'utilizzo dei sindacati nell'API del Registro di sistema dello schema, incluse le chiamate di esempio per varie operazioni. Per informazioni più generali sui sindacati in XDM, vedere la sezione sui sindacati in nozioni di base della composizione dello schema.

Campi dello schema unione

Schema Registry include automaticamente tre campi chiave in uno schema unione: identityMap, timeSeriesEvents e segmentMembership.

Mappa identità

Un elemento identityMap dello schema unione è una rappresentazione delle identità note all'interno degli schemi di record associati all'unione. La mappa identità separa le identità in array diversi, chiave per namespace. Ogni identità elencata è essa stessa un oggetto contenente un valore id univoco. Per ulteriori informazioni, vedere la documentazione del servizio identità.

Eventi serie temporali

L'array timeSeriesEvents è un elenco di eventi delle serie temporali relativi agli schemi di record associati all'unione. Quando i dati del profilo vengono esportati nei set di dati, questa matrice viene inclusa per ciascun record. Questa funzione è utile per diversi casi di utilizzo, ad esempio per l'apprendimento automatico, in cui i modelli necessitano dell'intera cronologia del comportamento di un profilo oltre agli attributi del record.

Mappa appartenenza segmento

La mappa segmentMembership memorizza i risultati delle valutazioni dei segmenti. Quando i processi del segmento vengono eseguiti correttamente utilizzando l'API Segmentazione, la mappa viene aggiornata. segmentMembership memorizza inoltre tutti i segmenti di pubblico già valutati che vengono trasferiti in Piattaforma, consentendo l'integrazione con altre soluzioni come Adobe Audience Manager. Per ulteriori informazioni, consulta l'esercitazione sulla creazione di segmenti tramite API.

Recupera un elenco di unioni

Quando si imposta il tag union su uno schema, Schema Registry aggiunge automaticamente lo schema all'unione per la classe su cui si basa lo schema. Se non esiste alcuna unione per la classe in questione, viene creata automaticamente una nuova unione. La $id dell'unione è simile alla $id standard di altre risorse Schema Registry, con l'unica differenza aggiunta da due caratteri di sottolineatura e dalla parola "unione" (__union).

È possibile visualizzare un elenco di unioni disponibili effettuando una richiesta di GET all'endpoint /tenant/unions.

Formato API

GET /tenant/unions

Richiesta

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/unions \
  -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.xed-id+json'

Il formato della risposta dipende dall'intestazione Accept inviata nella richiesta. Le seguenti intestazioni Accept sono disponibili per l'elenco delle unioni:

Accept header Descrizione
application/vnd.adobe.xed-id+json Restituisce un breve riepilogo di ciascuna risorsa. Intestazione consigliata per elencare le risorse. (Limite: 300)
application/vnd.adobe.xed+json Restituisce la classe JSON completa per ogni risorsa, con $ref originale e allOf inclusi. (Limite: 300)

Risposta

Una risposta corretta restituisce lo stato HTTP 200 (OK) e un array results nel corpo della risposta. Se le unioni sono state definite, i dettagli di ciascuna unione vengono forniti come oggetti all'interno dell'array. Se non sono state definite unioni, lo stato HTTP 200 (OK) viene comunque restituito, ma l'array results sarà vuoto.

{
    "results": [
        {
            "title": "XDM Individual Profile",
            "$id": "https://ns.adobe.com/xdm/context/profile__union",
            "meta:altId": "_xdm.context.profile__union",
            "version": "1"
        },
        {
            "title": "Property",
            "$id": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590__union",
            "meta:altId": "_{TENANT_ID}.classes.19e1d8b5098a7a76e2c10a81cbc99590__union",
            "version": "1"
        }
    ]
}

Cerca un'unione

Potete visualizzare un'unione specifica eseguendo una richiesta di GET che include $id e, a seconda dell'intestazione Accetto, alcuni o tutti i dettagli dell'unione.

NOTA

Le ricerche dell'unione sono disponibili utilizzando l'endpoint /unions e /schemas per consentirne l'utilizzo nelle esportazioni Profile in un dataset.

Formato API

GET /tenant/unions/{UNION_ID}
GET /tenant/schemas/{UNION_ID}
Parametro Descrizione
{UNION_ID} L'URI $id con codifica URL dell'unione da cercare. Gli URI per gli schemi di unione vengono aggiunti con "__union".

Richiesta

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/unions/https%3A%2F%2Fns.adobe.com%2Fxdm%2Fcontext%2Fprofile__union \
  -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.xed+json; version=1'

Le richieste di ricerca unionali richiedono l'inclusione di un elemento version nell'intestazione Accetto.

Le seguenti intestazioni Accetta sono disponibili per le ricerche dello schema unione:

Accetta Descrizione
application/vnd.adobe.xed+json; version= Non elaborato con $ref e allOf. Include titoli e descrizioni.
application/vnd.adobe.xed-full+json; version= $ref e allOf risolto. Include titoli e descrizioni.

Risposta

Una risposta corretta restituisce la visualizzazione unione di tutti gli schemi che implementano la classe di cui $id è stato fornito nel percorso della richiesta.

Il formato della risposta dipende dall’intestazione Accetta inviata nella richiesta. Provate con diverse intestazioni Accetta per confrontare le risposte e determinare quale intestazione è più adatta all’uso da parte dell’utente.

{
    "type": "object",
    "description": "Union view of all schemas that extend https://ns.adobe.com/xdm/context/profile",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
        },
        {
            "$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/477bb01d7125b015b4feba7bccc2e599"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
        }
    ],
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/profile",
        "https://ns.adobe.com/xdm/data/record",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/common/extensible",
        "https://ns.adobe.com/xdm/common/auditable",
        "https://ns.adobe.com/xdm/context/profile-person-details",
        "https://ns.adobe.com/{TENANT_ID}/mixins/477bb01d7125b015b4feba7bccc2e599",
        "https://ns.adobe.com/xdm/context/profile-personal-details"
    ],
    "title": "Union object for https://ns.adobe.com/xdm/context/profile",
    "$id": "https://ns.adobe.com/xdm/context/profile__union",
    "meta:containerId": "tenant",
    "meta:class": "https://ns.adobe.com/xdm/context/profile",
    "meta:altId": "_xdm.context.profile__union",
    "version": "1.0",
    "meta:resourceType": "unions",
    "meta:registryMetadata": {}
}

Abilita uno schema per l'appartenenza all'unione

Affinché uno schema possa essere incluso nell'unione per la relativa classe, è necessario aggiungere un tag union all'attributo meta:immutableTags dello schema. A tal fine, è possibile effettuare una richiesta di PATCH per aggiungere allo schema in questione un array meta:immutableTags con un singolo valore di stringa union. Per un esempio dettagliato, vedere la guida dell'endpoint degli schemi.

Elenca gli schemi in un'unione

Per vedere quali schemi fanno parte di un'unione specifica, potete eseguire una richiesta di GET all'endpoint /tenant/schemas. Utilizzando il parametro di query property, potete configurare la risposta solo per gli schemi di restituzione contenenti un campo meta:immutableTags e un meta:class uguale alla classe a cui state accedendo.

Formato API

GET /tenant/schemas?property=meta:immutableTags==union&property=meta:class=={CLASS_ID}
Parametro Descrizione
{CLASS_ID} Il $id della classe di cui si desidera elencare gli schemi abilitati per l'unione.

Richiesta

La richiesta seguente recupera un elenco di tutti gli schemi che fanno parte dell'unione per la classe XDM Individual Profile.

curl -X GET \
  'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas?property=meta:immutableTags==union&property=meta:class==https://ns.adobe.com/xdm/context/profile' \
  -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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Il formato della risposta dipende dall'intestazione Accept inviata nella richiesta. Per elencare gli schemi sono disponibili le seguenti intestazioni Accept:

Accept header Descrizione
application/vnd.adobe.xed-id+json Restituisce un breve riepilogo di ciascuna risorsa. Intestazione consigliata per elencare le risorse. (Limite: 300)
application/vnd.adobe.xed+json Restituisce lo schema JSON completo per ogni risorsa, con $ref originale e allOf inclusi. (Limite: 300)

Risposta

Una risposta corretta restituisce un elenco filtrato di schemi, contenente solo quelli appartenenti alla classe specificata che sono stati abilitati per l'appartenenza all'unione. Tenere presente che quando si utilizzano più parametri di query, viene considerata una relazione AND.

{
    "results": [
        {
            "title": "Schema 1",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/142afb78d8b368a5ba97a6cc8fc7e033",
            "meta:altId": "_{TENANT_ID}.schemas.142afb78d8b368a5ba97a6cc8fc7e033",
            "version": "1.2"
        },
        {
            "title": "Schema 2",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/e7297a6ddfc7812ab3a7b504a1ab98da",
            "meta:altId": "_{TENANT_ID}.schemas.e7297a6ddfc7812ab3a7b504a1ab98da",
            "version": "1.5"
        },
        {
            "title": "Schema 3",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/50f960bb810e99a21737254866a477bf",
            "meta:altId": "_{TENANT_ID}.schemas.50f960bb810e99a21737254866a477bf",
            "version": "1.2"
        },
        {
            "title": "Schema 4",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/a39655ca8ea3d5c1f36a463b45fccca8",
            "meta:altId": "_{TENANT_ID}.schemas.a39655ca8ea3d5c1f36a463b45fccca8",
            "version": "1.1"
        },
        {
            "title": "Schema 5",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/c063fac45c6d6285ef33b0e2af09f633",
            "meta:altId": "_{TENANT_ID}.schemas.c063fac45c6d6285ef33b0e2af09f633",
            "version": "1.2"
        },
        {
            "title": "Schema 6",
            "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/dfebb19b93827b70bbad006137812537",
            "meta:altId": "_{TENANT_ID}.schemas.dfebb19b93827b70bbad006137812537",
            "version": "1.7"
        }
    ],
    "_links": {
        "global_schemas": {
            "href": "https://platform.adobe.io/data/foundation/schemaregistry/global/schemas?property=meta:immutableTags==union&property=meta:class==https://ns.adobe.com/xdm/context/profile"
        }
    }
}

In questa pagina