Sviluppo di integrazioni ETL per Adobe Experience Platform

La guida all'integrazione di ETL illustra i passaggi generali per la creazione di connettori sicuri e a elevate prestazioni per Experience Platform e l'acquisizione di dati in Platform.

Questa guida include anche esempi di chiamate API da utilizzare durante la progettazione di un connettore ETL, con collegamenti alla documentazione che descrive ogni servizio Experience Platform e maggiori dettagli sull'utilizzo della relativa API.

Un esempio di integrazione è disponibile su GitHub tramite ETL Ecosystem Integration Reference Code con la licenza Apache versione 2.0.

Flusso di lavoro

Il seguente diagramma fornisce una panoramica generale dell'integrazione dei componenti Adobe Experience Platform con un'applicazione ETL e un connettore.

Componenti Adobe Experience Platform

Nelle integrazioni del connettore ETL sono coinvolti più componenti di Experience Platform. L’elenco seguente illustra diversi componenti e funzionalità chiave:

Guida introduttiva a Experience Platform API

Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere o avere a disposizione per effettuare correttamente chiamate alle API Experience Platform.

Lettura delle chiamate API di esempio

Questa guida fornisce esempi di chiamate API per illustrare 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:

Tutte le risorse in Experience Platform sono isolate in specifiche sandbox virtuali. Tutte le richieste alle API Platform richiedono un'intestazione che specifichi il nome della sandbox in cui verrà eseguita l'operazione:

Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione aggiuntiva:

Flusso utente generale

Per iniziare, un utente ETL accede all'interfaccia utente di Experience Platform e crea set di dati per l'acquisizione utilizzando un connettore standard o un connettore push-service.

Nell’interfaccia utente, l’utente crea il set di dati di output selezionando uno schema di set di dati. La scelta dello schema dipende dal tipo di dati (record o serie temporali) acquisiti in Platform. Facendo clic sulla scheda Schemi nell’interfaccia utente, l’utente potrà visualizzare tutti gli schemi disponibili, incluso il tipo di comportamento supportato dallo schema.

