Endpoint per processi di esportazione

Real-time Customer Profile consente di creare un’unica visualizzazione dei singoli clienti raggruppando i dati provenienti da più sorgenti, inclusi i dati degli attributi e i dati comportamentali. I dati del profilo possono quindi essere esportati in un set di dati per un’ulteriore elaborazione. Ad esempio, è possibile esportare per l’attivazione i segmenti di pubblico dai dati Profile e gli attributi di profilo possono essere esportati per il reporting.

Questo documento fornisce istruzioni dettagliate per la creazione e la gestione dei processi di esportazione tramite l' API profilo.

NOTA

Questa guida descrive l’utilizzo dei processi di esportazione in Profile API. Per informazioni su come gestire i lavori di esportazione per il servizio di segmentazione di Adobe Experience Platform, consulta la guida sui processi di esportazione nell’ API di segmentazione.

Oltre a creare un processo di esportazione, è possibile accedere ai dati Profile utilizzando l'endpoint /entities, noto anche come "Profile Access". Per ulteriori informazioni, consulta la guida all’endpoint entità . Per i passaggi su come accedere ai dati Profile utilizzando l'interfaccia utente, fai riferimento alla guida utente.

Introduzione

Gli endpoint API utilizzati in questa guida fanno parte dell’ API Real-time Customer Profile . Prima di continuare, controlla la guida introduttiva per i collegamenti alla relativa documentazione, una guida per la lettura delle chiamate API di esempio in questo documento e informazioni importanti sulle intestazioni necessarie per effettuare correttamente le chiamate a qualsiasi API Experience Platform.

Creare un processo di esportazione

L’esportazione di dati Profile richiede prima la creazione di un set di dati in cui verranno esportati i dati, quindi l’avvio di un nuovo processo di esportazione. Entrambi questi passaggi possono essere eseguiti utilizzando API di Experience Platform, con le API di servizi di catalogo utilizzate per le prime e le API di profilo cliente in tempo reale. Le istruzioni dettagliate per il completamento di ogni passaggio sono descritte nelle sezioni seguenti.

Creare un set di dati di destinazione

Durante l’esportazione dei dati Profile, è necessario creare prima un set di dati di destinazione. È importante che il set di dati sia configurato correttamente per garantire che l’esportazione abbia esito positivo.

Una delle considerazioni chiave è lo schema su cui è basato il set di dati (schemaRef.id nella richiesta di esempio API di seguito). Per esportare i dati di profilo, il set di dati deve essere basato su XDM Individual Profile Schema dell’unione (https://ns.adobe.com/xdm/context/profile__union). Uno schema di unione è uno schema generato dal sistema e di sola lettura che aggrega i campi degli schemi che condividono la stessa classe. In questo caso, si tratta della classe XDM Individual Profile . Per ulteriori informazioni sugli schemi di visualizzazione dell'unione, vedere la sezione unione nella guida di base sulla composizione dello schema.

I passaggi descritti in questa esercitazione spiegano come creare un set di dati che fa riferimento allo schema dell’Unione XDM Individual Profile utilizzando l’API Catalog. Puoi anche utilizzare l'interfaccia utente Platform per creare un set di dati che faccia riferimento allo schema di unione. I passaggi per l’utilizzo dell’interfaccia utente sono descritti in questa esercitazione sull’interfaccia utente per l’esportazione di segmenti ma sono applicabili anche qui. Una volta completato, puoi tornare a questa esercitazione per procedere con i passaggi per avviare un nuovo processo di esportazione.

Se disponi già di un set di dati compatibile e ne conosci l’ID, puoi procedere direttamente al passaggio avvio di un nuovo processo di esportazione.

Formato API

POST /dataSets

Richiesta

La seguente richiesta crea un nuovo set di dati, fornendo parametri di configurazione nel payload.

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 '{
        "name": "Profile Data Export",
        "schemaRef": {
          "id": "https://ns.adobe.com/xdm/context/profile__union",
          "contentType": "application/vnd.adobe.xed+json;version=1"
        }
      }'
Proprietà Descrizione
name Un nome descrittivo per il set di dati.
schemaRef.id ID della visualizzazione unione (schema) a cui sarà associato il set di dati.

Risposta

Una risposta corretta restituisce un array contenente l’ID univoco di sola lettura, generato dal sistema, del set di dati appena creato. Per esportare correttamente i dati del profilo, è necessario un ID di set di dati configurato correttamente.

[
  "@/datasets/5b020a27e7040801dedba61b"
] 

Avvia processo di esportazione

