Abilitare un set di dati per gli aggiornamenti dei profili tramite API

Questa esercitazione illustra il processo di abilitazione di un set di dati con funzionalità di "upsert" per apportare aggiornamenti ai dati del profilo cliente in tempo reale. Ciò include i passaggi per creare un nuovo set di dati e configurare un set di dati esistente.

NOTE
Il flusso di lavoro descritto in questa esercitazione funziona solo per l’acquisizione in batch. Per gli aggiornamenti di acquisizione in streaming, consulta la guida in invio di aggiornamenti di riga parziali al profilo cliente in tempo reale tramite la preparazione dati.

Introduzione

Questo tutorial richiede una buona conoscenza di diversi servizi Adobe Experience Platform coinvolti nella gestione dei set di dati abilitati per il profilo. Prima di iniziare questo tutorial, consulta la documentazione di questi servizi Platform correlati:

  • Real-Time Customer Profile: fornisce un profilo consumer unificato e in tempo reale basato su dati aggregati provenienti da più origini.
  • 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): framework standardizzato tramite il quale Platform organizza i dati sull'esperienza del cliente.
  • Acquisizione batch: l'API di acquisizione batch consente di acquisire dati in Experience Platform come file batch.

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

Lettura delle chiamate API di esempio

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

Raccogliere i valori per le intestazioni richieste

Per effettuare chiamate alle API Platform, devi prima completare l'esercitazione di autenticazione. Completando il tutorial sull’autenticazione si ottengono i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di Experience Platform, come mostrato di seguito:

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un'intestazione Content-Type aggiuntiva. Il valore corretto per questa intestazione viene mostrato nelle richieste di esempio, se necessario.

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

Creare un set di dati abilitato per gli aggiornamenti del profilo

Quando crei un nuovo set di dati, puoi abilitarlo per il profilo e abilitare le funzionalità di aggiornamento al momento della creazione.

NOTE
Per creare un nuovo set di dati abilitato per il profilo, è necessario conoscere l’ID di uno schema XDM esistente abilitato per il profilo. Per informazioni su come cercare o creare uno schema abilitato per il profilo, vedere il tutorial su creazione di uno schema tramite l'API Schema Registry.

Per creare un set di dati abilitato per Profilo e aggiornamenti, utilizzare una richiesta POST all'endpoint /dataSets.

Formato API

POST /dataSets

Richiesta

Includendo sia unifiedIdentity che unifiedProfile in tags nel corpo della richiesta, il set di dati verrà abilitato per Profile al momento della creazione. All'interno dell'array unifiedProfile, l'aggiunta di isUpsert:true aggiungerà la possibilità per il set di dati di supportare gli aggiornamenti.

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "Sample dataset",
        "description: "A sample dataset with a sample description.",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
            "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
        },
        "tags": {
            "unifiedIdentity": [
                "enabled: true"
            ],
            "unifiedProfile": [
                "enabled: true",
                "isUpsert: true"
            ]
        }
      }'
Proprietà
Descrizione
schemaRef.id
ID dello schema abilitato per Profile su cui verrà basato il set di dati.
{TENANT_ID}
Lo spazio dei nomi all'interno di Schema Registry che contiene le risorse appartenenti alla tua organizzazione. Per ulteriori informazioni, vedere la sezione TENANT_ID della Guida per gli sviluppatori di Schema Registry.

Risposta

In caso di esito positivo, la risposta mostra un array contenente l'ID del set di dati appena creato sotto forma di "@/dataSets/{DATASET_ID}".

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Configurare un set di dati esistente configure-an-existing-dataset

I passaggi seguenti descrivono come configurare un set di dati esistente abilitato per il profilo per la funzionalità di aggiornamento (upsert).

NOTE
Per configurare un set di dati esistente abilitato per il profilo per l'upsert, è innanzitutto necessario disabilitare il set di dati per il profilo e quindi abilitarlo nuovamente insieme al tag isUpsert. Se il set di dati esistente non è abilitato per il profilo, puoi procedere direttamente alla procedura per abilitare il set di dati per il profilo e l'upsert. In caso di dubbi, i passaggi seguenti mostrano come verificare se il set di dati è già abilitato.

Verifica se il set di dati è abilitato per il profilo

Utilizzando l'API Catalog, è possibile esaminare un set di dati esistente per determinare se è abilitato per l'utilizzo in Real-Time Customer Profile. La chiamata seguente 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 controllare.

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