Nello strumento ETL, l’utente inizierà a progettare le trasformazioni di mappatura dopo aver configurato la connessione appropriata (utilizzando le credenziali). Si presume che nello strumento ETL siano già installati Experience Platform connettori (processo non definito in questa Guida all'integrazione).

I moduli per uno strumento ETL di esempio e un flusso di lavoro sono stati forniti nel flusso di lavoro ETL. Sebbene gli strumenti ETL possano differire nel formato, la maggior parte di essi espone funzionalità simili.

Visualizzare l’elenco dei set di dati

Utilizzando l'origine dati per la mappatura, è possibile ottenere un elenco di tutti i set di dati disponibili utilizzando Catalog API.

È possibile inviare una singola richiesta API per visualizzare tutti i set di dati disponibili (ad esempio GET /dataSets); la best practice prevede l'inclusione di parametri di query che limitano la dimensione della risposta.

Nei casi in cui vengono richieste informazioni complete sul set di dati, il payload di risposta può raggiungere dimensioni superiori a 3 GB, rallentando le prestazioni complessive. Pertanto, l'utilizzo dei parametri di query per filtrare solo le informazioni necessarie renderà Catalog le query più efficienti.

Filtraggio elenco

Quando si filtrano le risposte, è possibile utilizzare più filtri in una singola chiamata separando i parametri con una e commerciale (&). Alcuni parametri di query accettano elenchi di valori separati da virgole, ad esempio il filtro "properties" nella richiesta di esempio seguente.

Catalog risposte vengono misurate automaticamente in base ai limiti configurati, tuttavia il parametro di query "limit" può essere utilizzato per personalizzare i vincoli e limitare il numero di oggetti restituiti. I limiti di risposta Catalog preconfigurati sono:

I parametri di query sono descritti più dettagliatamente nella panoramica di Catalog Service.

Formato API

GET /catalog/dataSets
GET /catalog/dataSets?{filter1}={value1},{value2}&{filter2}={value3}

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=3&properties=name,description,schemaRef" \
  -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}"

Per esempi dettagliati su come effettuare chiamate a Catalog API, consulta la panoramica di Catalog Service.

Risposta

La risposta include tre set di dati (limit=3) che mostrano "name", "description" e "schemaRef" come indicato dal parametro di query properties.

{
    "5b95b155419ec801e6eee780": {
        "name": "Store Transactions",
        "description": "Retails Store Transactions",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c351fa2f5fee300000fa9e8": {
        "name": "Loyalty Members",
        "description": "Loyalty Program Members",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c1823b19e6f400000993885": {
        "name": "Web Traffic",
        "description": "Retail Web Traffic",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/2025a705890c6d4a4a06b16f8cf6f4ca",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    }
}

Visualizza schema set di dati

La proprietà "schemaRef" di un set di dati contiene un URI che fa riferimento allo schema XDM su cui è basato il set di dati. Lo schema XDM ("schemaRef") rappresenta tutti i campi potenziali che potrebbero essere utilizzati dal set di dati, non necessariamente i campi in uso (vedi "observableSchema" di seguito).

Lo schema XDM è lo schema utilizzato quando devi presentare all’utente un elenco di tutti i campi disponibili in cui è possibile scrivere.

Il primo valore "schemaRef.id" nell'oggetto di risposta precedente (https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18) è un URI che punta a uno schema XDM specifico in Schema Registry. È possibile recuperare lo schema effettuando una richiesta di ricerca (GET) all'API Schema Registry.

Formato API

GET /schemaregistry/tenant/schemas/{url encoded schemaRef.id}

Richiesta

La richiesta utilizza l'URI id codificato dall'URL dello schema (il valore dell'attributo "schemaRef.id") e richiede un'intestazione Accept.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/https%3A%2F%2Fns.adobe.com%2F{TENANT_ID}%2Fschemas%2F274f17bc5807ff307a046bab1489fb18 \
  -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}' \
  -H 'Accept: application/vnd.adobe.xed-full+json; version=1' \

Il formato della risposta dipende dal tipo di intestazione Accept inviata nella richiesta. Le richieste di ricerca richiedono anche l'inclusione di version nell'intestazione Accept. La tabella seguente illustra le intestazioni Accept per le ricerche:

Risposta

Lo schema JSON restituito descrive la struttura e le informazioni a livello di campo ("type", "format", "minimum", "maximum", ecc.) dei dati, serializzati come JSON. Se per l'acquisizione si utilizza un formato di serializzazione diverso da JSON (ad esempio Parquet o Scala), la Guida al registro dello schema contiene una tabella che mostra il tipo JSON desiderato ("meta:xdmType") e la corrispondente rappresentazione in altri formati.

Insieme a questa tabella, la Guida per gli sviluppatori di Schema Registry contiene esempi dettagliati di tutte le possibili chiamate che possono essere effettuate utilizzando l'API Schema Registry.

Proprietà "schema" del set di dati (OBSOLETO - Fine del ciclo di vita 2019-05-30)

I set di dati possono contenere una proprietà "schema" che ora è obsoleta e rimane temporaneamente disponibile per compatibilità con le versioni precedenti. Ad esempio, una richiesta di inserimento (GET) simile a quella effettuata in precedenza, in cui "schema" è stato sostituito da "schemaRef" nel parametro di query properties, potrebbe restituire quanto segue:

{
  "5ba9452f7de80400007fc52a": {
    "name": "Sample Dataset 1",
    "description": "Description of Sample Dataset 1.",
    "schema": "@/xdms/context/person"
  }
}

Se la proprietà "schema" di un set di dati è compilata, ciò segnala che lo schema è uno schema /xdms obsoleto e, se supportato, il connettore ETL deve utilizzare il valore nella proprietà "schema" con l'endpoint /xdms (un endpoint obsoleto in Catalog API) per recuperare lo schema legacy.

Formato API

GET /catalog/{"schema" property without the "@"}

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/catalog/xdms/context/person?expansion=xdm" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Risposta

Analogamente ai passaggi per visualizzare lo schema del set di dati, la risposta contiene uno schema JSON che descrive la struttura e le informazioni a livello di campo dei dati, serializzati come JSON.

La proprietà "observableSchema"

La proprietà "observableSchema" di un set di dati ha una struttura JSON corrispondente a quella dello schema XDM JSON. "observableSchema" contiene i campi presenti nei file di input in ingresso. Durante la scrittura dei dati in Experience Platform, non è necessario che un utente utilizzi tutti i campi dello schema di destinazione. Dovrebbero invece fornire solo i campi in uso.

Lo schema osservabile è lo schema che utilizzeresti per leggere i dati o presentare un elenco di campi disponibili per la lettura o la mappatura da.

{
    "598d6e81b2745f000015edcb": {
        "observableSchema": {
            "type": "object",
            "meta:xdmType": "object",
            "properties": {
                "name": {
                    "type": "string",
                },
                "age": {
                    "type": "string",
                }
            }
        }
    }
}

Anteprima dati

L'applicazione ETL potrebbe fornire la funzionalità di anteprima dei dati ("Figura 8" nel flusso di lavoro ETL). L’API di accesso ai dati offre diverse opzioni per l’anteprima dei dati.

Ulteriori informazioni, incluse le istruzioni dettagliate per l'anteprima dei dati tramite l'API di accesso ai dati, sono disponibili nell'esercitazione sull'accesso ai dati.

Ottenere i dettagli del set di dati utilizzando il parametro di query "properties"

Come mostrato nei passaggi precedenti per visualizzare un elenco di set di dati, puoi richiedere "file" utilizzando il parametro di query "properties".

Per informazioni dettagliate sull'esecuzione di query sui set di dati e sui filtri di risposta disponibili, è possibile fare riferimento alla panoramica di Catalog Service.

Formato API

GET /catalog/dataSets?limit={value}&properties={value}

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=1&properties=files" \
  -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

La risposta includerà un set di dati (limit=1) che mostra la proprietà "files".

{
  "5bf479a6a8c862000050e3c7": {
    "files": "@/dataSetFiles?dataSetId=5bf479a6a8c862000050e3c7"
  }
}

Elencare i file dei set di dati utilizzando l’attributo "files"

Puoi anche utilizzare una richiesta GET per recuperare i dettagli del file utilizzando l’attributo "files".

Formato API

GET /catalog/dataSets/{DATASET_ID}/views/{VIEW_ID}/files

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/5bf479a6a8c862000050e3c7/views/5bf479a654f52014cfffe7f1/files" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Risposta

La risposta include l’ID file del set di dati come proprietà di livello principale, con i dettagli del file contenuti nell’oggetto ID file del set di dati.

{
    "194e89b976494c9c8113b968c27c1472-1": {
        "batchId": "194e89b976494c9c8113b968c27c1472",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542749145828,
        "updated": 1542749145828
    },
    "14d5758c107443e1a83c714e56ca79d0-1": {
        "batchId": "14d5758c107443e1a83c714e56ca79d0",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542752699111,
        "updated": 1542752699111
    },
    "ea40946ac03140ec8ac4f25da360620a-1": {
        "batchId": "ea40946ac03140ec8ac4f25da360620a",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542756935535,
        "updated": 1542756935535
    }
}

Recupera dettagli file

Gli ID file del set di dati restituiti nella risposta precedente possono essere utilizzati in una richiesta GET per recuperare ulteriori dettagli del file tramite l'API Data Access.

La panoramica sull'accesso ai dati contiene dettagli sull'utilizzo dell'API Data Access.

Formato API

GET /export/files/{DATASET_FILE_ID}

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Risposta

[
    {
    "name": "{FILE_NAME}.parquet",
    "length": 2576,
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet"
            }
        }
    }
]