Una volta che disponi di un set di dati persistente nell’unione, puoi creare un processo di esportazione per mantenere i dati del profilo nel set di dati effettuando una richiesta POST all’endpoint /export/jobs nell’API del profilo cliente in tempo reale e fornendo i dettagli dei dati che desideri esportare nel corpo della richiesta.

Formato API

POST /export/jobs

Richiesta

La seguente richiesta crea un nuovo processo di esportazione, fornendo i parametri di configurazione nel payload.

curl -X POST \
  https://platform.adobe.io/data/core/ups/export/jobs \
  -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": "identities.id,personalEmail.address",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "additionalFields" : {
      "eventList": {
        "fields": "environment.browserDetails.name,environment.browserDetails.version",
        "filter": {
          "fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
        }
      }
    }
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }' 
Proprietà Descrizione
fields (Facoltativo) Limita i campi di dati da includere nell’esportazione solo a quelli forniti in questo parametro. Se si omette questo valore, tutti i campi verranno inclusi nei dati esportati.
mergePolicy (Facoltativo) Specifica il criterio di unione per la gestione dei dati esportati. Includi questo parametro quando sono in corso l’esportazione di più segmenti.
mergePolicy.id ID del criterio di unione.
mergePolicy.version Versione specifica del criterio di unione da utilizzare. L’eliminazione di questo valore viene eseguita per impostazione predefinita nella versione più recente.
additionalFields.eventList (Facoltativo) Controlla i campi evento delle serie temporali esportati per oggetti secondari o associati fornendo una o più delle seguenti impostazioni:
  • eventList.fields: Controllare i campi da esportare.
  • eventList.filter: Specifica i criteri che limitano i risultati inclusi dagli oggetti associati. Si attende un valore minimo necessario per l’esportazione, in genere una data.
  • eventList.filter.fromIngestTimestamp: Filtra gli eventi delle serie temporali in quelli che sono stati acquisiti dopo la marca temporale fornita. Questo non è il momento dell’evento stesso, ma il momento dell’acquisizione degli eventi.
destination (Obbligatorio) Informazioni sulla destinazione per i dati esportati:
  • destination.datasetId: (Obbligatorio) L'ID del set di dati in cui devono essere esportati i dati.
  • destination.segmentPerBatch: (Facoltativo) Un valore booleano che, se non specificato, viene impostato come predefinito false. Il valore false esporta tutti gli ID segmento in un singolo ID batch. Un valore di true esporta un ID segmento in un ID batch. Tieni presente che l’impostazione del valore su true può influire sulle prestazioni dell’esportazione batch.
schema.name (Obbligatorio) Il nome dello schema associato al set di dati in cui devono essere esportati i dati.
NOTA

Per esportare solo i dati di profilo e non includere i dati relativi alle serie temporali, rimuovi l’oggetto "additionalFields" dalla richiesta.

Risposta

Una risposta corretta restituisce un set di dati popolato con dati di profilo come specificato nella richiesta.

{
    "profileInstanceId": "ups",
    "jobType": "BATCH",
    "id": 24115,
    "schema": {
        "name": "_xdm.context.profile"
    },
    "mergePolicy": {
        "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
        "version": 1
    },
    "status": "NEW",
    "requestId": "IwkVcD4RupdSmX376OBVORvcvTdA4ypN",
    "computeGatewayJobId": {},
    "metrics": {
        "totalTime": {
            "startTimeInMs": 1559674261657
        }
    },
    "destination": {
      "dataSetId" : "5cf6bcf79ecc7c14530fe436",
      "segmentPerBatch": false,
      "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
    },
    "updateTime": 1559674261868,
    "imsOrgId": "{IMS_ORG}",
    "creationTime": 1559674261657
}

Elenca tutti i processi di esportazione

È possibile restituire un elenco di tutti i processi di esportazione per una particolare organizzazione IMS eseguendo una richiesta di GET all'endpoint export/jobs. La richiesta supporta anche i parametri di query limit e offset, come mostrato di seguito.

Formato API

GET /export/jobs
GET /export/jobs?{QUERY_PARAMETERS}
Parametro Descrizione
start Offset la pagina dei risultati restituiti, in base al tempo di creazione della richiesta. Esempio: start=4
limit Limita il numero di risultati restituiti. Esempio: limit=10
page Restituisce una pagina specifica di risultati, in base al tempo di creazione della richiesta. Esempio: page=2
sort Ordinare i risultati in base a un campo specifico in ordine crescente ( asc ) o decrescente ( desc ). Il parametro di ordinamento non funziona quando si restituiscono più pagine di risultati. Esempio: sort=updateTime:asc

Richiesta

curl -X GET \
  https://platform.adobe.io/data/core/ups/export/jobs/ \
  -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

La risposta include un oggetto records contenente i processi di esportazione creati dalla tua organizzazione IMS.

