Show Menu
ARGOMENTI×

Configurare un set di dati per il servizio Profilo e identità utilizzando le API

Questa esercitazione descrive il processo di attivazione di un dataset da utilizzare in Real-time Customer Profile and Identity Service, suddiviso nei seguenti passaggi:
  1. Abilita un set di dati da utilizzare nel profilo cliente in tempo reale, utilizzando una delle due opzioni seguenti:

Introduzione

Questa esercitazione richiede una buona conoscenza dei vari servizi Adobe Experience Platform coinvolti nella gestione dei set di dati abilitati per i profili. Prima di iniziare questa esercitazione, consulta la documentazione relativa ai seguenti servizi della piattaforma:
  • Profilo cliente in tempo reale: Fornisce un profilo di consumo unificato e in tempo reale basato su dati aggregati provenienti da più origini.
  • Servizio identità: Abilita il profilo cliente in tempo reale collegando identità da origini dati diverse che vengono caricate nella piattaforma.
  • Servizio catalogo: API RESTful che consente di creare set di dati e configurarli per il profilo cliente e il servizio identità in tempo reale.
  • Experience Data Model (XDM) : Il framework standardizzato tramite il quale la piattaforma organizza i dati sull'esperienza cliente.
Le sezioni seguenti forniscono informazioni aggiuntive che sarà necessario conoscere per effettuare correttamente chiamate alle API della piattaforma.

Lettura di chiamate API di esempio

Questa esercitazione fornisce esempi di chiamate API per dimostrare come formattare le richieste. Questi includono percorsi, intestazioni richieste e payload di richieste formattati correttamente. Viene inoltre fornito un JSON di esempio restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, consulta la sezione come leggere le chiamate API di esempio nella guida alla risoluzione dei problemi della piattaforma Experience.

Raccogli valori per le intestazioni richieste

Per effettuare chiamate alle API della piattaforma, dovete prima completare l'esercitazione di autenticazione. Completando l'esercitazione sull'autenticazione, vengono forniti i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di Experience Platform, come illustrato di seguito:
  • Autorizzazione: Portatore {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un'intestazione aggiuntiva:
  • Content-Type: application/json
Tutte le risorse in Experience Platform sono isolate in sandbox virtuali specifiche. Tutte le richieste alle API della piattaforma richiedono un'intestazione che specifica il nome della sandbox in cui avrà luogo l'operazione. Per ulteriori informazioni sulle sandbox in Piattaforma, consultate la documentazione sulla panoramica della sandbox.
  • x-sandbox-name: {SANDBOX_NAME}

Crea un set di dati abilitato per Profilo e Identità

Puoi abilitare un set di dati per il profilo cliente e il servizio identità in tempo reale immediatamente dopo la creazione o in qualsiasi momento dopo la creazione del set di dati. Se si desidera abilitare un dataset già creato, seguire i passaggi per configurare un dataset esistente trovato più avanti in questo documento. Per creare un nuovo set di dati, è necessario conoscere l'ID di uno schema XDM esistente abilitato per il profilo cliente in tempo reale. Per informazioni su come ricercare o creare uno schema abilitato per il profilo, vedere l'esercitazione sulla creazione di uno schema tramite l'API del Registro di sistema dello schema. La seguente chiamata all'API Catalog abilita un set di dati per Profile and Identity Service.
Formato API
POST /dataSets

Richiesta
Includendo unifiedProfile e unifiedIdentity sotto tags nel corpo della richiesta, il set di dati sarà attivato immediatamente rispettivamente per Profile e Identity Service. I valori di questi tag devono essere una matrice contenente la stringa "enabled:true" .
curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Content-Type: application/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}' \
  -d '{
    "fileDescription" : {
    "persisted": true,
        "containerFormat": "parquet",
        "format": "parquet"
    },
    "fields":[],
    "schemaRef" : {
        "id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
        "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
    },
    "tags" : {
       "unifiedProfile": ["enabled:true"],
       "unifiedIdentity": ["enabled:true"]
    }
  }'

Proprietà
Descrizione
schemaRef.id
ID dello schema abilitato per il profilo su cui verrà basato il dataset.
{TENANT_ID}
Lo spazio dei nomi all'interno del Registro di sistema dello schema che contiene le risorse appartenenti all'organizzazione IMS. Per ulteriori informazioni, vedere la sezione TENANT_ID della guida per gli sviluppatori del Registro di sistema dello schema.
Risposta
Una risposta corretta mostra un array contenente l'ID del set di dati appena creato sotto forma di "@/dataSets/{DATASET_ID}" . Dopo aver creato e attivato correttamente un dataset, procedere con i passaggi necessari per caricare i dati .
[
    "@/dataSets/5b020a27e7040801dedbf46e"
] 

Configurare un dataset esistente

Nei passaggi seguenti viene illustrato come abilitare un dataset creato in precedenza per il profilo cliente e il servizio identità in tempo reale. Se hai già creato un set di dati con abilitazione per il profilo, procedi alla procedura di acquisizione dei dati .

Verifica se il set di dati è abilitato