Anteprima dati file

La proprietà "href" può essere utilizzata per recuperare i dati di anteprima tramite Data Access API.

Formato API

GET /export/files/{FILE_ID}?path={FILE_NAME}.{FILE_FORMAT}

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

La risposta alla richiesta di cui sopra conterrà un’anteprima del contenuto del file.

Ulteriori informazioni sull'API Data Access, incluse richieste e risposte dettagliate, sono disponibili nella panoramica sull'accesso ai dati.

Ottieni "fileDescription" dal set di dati

Il componente di destinazione come output di dati trasformati. L'ingegnere dati sceglierà un set di dati di output ("Figura 12" nel flusso di lavoro ETL). Lo schema XDM è associato al set di dati di output. I dati da scrivere saranno identificati dall’attributo "fileDescription" dell’entità set di dati dalle API di individuazione dati. Queste informazioni possono essere recuperate utilizzando un ID set di dati ({DATASET_ID}). La proprietà "fileDescription" nella risposta JSON fornirà le informazioni richieste.

Formato API

GET /catalog/dataSets/{DATASET_ID}

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/59c93f3da7d0c00000798f68" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"

Risposta

{
  "59c93f3da7d0c00000798f68": {
    "version": "1.0.4",
    "fileDescription": {
        "persisted": false,
        "format": "parquet"
    }
  }
}