{
  "records": [
    {
      "profileInstanceId": "ups",
      "jobType": "BATCH",
      "id": 726,
      "schema": {
          "name": "_xdm.context.profile"
      },
      "mergePolicy": {
          "id": "timestampOrdered-none-mp",
          "version": 1
      },
      "status": "SUCCEEDED",
      "requestId": "d995479c-8a08-4240-903b-af469c67be1f",
      "computeGatewayJobId": {
          "exportJob": "f3058161-7349-4ca9-807d-212cee2c2e94",
          "pushJob": "feaeca05-d137-4605-aa4e-21d19d801fc6"
      },
      "metrics": {
          "totalTime": {
              "startTimeInMs": 1538615973895,
              "endTimeInMs": 1538616233239,
              "totalTimeInMs": 259344
          },
          "profileExportTime": {
              "startTimeInMs": 1538616067445,
              "endTimeInMs": 1538616139576,
              "totalTimeInMs": 72131
          },
          "aCPDatasetWriteTime": {
              "startTimeInMs": 1538616195172,
              "endTimeInMs": 1538616195715,
              "totalTimeInMs": 543
          }
      },
      "destination": {
          "datasetId": "5b7c86968f7b6501e21ba9df",
          "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
      },
      "updateTime": 1538616233239,
      "imsOrgId": "{IMS_ORG}",
      "creationTime": 1538615973895
    },
    {
      "profileInstanceId": "test_xdm_latest_profile_20_e2e_1538573005395",
      "errors": [
        {
          "code": "0090000009",
          "msg": "Error writing profiles to output path 'adl://va7devprofilesnapshot.azuredatalakestore.net/snapshot/722'",
          "callStack": "com.adobe.aep.unifiedprofile.common.logging.Logger" 
        },
        {
          "code": "unknown",
          "msg": "Job aborted.",
          "callStack": "org.apache.spark.SparkException: Job aborted."
        }
      ],
      "jobType": "BATCH",
      "filter": {
        "segments": [
            {
                "segmentId": "7a93d2ff-a220-4bae-9a4e-5f3c35032be3"
            }
        ]
      },
      "id": 722,
      "schema": {
          "name": "_xdm.context.profile"
      },
      "mergePolicy": {
          "id": "7972e3d6-96ea-4ece-9627-cbfd62709c5d",
          "version": 1
      },
      "status": "FAILED",
      "requestId": "KbOAsV7HXmdg262lc4yZZhoml27UWXPZ",
      "computeGatewayJobId": {
          "exportJob": "15971e0f-317c-4390-9038-1a0498eb356f"
      },
      "metrics": {
          "totalTime": {
              "startTimeInMs": 1538573416687,
              "endTimeInMs": 1538573922551,
              "totalTimeInMs": 505864
          },
          "profileExportTime": {
              "startTimeInMs": 1538573872211,
              "endTimeInMs": 1538573918809,
              "totalTimeInMs": 46598
          }
      },
      "destination": {
          "datasetId": "5bb4c46757920712f924a3eb",
          "batchId": ""
      },
      "updateTime": 1538573922551,
      "imsOrgId": "{IMS_ORG}",
      "creationTime": 1538573416687
    }
  ],
  "page": {
      "sortField": "createdTime",
      "sort": "desc",
      "pageOffset": "1538573416687_722",
      "pageSize": 2
  },
  "link": {
      "next": "/export/jobs/?limit=2&offset=1538573416687_722"
  }
}

Monitorare l’avanzamento dell’esportazione

Per visualizzare i dettagli di un processo di esportazione specifico o monitorarne lo stato durante il processo, puoi effettuare una richiesta di GET all’ endpoint /export/jobs e includere nel percorso id del processo di esportazione. Il processo di esportazione viene completato una volta che il campo status restituisce il valore "SUCCEEDED".

Formato API

GET /export/jobs/{EXPORT_JOB_ID}
Parametro Descrizione
{EXPORT_JOB_ID} Il id del processo di esportazione a cui si desidera accedere.

Richiesta

curl -X GET \
  https://platform.adobe.io/data/core/ups/export/jobs/24115 \
  -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

