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

Questa esercitazione descrive il processo di abilitazione di un set di dati con funzionalità "upsert" per effettuare aggiornamenti ai dati del profilo cliente in tempo reale. Ciò include passaggi per la creazione di un nuovo set di dati e la configurazione di un set di dati esistente.

Introduzione

Questa esercitazione richiede una comprensione approfondita di diversi servizi Adobe Experience Platform coinvolti nella gestione dei set di dati abilitati per il profilo. Prima di iniziare questa esercitazione, consulta la documentazione relativa a Platform servizi:

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 sulle come leggere le chiamate API di esempio in Experience Platform guida alla risoluzione dei problemi.

Raccogli i valori delle intestazioni richieste

Per effettuare chiamate a Platform API, devi prima completare l’ esercitazione sull'autenticazione. Il completamento dell’esercitazione sull’autenticazione fornisce i valori per ciascuna delle intestazioni richieste in tutte le Experience Platform Chiamate API, 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 Content-Type intestazione. 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 a Platform Le API richiedono un x-sandbox-name intestazione che specifica il nome della sandbox in cui verrà effettuata l’operazione. Per ulteriori informazioni sulle sandbox in Platform, vedi documentazione panoramica su sandbox.

Creare un set di dati abilitato per gli aggiornamenti dei profili

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

NOTA

Per creare un nuovo set di dati abilitato per il profilo, devi 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, consulta l’esercitazione su creazione di uno schema tramite l’API del Registro di sistema dello schema.

Per creare un set di dati abilitato per Profilo e aggiornamenti, utilizza una richiesta di POST per /dataSets punto finale.

Formato API

POST /dataSets

Richiesta

Includendo unifiedProfile sotto tags nel corpo della richiesta, il set di dati sarà abilitato per Profile al momento della creazione. All'interno di unifiedProfile array, aggiunta isUpsert:true aggiunge 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: {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",
            "isUpsert:true"
          ]
        }
      }'
Proprietà Descrizione
schemaRef.id ID del Profileschema abilitato su cui verrà basato il set di dati.
{TENANT_ID} Lo spazio dei nomi all’interno del Schema Registry che contiene risorse appartenenti all’organizzazione IMS. Consulta la sezione TENANT_ID della sezione Schema Registry guida per sviluppatori per ulteriori informazioni.

Risposta

Una risposta corretta 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

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

NOTA

Per configurare un set di dati abilitato per il profilo esistente per "upsert", devi prima disabilitare il set di dati per il profilo e quindi riabilitarlo insieme al isUpsert tag . Se il set di dati esistente non è abilitato per Profilo, puoi procedere direttamente ai passaggi per abilitazione del set di dati per Profilo e aggiornamento. Se non sei sicuro, i passaggi seguenti mostrano come verificare se il set di dati è già abilitato.

Controlla se il set di dati è abilitato per Profilo

Utilizzo della Catalog API, puoi controllare 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 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": "{DATASET_NAME}",
        "imsOrg": "{IMS_ORG}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedProfile": [
                "enabled:true"
            ]
        },
        "lastBatchId": "{BATCH_ID}",
        "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": "{VIEW_ID}",
        "status": "enabled",
        "transforms": "@/dataSets/5b020a27e7040801dedbf46e/views/5b020a27e7040801dedbf46f/transforms",
        "files": "@/dataSets/5b020a27e7040801dedbf46e/views/5b020a27e7040801dedbf46f/files",
        "schema": "{SCHEMA}",
        "schemaMetadata": {
            "primaryKey": [],
            "delta": [],
            "dule": [],
            "gdpr": []
        },
        "schemaRef": {
            "id": "https://ns.adobe.com/xdm/context/experienceevent",
            "contentType": "application/vnd.adobe.xed+json"
        }
    }
}

Sotto la tags puoi vedere che unifiedProfile è presente 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, devi prima disabilitare il unifiedProfile e quindi riattivarlo accanto al tag isUpsert tag . Questa operazione viene eseguita utilizzando due richieste PATCH, una volta per disabilitare e una per riabilitare.

AVVERTENZA

I dati acquisiti nel set di dati quando è disattivato non verranno acquisiti nell’archivio profili. Si consiglia di evitare di acquisire dati nel set di dati fino a quando non viene riabilitato per Profilo.

Formato API

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

Richiesta

Il primo corpo della richiesta di PATCH include un path a unifiedProfile impostazione value a enabled:false per disabilitare il 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        { "op": "replace", "path": "/tags/unifiedProfile", "value": ["enabled:false"] },
      ]'

Risposta
Una richiesta PATCH corretta 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. La unifiedProfile Il tag è stato disattivato.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Abilita il set di dati per Profilo e aggiornamento

Un set di dati esistente può essere abilitato per gli aggiornamenti di profili e attributi utilizzando una singola richiesta PATCH.

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 path a unifiedProfile impostazione value per includere enabled e isUpsert tag, entrambi impostati 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        { "op": "add", "path": "/tags/unifiedProfile", "value": ["enabled:true","isUpsert:true"] },
      ]'

Risposta
Una richiesta PATCH corretta 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. La unifiedProfile Il tag è stato ora abilitato e configurato per gli aggiornamenti degli attributi.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Passaggi successivi

Il set di dati abilitato per profili e per gli utenti può ora essere utilizzato dai flussi di lavoro di acquisizione in batch e in streaming per apportare aggiornamenti ai dati del profilo. Per ulteriori informazioni sull’acquisizione di dati in Adobe Experience Platform, consulta la sezione panoramica sull’acquisizione dei dati.

In questa pagina