I dati verranno scritti in Experience Platform utilizzando l'API di acquisizione batch. La scrittura dei dati è un processo asincrono. Quando i dati vengono scritti in Adobe Experience Platform, viene creato un batch contrassegnato come completato solo dopo che i dati sono stati scritti completamente.

I dati in Experience Platform devono essere scritti sotto forma di file Parquet.

Fase di esecuzione

All'avvio dell'esecuzione, il connettore (come definito nel componente di origine) leggerà i dati da Experience Platform utilizzando Data Access API. Il processo di trasformazione legge i dati per un determinato intervallo di tempo. Internamente, eseguirà query su batch di set di dati di origine. Durante l’esecuzione della query, utilizzerà una data di inizio con parametri (continua per i dati di serie temporali o i dati incrementali) ed elencherà i file di set di dati per tali batch, e inizierà ad effettuare richieste di dati per tali file di set di dati.

Esempio di trasformazioni

Il documento trasformazioni ETL di esempio contiene diverse trasformazioni di esempio, tra cui la gestione delle identità e le mappature dei tipi di dati. Utilizza queste trasformazioni come riferimento.

Leggi dati da Experience Platform

Utilizzando Catalog API, è possibile recuperare tutti i batch tra un'ora di inizio e un'ora di fine specificate e ordinarli in base all'ordine di creazione.

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?dataSet=DATASETID&createdAfter=START_TIMESTAMP&createdBefore=END_TIMESTAMP&sort=desc:created" \
  -H "Accept: 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}"

I dettagli sul filtraggio dei batch sono disponibili nell'esercitazione Accesso ai dati.

Estrarre file da un batch

Una volta ottenuto l'ID per il batch che si sta cercando ({BATCH_ID}), è possibile recuperare un elenco di file appartenenti a un batch specifico tramite Data Access API. I dettagli relativi sono disponibili nell'Data Access esercitazione.

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/files" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Accedere ai file tramite ID file

Utilizzando l'ID univoco di un file ({FILE_ID), è possibile utilizzare Data Access API per accedere ai dettagli specifici del file, tra cui il nome, la dimensione in byte e un collegamento per scaricarlo.

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/export/files/{FILE_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

La risposta può puntare a un singolo file o a una directory. I dettagli su ciascuno sono disponibili nell'Data Access esercitazione.

Accedere al contenuto dei file

Data Access API può essere utilizzato per accedere al contenuto di un file specifico. Per recuperare il contenuto, viene effettuata una richiesta GET utilizzando il valore restituito per _links.self.href quando si accede a un file utilizzando l'ID file.

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/export/files/{DATASET_FILE_ID}?path=filename1.csv" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

La risposta a questa richiesta contiene il contenuto del file. Per ulteriori informazioni, inclusi i dettagli sull'impaginazione delle risposte, vedere l'esercitazione How to Query Data via Data Access API.

Convalidare i record per la conformità allo schema

Durante la scrittura dei dati, gli utenti possono scegliere di convalidare i dati in base alle regole di convalida definite nello schema XDM. Ulteriori informazioni sulla convalida dello schema sono disponibili nel Codice di riferimento per l'integrazione dell'ecosistema ETL in data GitHub.

Se si utilizza l'implementazione di riferimento trovata in GitHub, è possibile attivare la convalida dello schema in questa implementazione utilizzando la proprietà di sistema -DenableSchemaValidation=true.

È possibile eseguire la convalida per i tipi XDM logici, utilizzando attributi quali minLength e maxlength per le stringhe, minimum e maximum per i numeri interi e altro ancora. La Guida per gli sviluppatori API del Registro di schema contiene una tabella che illustra i tipi XDM e le proprietà che possono essere utilizzati per la convalida.

Creare un batch

Una volta elaborati i dati, lo strumento ETL riscriverà i dati in Experience Platform utilizzando l'API Batch Ingestion. Prima di poter aggiungere dati a un set di dati, questi devono essere collegati a un batch che verrà successivamente caricato in un set di dati specifico.

Richiesta

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -d '{
        "datasetId":"{DATASET_ID}"
      }'

I dettagli per la creazione di un batch, incluse le richieste e le risposte di esempio, sono disponibili nella Panoramica sull'acquisizione batch.

Scrivi nel set di dati

