Configura un set di dati per Profile e Identity Service utilizzando le API

Questa esercitazione descrive il processo di abilitazione di un set di dati da utilizzare in Real-time Customer Profile e Identity Service, suddivisi nei seguenti passaggi:

1. Abilita un set di dati da utilizzare in Real-time Customer Profile utilizzando una delle due opzioni seguenti:
   • Creare un nuovo set di dati
   • Configurare un set di dati esistente
2. Inserire dati nel set di dati
3. Conferma l’acquisizione dei dati per profilo cliente in tempo reale
4. Conferma dell’acquisizione dei dati da parte del servizio Identity

Introduzione

Questa esercitazione richiede una comprensione approfondita dei vari servizi Adobe Experience Platform coinvolti nella gestione dei set di dati abilitati Profile. Prima di iniziare questa esercitazione, consulta la documentazione relativa a questi servizi Platform correlati:

• Real-time Customer Profile: Fornisce un profilo di consumatore unificato e in tempo reale basato su dati aggregati provenienti da più origini.
• Identity Service: Consente Real-time Customer Profile di colmare le identità provenienti da origini dati diverse che vengono acquisite in Platform.
• Catalog Service: API RESTful che consente di creare set di dati e configurarli per Real-time Customer Profile e Identity Service.
• Experience Data Model (XDM): Il framework standardizzato in base al quale Platform vengono organizzati i dati sulla customer experience.

Le sezioni seguenti forniscono informazioni aggiuntive che dovrai conoscere per effettuare correttamente le chiamate alle API di Platform.

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 richiesta formattati correttamente. Viene inoltre fornito un esempio di codice JSON restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, consulta la sezione su come leggere le chiamate API di esempio nella guida alla risoluzione dei problemi di Experience Platform .

Raccogli i valori delle intestazioni richieste

Per effettuare chiamate alle API Platform, devi prima completare l’ esercitazione sull’autenticazione. Il completamento dell’esercitazione di autenticazione fornisce i valori per ciascuna delle intestazioni richieste in tutte le chiamate API Experience Platform, come mostrato di seguito:

• Authorization: Bearer {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. Il valore corretto per questa intestazione viene mostrato nelle richieste di esempio, se necessario.

Tutte le risorse in Experience Platform sono isolate in sandbox virtuali specifiche. Tutte le richieste alle API Platform richiedono un’intestazione x-sandbox-name che specifica il nome della sandbox in cui avrà luogo l’operazione. Per ulteriori informazioni sulle sandbox in Platform, consulta la documentazione di panoramica sandbox.

Crea un set di dati abilitato per Profile e Identity

Puoi abilitare un set di dati per Real-time Customer Profile e Identity Service immediatamente dopo la creazione o in qualsiasi momento dopo la creazione del set di dati. Per abilitare un set di dati già creato, segui i passaggi per configurare un set di dati esistente che si trovano più avanti in questo documento. Per creare un nuovo set di dati, devi conoscere l’ID di uno schema XDM esistente abilitato per Profilo cliente in tempo reale. Per informazioni su come cercare o creare uno schema abilitato per il profilo, consulta l’esercitazione su creazione di uno schema utilizzando l’API del Registro di sistema dello schema. La seguente chiamata all’ API Catalog abilita un set di dati per Profile e Identity Service.

Formato API

POST /dataSets

Richiesta

Inserendo unifiedProfile e unifiedIdentity in tags nel corpo della richiesta, il set di dati verrà immediatamente abilitato per rispettivamente 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 '{
    "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"]
    }
  }'

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 abilitato correttamente un set di dati, procedi con i passaggi per caricare i dati.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
] 

Configurare un set di dati esistente

I passaggi seguenti spiegano come abilitare un set di dati creato in precedenza per Real-time Customer Profile e Identity Service. Se hai già creato un set di dati abilitato per il profilo, procedi con i passaggi per acquisizione di dati.

Controlla se il set di dati è abilitato

Utilizzando l’API Catalog, puoi controllare un set di dati esistente per determinare se è abilitato per l’utilizzo in Real-time Customer Profile e Identity Service. La chiamata seguente recupera i dettagli di un set di dati per ID.

Formato API

GET /dataSets/{DATASET_ID}

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",
        "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 proprietà tags , puoi vedere che unifiedProfile e unifiedIdentity sono entrambi presenti con il valore enabled:true. Pertanto, Real-time Customer Profile e Identity Service sono abilitati rispettivamente per questo set di dati.

Abilitare il set di dati

Se il set di dati esistente non è stato abilitato per Profile o Identity Service, puoi abilitarlo effettuando una richiesta PATCH utilizzando l’ID del set di dati.

Formato API

PATCH /dataSets/{DATASET_ID}

Richiesta

curl -X PATCH \
  https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+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 '[
        { "op": "add", "path": "/tags/unifiedProfile", "value": ["enabled:true"] },
        { "op": "add", "path": "/tags/unifiedIdentity", "value": ["enabled:true"] }	
      ]'

Il corpo della richiesta include un tag path a due tipi di tag, unifiedProfile e unifiedIdentity. Le value di ciascuna sono matrici contenenti la stringa enabled:true.

​
ResponseUna 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 di PATCH. I tag unifiedProfile e unifiedIdentity sono stati aggiunti e il set di dati è abilitato per l’uso da parte dei servizi Profilo e Identità.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Inserire dati nel set di dati

Sia Real-time Customer Profile che Identity Service utilizzano dati XDM durante l’acquisizione in un set di dati. Per istruzioni su come caricare i dati in un set di dati, consulta l’esercitazione su creazione di un set di dati utilizzando le API. Quando pianifichi quali dati inviare al set di dati abilitato Profile, prendi in considerazione le seguenti best practice:

• Includi tutti i dati che desideri utilizzare come criteri di segmento del pubblico.
• Includi tutti gli identificatori che puoi verificare dai dati del profilo per massimizzare il grafico delle identità. Questo consente a Identity Service di unire le identità tra i set di dati in modo più efficace.

Conferma l’acquisizione dei dati per Real-time Customer Profile

Quando carichi i dati in un nuovo set di dati per la prima volta o come parte di un processo che coinvolge una nuova ETL o una nuova origine dati, è consigliabile controllare attentamente i dati per assicurarsi che siano stati caricati come previsto. Utilizzando l’ API di accesso Real-time Customer Profile è possibile recuperare i dati batch caricati in un set di dati. Se non riesci a recuperare nessuna delle entità previste, il set di dati potrebbe non essere abilitato per Real-time Customer Profile. Dopo aver confermato che il set di dati è stato abilitato, assicurati che il formato e gli identificatori dei dati di origine supportino le tue aspettative. Per istruzioni dettagliate su come utilizzare l'API Real-time Customer Profile per accedere ai dati Profile, segui la guida all'endpoint entità, nota anche come API "Profile Access".

Conferma dell’acquisizione dei dati da parte del servizio Identity

Ogni frammento di dati acquisito che contiene più di un’identità crea un collegamento nel grafico della tua identità privata. Per ulteriori informazioni sui grafici di identità e sull’accesso ai dati di identità, inizia leggendo la panoramica del servizio Identity.