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 sulle unioni in XDM, consultate la sezione sui sindacati nelle nozioni di base della composizionedello schema.

Campi dello schema unione

Include Schema Registry automaticamente tre campi chiave in uno schema unione: identityMap, timeSeriesEventse segmentMembership.

Mappa identità

Uno schema unione identityMap è 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 id valore univoco. See the Identity Service documentation for more information.

Eventi serie temporali

L' timeSeriesEvents array è 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 segmentMembership mappa memorizza i risultati delle valutazioni dei segmenti. Quando i processi del segmento vengono eseguiti correttamente tramite 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 .

Recupero di un elenco di unioni

Quando si imposta il union tag su uno schema, lo schema viene aggiunto Schema Registry automaticamente 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 struttura dell'Unione è simile allo standard $id delle altre Schema Registry risorse, con l'unica differenza che viene aggiunta da due caratteri di sottolineatura e dalla parola "unione" (__union).

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

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’ Accept intestazione inviata nella richiesta. Le seguenti Accept intestazioni 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 l'originale $ref e allOf l'inclusione. (Limite: 300)

Risposta

Una risposta corretta restituisce lo stato HTTP 200 (OK) e un results array 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 la results matrice 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'unione

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

Nota

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

Formato API

GET /tenant/unions/{UNION_ID}
GET /tenant/schemas/{UNION_ID}
Parametro Descrizione
{UNION_ID} L’ $id URI URL codificato 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 unioni richiedono che un oggetto version sia incluso 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 è stata fornita 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 a un'unione

Affinché uno schema possa essere incluso nell'unione per la relativa classe, è necessario aggiungere un union tag all' meta:immutableTags attributo dello schema. È possibile eseguire questa operazione eseguendo una richiesta di PATCH per aggiungere un meta:immutableTags array con un singolo valore di stringa union allo schema in questione. Per un esempio dettagliato, consultate la guida all'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' /tenant/schemas endpoint. Utilizzando il parametro property query, potete configurare la risposta solo per gli schemi di restituzione contenenti un meta:immutableTags campo e un meta:class uguale alla classe a cui si accede tramite unione.

Formato API

GET /tenant/schemas?property=meta:immutableTags==union&property=meta:class=={CLASS_ID}
Parametro Descrizione
{CLASS_ID} L'elemento $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 XDM Individual Profile classe.

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’ Accept intestazione inviata nella richiesta. Le seguenti Accept intestazioni 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 elencare le risorse. (Limite: 300)
application/vnd.adobe.xed+json Restituisce lo schema JSON completo per ciascuna risorsa, con originale $ref e allOf incluso. (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