Dopo aver creato correttamente un nuovo batch, i file possono quindi essere caricati in un set di dati specifico. È possibile registrare più file in un batch fino a quando non viene promosso. I file possono essere caricati utilizzando l’API di caricamento file di piccole dimensioni; tuttavia, se i file sono troppo grandi e il limite del gateway è superato, puoi utilizzare l’API di caricamento file di grandi dimensioni. I dettagli relativi all'utilizzo di Caricamento di file di grandi e piccole dimensioni sono disponibili nella Panoramica sull'acquisizione in batch.

Richiesta

I dati in Experience Platform devono essere scritti sotto forma di file Parquet.

curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/dataSets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id:{ORG_ID}" \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -H "x-api-key: API_KEY" \
  -H "content-type: application/octet-stream" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Contrassegna caricamento batch come completato

Dopo che tutti i file sono stati caricati nel batch, il batch può essere segnalato per il completamento. In questo modo, vengono create le voci "DataSetFile" Catalog per i file completati e associate al batch generato. Il batch Catalog è quindi contrassegnato come riuscito, che attiva i flussi a valle per acquisire i dati disponibili.

I dati verranno prima recapitati nel percorso di gestione temporanea in Adobe Experience Platform e quindi spostati nel percorso finale dopo la catalogazione e la convalida. I batch verranno contrassegnati come completati quando tutti i dati vengono spostati in una posizione permanente.

Richiesta

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization:Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

In caso di esito positivo, la risposta restituirà lo stato HTTP 200 OK e il corpo della risposta sarà vuoto.

Lo strumento ETL farà in modo di annotare la marca temporale dei set di dati sorgente durante la lettura dei dati.

Nella successiva esecuzione della trasformazione, probabilmente tramite la pianificazione o la chiamata dell’evento, l’ETL inizierà a richiedere i dati dalla marca temporale salvata in precedenza e tutti i dati andranno avanti.

Ottieni ultimo stato batch

Prima di eseguire nuove attività nello strumento ETL, è necessario verificare che l'ultimo batch sia stato completato correttamente. Catalog Service API fornisce un'opzione specifica del batch che fornisce i dettagli dei batch rilevanti.

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?limit=1&sort=desc:created" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Risposta

È possibile pianificare nuove attività se il valore "status" del batch precedente è "success", come illustrato di seguito:

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "CLIENT_USER_ID@AdobeID",
    "updatedUser": "CLIENT_USER_ID@AdobeID",
    "updated": 1494349963467,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

Ottieni ultimo stato batch per ID

È possibile recuperare un singolo stato batch tramite Catalog Service API emettendo una richiesta GET utilizzando {BATCH_ID}. L'ID {BATCH_ID} utilizzato corrisponderebbe all'ID restituito al momento della creazione del batch.

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Risposta - Completata

La seguente risposta mostra un "successo":

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

Risposta - Errore

In caso di errore, gli "errori" possono essere estratti dalla risposta e visualizzati sullo strumento ETL come messaggi di errore.

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "failure",
    "errors": [
        {
            "code": "200",
            "description": "Error in validating schema for file: 'adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv' with errorMessage=adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv is not a Parquet file. expected magic number at tail [80, 65, 82, 49] but found [57, 98, 55, 10] and errorType=java.lang.RuntimeException",
            "rows": []
        }
    ],
    "version": "1.0.1",
    "availableDates": {}
}

Dati ed eventi incrementali e snapshot rispetto ai profili

I dati possono essere rappresentati in una matrice due per due nel modo seguente:

I dati dell’evento si riferiscono in genere a colonne di marca temporale indicizzate in ogni riga.

I dati del profilo si riferiscono in genere a quando nei dati non è presente una marca temporale e ogni riga può essere identificata da una chiave primaria/composita.

I dati incrementali sono il luogo in cui solo i dati nuovi/aggiornati entrano nel sistema e si aggiungono ai dati correnti nei set di dati.

I dati di snapshot si verificano quando tutti i dati entrano nel sistema e sostituiscono alcuni o tutti i dati precedenti in un set di dati.

In caso di eventi incrementali, lo strumento ETL deve utilizzare le date disponibili/la data di creazione dell’entità batch. In caso di servizio push, le date disponibili non saranno presenti, pertanto lo strumento utilizzerà la data di creazione/aggiornamento batch per contrassegnare gli incrementi. Ogni batch di eventi incrementali deve essere elaborato.

Per i profili incrementali, lo strumento ETL utilizzerà le date create/aggiornate dell’entità batch. Di solito è necessario elaborare ogni batch di dati di profilo incrementali.