Utilizzando l'API Catalog, potete ispezionare un set di dati esistente per determinare se è abilitato per l'uso in Real-time Customer Profile and Identity Service. La seguente chiamata recupera i dettagli di un set di dati per ID.
Formato API
GET /dataSets/{DATASET_ID}

Parametro
Descrizione
{DATASET_ID}
ID di un set di dati da esaminare.
Richiesta
curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e' \
  -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
{
    "5b020a27e7040801dedbf46e": {
        "name": "Commission Program Events DataSet",
        "imsOrg": "{IMS_ORG}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedProfile": [
                "enabled:true"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ]
        },
        "lastBatchId": "6dcd9128a1c84e6aa5177641165e18e4",
        "lastBatchStatus": "success",
        "dule": {},
        "statsCache": {
            "startDate": null,
            "endDate": null
        },
        "namespace": "ACP",
        "state": "DRAFT",
        "version": "1.0.1",
        "created": 1536536917382,
        "updated": 1539793978215,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "viewId": "5b020a27e7040801dedbf46f",
        "status": "enabled",
        "fileDescription": {
            "persisted": true,
            "containerFormat": "parquet",
            "format": "parquet"
        },
        "transforms": "@/dataSets/5b020a27e7040801dedbf46e/views/5b020a27e7040801dedbf46f/transforms",
        "files": "@/dataSets/5b020a27e7040801dedbf46e/views/5b020a27e7040801dedbf46f/files",
        "schema": "@/xdms/context/experienceevent",
        "schemaMetadata": {
            "primaryKey": [],
            "delta": [],
            "dule": [],
            "gdpr": []
        },
        "schemaRef": {
            "id": "https://ns.adobe.com/xdm/context/experienceevent",
            "contentType": "application/vnd.adobe.xed+json"
        }
    }
}

Sotto la tags proprietà, è possibile vedere che unifiedProfile e unifiedIdentity sono entrambi presenti con il valore enabled:true . Di conseguenza, i profili cliente e i servizi identità in tempo reale sono abilitati rispettivamente per questo set di dati.

Abilitare il set di dati

Se il set di dati esistente non è stato abilitato per il servizio Profilo o Identità, puoi attivarlo effettuando una richiesta PATCH utilizzando l’ID del set di dati.
Formato API
PATCH /dataSets/{DATASET_ID}

Parametro
Descrizione
{DATASET_ID}
ID di un set di dati da aggiornare.
Richiesta
curl -X PATCH \
  https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type: application/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}' \
  -d '{
    "tags" : {
        "unifiedProfile": ["enabled:true"],
        "unifiedIdentity": ["enabled:true"]
    }
  }'

Il corpo della richiesta include una tags proprietà, che contiene due proprietà secondarie: "unifiedProfile" e "unifiedIdentity" . I valori di queste proprietà secondarie sono matrici contenenti la stringa "enabled:true" .
Risposta Una richiesta PATCH riuscita restituisce lo stato HTTP 200 (OK) e un array contenente l'ID del set di dati aggiornato. Questo ID deve corrispondere a quello inviato nella richiesta PATCH. Sono stati aggiunti "unifiedProfile" e "unifiedIdentity" i tag e il set di dati è abilitato per l'uso da parte dei servizi Profilo e Identità.
[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Inserimento di dati nel dataset

Sia il profilo cliente in tempo reale che il servizio identità utilizzano i dati XDM durante l'assimilazione in un dataset. Per istruzioni su come caricare i dati in un dataset, fare riferimento all'esercitazione sulla creazione di un dataset mediante le API . Quando pianificate quali dati inviare al set di dati abilitato per il profilo, tenete presenti le seguenti procedure ottimali:
  • Includete tutti i dati che desiderate utilizzare come criteri di segmento dell'audience.
  • Includi tutti gli identificatori che puoi verificare dai dati del tuo profilo per massimizzare il grafico di identità. In questo modo, Servizio identità può unire più efficacemente le identità tra i set di dati.

Conferma acquisizione dati per profilo cliente in tempo reale

Quando si caricano i dati in un nuovo dataset per la prima volta, o come parte di un processo che coinvolge una nuova ETL o una nuova origine dati, si consiglia di controllare attentamente i dati per assicurarsi che siano stati caricati come previsto. Utilizzando l'API Real-time Customer Profile Access, potete recuperare i dati batch mentre vengono caricati in un dataset. Se non riesci a recuperare nessuna delle entità previste, il set di dati potrebbe non essere abilitato per il profilo cliente in tempo reale. Dopo aver confermato che il set di dati è stato abilitato, accertati che il formato e gli identificatori dei dati di origine supportino le tue aspettative. Per istruzioni dettagliate su come utilizzare l'API del profilo cliente in tempo reale per accedere ai dati del profilo, segui la guida secondaria sulle entità, nota anche come "API di accesso profilo" .

Conferma dell'acquisizione dei dati da parte del servizio identità

Ogni frammento di dati inserito contenente più identità crea un collegamento nel grafico dell'identità privata. Per ulteriori informazioni sui grafici identità e sui dati di accesso all'identità, leggere la panoramica del servizio identità.