{
    "5b020a27e7040801dedbf46e": {
        "name": "{DATASET_NAME}",
        "imsOrg": "{ORG_ID}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ],
            "unifiedProfile": [
                "enabled:true"
            ]
        },
        "version": "1.0.1",
        "created": 1536536917382,
        "updated": 1539793978215,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "viewId": "{VIEW_ID}",
        "files": "@/dataSetFiles?dataSetId=5b020a27e7040801dedbf46e",
        "schema": "{SCHEMA}",
        "schemaRef": {
            "id": "https://ns.adobe.com/xdm/context/experienceevent",
            "contentType": "application/vnd.adobe.xed+json"
        }
    }
}

Nella proprietà tags è presente unifiedProfile con il valore enabled:true. Pertanto, Real-Time Customer Profile è abilitato per questo set di dati.

Disattiva il set di dati per il profilo

Per configurare un set di dati abilitato per il profilo per gli aggiornamenti, è innanzitutto necessario disabilitare i tag unifiedProfile e unifiedIdentity e quindi abilitarli nuovamente insieme al tag isUpsert. Questa operazione viene eseguita utilizzando due richieste PATCH, una per disabilitare e una per riabilitare.

WARNING
I dati acquisiti nel set di dati mentre è disabilitato non verranno acquisiti nell’archivio profili. Evita di acquisire i dati nel set di dati fino a quando non vengono riabilitati per il profilo.

Formato API

PATCH /dataSets/{DATASET_ID}
Parametro
Descrizione
{DATASET_ID}
ID del set di dati da aggiornare.

Richiesta

Il primo corpo della richiesta PATCH include path in unifiedProfile e path in unifiedIdentity, impostando value in enabled:false per entrambi i percorsi al fine di disabilitare i tag.

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
            "op": "replace",
            "path": "/tags/unifiedProfile",
            "value": ["enabled:false"]
        },
        {
            "op": "replace",
            "path": "/tags/unifiedIdentity",
            "value": ["enabled:false"]
        }
      ]'

Risposta

In caso di esito positivo, la richiesta PATCH restituisce lo stato HTTP 200 (OK) e una matrice contenente l’ID del set di dati aggiornato. Questo ID deve corrispondere a quello inviato nella richiesta PATCH. I tag unifiedProfile e unifiedIdentity sono stati disabilitati.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Abilita il set di dati per Profilo e upsert enable-the-dataset

È possibile abilitare un set di dati esistente per gli aggiornamenti di profili e attributi utilizzando una singola richiesta PATCH.

IMPORTANT
Quando abiliti il set di dati per il profilo, accertati che lo schema a cui è associato il set di dati sia anche abilitato per il profilo. Se lo schema non è abilitato per il profilo, il set di dati non verrà visualizzato come abilitato per il profilo nell'interfaccia utente di Platform.

Formato API

PATCH /dataSets/{DATASET_ID}
Parametro
Descrizione
{DATASET_ID}
ID di un set di dati da aggiornare.

Richiesta

Il corpo della richiesta include un tag da path a unifiedProfile che imposta value per includere i tag enabled e isUpsert, entrambi impostati su true, e un tag da path a unifiedIdentity che imposta value per includere il tag enabled impostato su true.

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
            "op": "add",
            "path": "/tags/unifiedProfile",
            "value": [
                "enabled:true",
                "isUpsert:true"
            ]
        },
        {
            "op": "add",
            "path": "/tags/unifiedIdentity",
            "value": [
                "enabled:true"
            ]
        }
      ]'

Risposta

In caso di esito positivo, la richiesta PATCH restituisce lo stato HTTP 200 (OK) e una matrice contenente l’ID del set di dati aggiornato. Questo ID deve corrispondere a quello inviato nella richiesta PATCH. Il tag unifiedProfile e il tag unifiedIdentity sono stati abilitati e configurati per gli aggiornamenti degli attributi.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Passaggi successivi

Ora è possibile utilizzare il profilo e il set di dati abilitato per l’upsert tramite flussi di lavoro di acquisizione batch per apportare aggiornamenti ai dati del profilo. Per ulteriori informazioni sull'acquisizione di dati in Adobe Experience Platform, consulta la panoramica sull'acquisizione dei dati.

recommendation-more-help
c5c02be6-79a3-4a2f-b766-136bffe8b676