Gli eventi snapshot sono molto meno probabili a causa delle dimensioni dei dati. Tuttavia, se questo fosse necessario, lo strumento ETL deve scegliere solo l'ultimo batch per l'elaborazione.

Quando si utilizzano i profili snapshot, lo strumento ETL dovrà scegliere l'ultimo batch di dati che è arrivato nel sistema. Tuttavia, se è necessario tenere traccia delle versioni delle modifiche, tutti i batch dovranno essere elaborati. L'elaborazione della deduplicazione all'interno del processo ETL contribuirà al controllo dei costi di storage.

Ripetizione batch e rielaborazione dati

La ripetizione in batch e la rielaborazione dei dati possono essere necessarie nei casi in cui un client rilevi che negli ultimi "n" giorni i dati elaborati da ETL non si sono verificati come previsto o i dati sorgente stessi potrebbero non essere corretti.

A tale scopo, gli amministratori dei dati del client utilizzeranno l'interfaccia utente Platform per rimuovere i batch contenenti dati danneggiati. Successivamente, sarà probabilmente necessario eseguire nuovamente l’ETL, popolandolo nuovamente con dati corretti. Se l’origine stessa contiene dati danneggiati, il data engineer/amministratore dovrà correggere i batch di origine e riacquisire i dati (in Adobe Experience Platform o tramite connettori ETL).

In base al tipo di dati generato, sarà il data engineer a scegliere di rimuovere un singolo batch o tutti i batch da determinati set di dati. I dati verranno rimossi/archiviati in base alle linee guida di Experience Platform.

È probabile che la funzionalità ETL per eliminare i dati sia importante.

Una volta completata la rimozione, gli amministratori client dovranno riconfigurare Adobe Experience Platform per riavviare l’elaborazione dei servizi core dal momento in cui i batch vengono eliminati.

Elaborazione batch simultanea

A discrezione del cliente, gli amministratori/ingegneri dei dati possono decidere di estrarre, trasformare e caricare i dati in modo sequenziale o simultaneo a seconda delle caratteristiche di un particolare set di dati. Questo sarà anche basato sul caso di utilizzo in cui il client esegue il targeting con i dati trasformati.

Ad esempio, se il client persiste in un archivio di persistenza aggiornabile e la sequenza o l’ordine degli eventi è importante, il client potrebbe dover elaborare rigorosamente i processi con trasformazioni ETL sequenziali.

In altri casi, i dati fuori servizio possono essere elaborati da applicazioni/processi a valle che ordinano internamente utilizzando una marca temporale specificata. In questi casi, le trasformazioni parallele dell’ETL possono essere attuabili per migliorare i tempi di elaborazione.

Per i batch di origine, dipenderà nuovamente dalle preferenze del client e dal vincolo del consumatore. Se i dati di origine possono essere rilevati in parallelo senza considerare la reggenza o l’ordinamento di una riga, il processo di trasformazione può creare batch di processi con un grado più elevato di parallelismo (ottimizzazione basata sull’elaborazione fuori ordine). Tuttavia, se la trasformazione deve rispettare i timestamp o modificare l’ordine di precedenza, l’API di accesso ai dati o l’utilità di pianificazione/chiamata dello strumento ETL dovranno garantire che i batch non vengano elaborati fuori ordine, ove possibile.

Differimento

Il rinvio è un processo in cui i dati di input non sono ancora abbastanza completi da essere inviati ai processi a valle, ma possono essere utilizzati in futuro. I clienti determineranno la propria tolleranza individuale alla finitura dei dati per una corrispondenza futura rispetto al costo dell’elaborazione per informare la decisione di mettere da parte i dati e rielaborarli nella successiva esecuzione della trasformazione, sperando che possano essere arricchiti e riconciliati/uniti in un momento futuro all’interno della finestra di conservazione. Questo ciclo è in corso fino a quando la riga non viene elaborata a sufficienza o si ritiene che sia troppo obsoleta per continuare a investire in. Ogni iterazione genera dati differiti che sono un superset di tutti i dati differiti delle iterazioni precedenti.

Al momento Adobe Experience Platform non identifica i dati differiti, pertanto le implementazioni client devono basarsi sulle configurazioni manuali ETL e Dataset per creare un altro set di dati in Platform che rispecchia il set di dati di origine e può essere utilizzato per conservare i dati differiti. In questo caso, i dati differiti saranno simili ai dati snapshot. In ogni esecuzione della trasformazione ETL, i dati di origine verranno uniti ai dati differiti e inviati per l’elaborazione.

Changelog