{
    "profileInstanceId": "ups",
    "jobType": "BATCH",
    "id": 24115,
    "schema": {
        "name": "_xdm.context.profile"
    },
    "mergePolicy": {
        "id": "0bf16e61-90e9-4204-b8fa-ad250360957b",
        "version": 1
    },
    "status": "SUCCEEDED",
    "requestId": "YwMt1H8QbVlGT2pzyxgwFHTwzpMbHrTq",
    "computeGatewayJobId": {
      "exportJob": "305a2e5c-2cf3-4746-9b3d-3c5af0437754",
      "pushJob": "963f275e-91a3-4fa1-8417-d2ca00b16a8a"
    },
    "metrics": {
      "totalTime": {
        "startTimeInMs": 1547053539564,
        "endTimeInMs": 1547054743929,
        "totalTimeInMs": 1204365
      },
      "profileExportTime": {
        "startTimeInMs": 1547053667591,
        "endTimeInMs": 1547053778195,
        "totalTimeInMs": 110604
      },
      "aCPDatasetWriteTime": {
        "startTimeInMs": 1547054660416,
        "endTimeInMs": 1547054698918,
        "totalTimeInMs": 38502
      }
    },
    "destination": {
      "dataSetId" : "5cf6bcf79ecc7c14530fe436",
      "segmentPerBatch": false,
      "batchId": "da5cfb4de32c4b93a09f7e37fa53ad52"
    },
    "updateTime": 1559674261868,
    "imsOrgId": "{IMS_ORG}",
    "creationTime": 1559674261657
}
Proprietà Descrizione
batchId Identificatore dei batch creati da un'esportazione riuscita, da utilizzare a scopo di ricerca durante la lettura dei dati del profilo.

Annullare un processo di esportazione

L’Experience Platform ti consente di annullare un processo di esportazione esistente, che può essere utile per una serie di motivi, tra cui se il processo di esportazione non è stato completato o è rimasto bloccato nella fase di elaborazione. Per annullare un processo di esportazione, è possibile eseguire una richiesta di DELETE all’endpoint /export/jobs e includere il id del processo di esportazione che si desidera annullare nel percorso della richiesta.

Formato API

DELETE /export/jobs/{EXPORT_JOB_ID}
Parametro Descrizione
{EXPORT_JOB_ID} Il id del processo di esportazione a cui si desidera accedere.

Richiesta

curl -X POST \
  https://platform.adobe.io/data/core/ups/export/jobs/726 \
  -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

Una richiesta di eliminazione corretta restituisce lo stato HTTP 204 (nessun contenuto) e un corpo di risposta vuoto, a indicare che l'operazione di annullamento è riuscita.

Passaggi successivi

Una volta completata correttamente l’esportazione, i dati sono disponibili nell’Experience Platform Data Lake . Puoi quindi utilizzare l' API di accesso ai dati per accedere ai dati utilizzando il batchId associato all'esportazione. A seconda delle dimensioni dell'esportazione, i dati possono essere in blocchi e il batch può essere costituito da più file.

Per istruzioni dettagliate su come utilizzare l'API di accesso ai dati per accedere e scaricare file batch, segui il tutorial sull'accesso ai dati.

Puoi anche accedere ai dati del profilo cliente in tempo reale esportati correttamente utilizzando il servizio Query Adobe Experience Platform. Utilizzando l’interfaccia utente o l’API RESTful, Query Service consente di scrivere, convalidare ed eseguire query sui dati all’interno del Data Lake.

Per ulteriori informazioni su come eseguire query sui dati del pubblico, consulta la documentazione del servizio query.

Appendice

La sezione seguente contiene informazioni aggiuntive sui lavori di esportazione nell’API del profilo.

Esempi aggiuntivi di payload per l’esportazione

La chiamata API di esempio mostrata nella sezione relativa all' avvio di un processo di esportazione crea un processo che contiene sia dati di profilo (record) che di evento (serie temporale). Questa sezione fornisce esempi di payload di richiesta aggiuntivi per limitare l’esportazione in modo che contenga un tipo di dati o l’altro.

Il seguente payload crea un processo di esportazione che contiene solo i dati di profilo (nessun evento):

{
    "fields": "identities.id,personalEmail.address",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }

Per creare un processo di esportazione che contiene solo i dati evento (nessun attributo di profilo), il payload potrebbe essere simile al seguente:

{
    "fields": "identityMap",
    "mergePolicy": {
      "id": "e5bc94de-cd14-4cdf-a2bc-88b6e8cbfac2",
      "version": 1
    },
    "additionalFields" : {
      "eventList": {
        "fields": "environment.browserDetails.name,environment.browserDetails.version",
        "filter": {
          "fromIngestTimestamp": "2018-10-25T13:22:04-07:00"
        }
      }
    },
    "destination": {
      "datasetId": "5b020a27e7040801dedba61b",
      "segmentPerBatch": false
    },
    "schema": {
      "name": "_xdm.context.profile"
    }
  }

Esportazione di segmenti

Puoi anche utilizzare l’endpoint dei processi di esportazione per esportare segmenti di pubblico invece dei dati Profile . Per ulteriori informazioni, consulta la guida sui processi di esportazione nell’ API di segmentazione .

In questa pagina