Endpoint Unions

Le unioni (o visualizzazioni 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.

Questo documento descrive i concetti essenziali per lavorare con i 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, consulta la sezione sui sindacati in nozioni di base sulla composizione dello schema.

Campi dello schema unione

Schema Registry include automaticamente tre campi chiave all'interno di uno schema di unione: identityMap, timeSeriesEvents e segmentMembership.

Mappa identità

L’ identityMap di uno schema di unione è una rappresentazione delle identità note all’interno degli schemi di record associati all’unione. La mappa identità separa le identità in diversi array collegati dallo spazio dei nomi. Ogni identità elencata è essa stessa un oggetto contenente un valore id univoco. Per ulteriori informazioni, consulta la documentazione del servizio Identity .

Eventi della serie temporale

L'array timeSeriesEvents è un elenco di eventi serie temporali relativi agli schemi di record associati all'unione. Quando i dati di profilo vengono esportati nei set di dati, questa matrice viene inclusa per ogni record. Questo è utile per vari casi d’uso, ad esempio per l’apprendimento automatico, in cui i modelli necessitano dell’intera cronologia dei comportamenti di un profilo oltre agli attributi del record.

Mappa di appartenenza al segmento

La mappa segmentMembership memorizza i risultati delle valutazioni dei segmenti. Quando i processi di segmento vengono eseguiti correttamente utilizzando l’ API di segmentazione, la mappa viene aggiornata. segmentMembership memorizza anche tutti i segmenti di pubblico valutati in precedenza acquisiti in Platform, consentendo l’integrazione con altre soluzioni come Adobe Audience Manager. Per ulteriori informazioni, consulta l’esercitazione su creazione di segmenti utilizzando le API .

Recupera un elenco di unioni

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

È possibile visualizzare un elenco dei sindacati 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 dei sindacati:

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

Risposta

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

{
    "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"
        }
    ]
}

Cercare un sindacato

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

NOTA

Le ricerche nell’Unione sono disponibili utilizzando l’endpoint /unions e /schemas per abilitarli all’uso in Profile esportazioni in un set di dati.

Formato API

GET /tenant/unions/{UNION_ID}
GET /tenant/schemas/{UNION_ID}
Parametro Descrizione
{UNION_ID} 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 dell’Unione richiedono che un elemento version sia incluso nell’intestazione Accept.

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

Accept Descrizione
application/vnd.adobe.xed+json; version=1 Non elaborato con $ref e allOf. Include titoli e descrizioni.
application/vnd.adobe.xed-full+json; version=1 $ref attributi e allOf risolti. 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 Accept inviata nella richiesta. Prova a utilizzare diverse intestazioni Accept per confrontare le risposte e determinare quale intestazione è migliore per il tuo caso d’uso.

{
    "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": {}
}

Abilitare 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. È possibile eseguire questa operazione effettuando una richiesta di PATCH per aggiungere un array meta:immutableTags con un singolo valore di stringa union allo schema in questione. Per un esempio dettagliato, consulta la guida all’endpoint degli schemi .

Elencare schemi in un’unione

Per vedere quali schemi fanno parte di un’unione specifica, puoi eseguire una richiesta di GET all’endpoint /tenant/schemas . Utilizzando il parametro di query property, puoi configurare la risposta per restituire solo gli schemi contenenti un campo meta:immutableTags e un meta:class uguale alla classe a cui stai 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. Le seguenti intestazioni Accept sono disponibili per elencare gli schemi:

Accept header Descrizione
application/vnd.adobe.xed-id+json Restituisce un breve riepilogo di ciascuna risorsa. Intestazione consigliata per l’elenco delle risorse. (Limite: 300)
application/vnd.adobe.xed+json Restituisce lo schema JSON completo per ogni risorsa, con i valori originali $ref 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, si presume 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