Sviluppo di integrazioni ETL per Adobe Experience Platform

La guida all’integrazione ETL descrive i passaggi generali per la creazione di connettori sicuri e ad alte 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 l’utilizzo della relativa API, in modo più dettagliato.

Un esempio di integrazione è disponibile su GitHub tramite il Codice di riferimento per l’integrazione dell’ecosistema ETL nella Apache licenza versione 2.0.

Flusso di lavoro

Il seguente diagramma del flusso di lavoro fornisce una panoramica di alto livello sull’integrazione dei componenti Adobe Experience Platform con un’applicazione e un connettore ETL.

Componenti Adobe Experience Platform

Sono presenti più componenti di Experience Platform coinvolti nelle integrazioni dei connettori ETL. L’elenco seguente illustra diversi componenti e funzionalità chiave:

  • Adobe Identity Management System (IMS) - Fornisce il framework per l’autenticazione ai servizi di Adobe.
  • Organizzazione IMS : un'entità aziendale che può possedere o concedere in licenza prodotti e servizi e consentire l'accesso ai propri membri.
  • Utente IMS : membri di un’organizzazione IMS. La relazione tra l'organizzazione e l'utente è molto importante per molti.
  • Sandbox - Una partizione virtuale una singola Platform istanza, per aiutare a sviluppare e sviluppare applicazioni di esperienza digitale.
  • Individuazione dati - Registra i metadati dei dati acquisiti e trasformati in Experience Platform.
  • Data Access - Fornisce agli utenti un'interfaccia per accedere ai loro dati in Experience Platform.
  • Data Ingestion - Invia dati a Experience Platform con Data Ingestion API.
  • Schema Registry - Definisce e memorizza lo schema che descrive la struttura dei dati da utilizzare in Experience Platform.

Guida introduttiva alle API Experience Platform

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

Lettura di chiamate API di esempio

Questa guida 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:

  • Autorizzazione: Portatore {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

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

  • nome x-sandbox: {SANDBOX_NAME}
NOTA

Per ulteriori informazioni sulle sandbox in Platform, consulta la documentazione di panoramica sandbox.

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

  • Tipo di contenuto: application/json

Flusso utente generale

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

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) che viene acquisito in Platform. Facendo clic sulla scheda Schemi nell’interfaccia utente, l’utente sarà in grado di visualizzare tutti gli schemi disponibili, compreso 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 proprie credenziali). Si presume che lo strumento ETL abbia già installato Experience Platform connettori (processo non definito in questa Guida all'integrazione).

Sono stati forniti mapping per uno strumento e un flusso di lavoro ETL di esempio nel flusso di lavoro ETL. Anche se gli strumenti ETL possono differire nel formato, la maggior parte espone funzionalità simili.

NOTA

Il connettore ETL deve specificare un filtro di marca temporale che contrassegna la data in cui acquisire i dati e l’offset (ovvero la finestra per la quale i dati devono essere letti). Lo strumento ETL dovrebbe supportare l’acquisizione di questi due parametri in questa o in un’altra interfaccia utente pertinente. In Adobe Experience Platform, questi parametri verranno mappati alle date disponibili (se presenti) o alla data acquisita presente nell’oggetto batch del set di dati.

Visualizza elenco di set di dati

Utilizzando l’origine dei dati per la mappatura, è possibile recuperare un elenco di tutti i set di dati disponibili utilizzando il percorso Catalog API.

Puoi emettere una singola richiesta API per visualizzare tutti i set di dati disponibili (ad esempio GET /dataSets), come best practice, include parametri di query che limitano la dimensione della risposta.

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

Filtro elenco

Quando filtri le risposte, puoi 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, come il filtro "proprietà" nella richiesta di esempio seguente.

Catalog le 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 preconfigurati Catalog sono i seguenti:

  • Se non viene specificato un parametro di limite, il numero massimo di oggetti per payload di risposta è 20.
  • Il limite globale per tutte le altre query Catalog è di 100 oggetti.
  • Per le query dei set di dati, se si richiede OsservableSchema utilizzando il parametro di query delle proprietà, il numero massimo di set di dati restituiti è 20.
  • I parametri di limite non validi (incluso limit=0) sono soddisfatti con un errore HTTP 400 che delinea gli intervalli appropriati.
  • Se i limiti o gli offset vengono passati come parametri di query, hanno la precedenza su quelli passati come intestazioni.

I parametri di query sono descritti più dettagliatamente in Panoramica del servizio catalogo.

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

Per esempi dettagliati su come effettuare chiamate a Catalog API, consulta la Panoramica del servizio catalogo .

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 possono essere utilizzati dal set di dati, non necessariamente i campi in uso (vedi "osservableSchema" di seguito).

Lo schema XDM è lo schema utilizzato quando è necessario 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 nel Schema Registry. Lo schema può essere recuperato effettuando una richiesta di ricerca (GET) all'API Schema Registry.

NOTA

La proprietà "schemaRef" sostituisce la proprietà "schema" ora obsoleta. Se "schemaRef" è assente dal set di dati o non contiene un valore, dovrai verificare la presenza di una proprietà "schema". Questo può essere fatto sostituendo "schemaRef" con "schema" nel parametro di query properties nella chiamata precedente. Ulteriori dettagli sulla proprietà "schema" sono disponibili nella sezione Dataset "schema" Property che segue.

Formato API

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

Richiesta

La richiesta utilizza l’URI codificato URL id 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: {IMS_ORG}' \
  -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 inviato nella richiesta. Le richieste di ricerca richiedono anche l’inclusione di un elemento version nell’intestazione Accept. La tabella seguente illustra le intestazioni Accept disponibili per le ricerche:

Accept Descrizione
application/vnd.adobe.xed-id+json Richieste elenco (GET), titoli, id e versioni
application/vnd.adobe.xed-full+json; version={major version} $refs e allOf risolti, ha titoli e descrizioni
application/vnd.adobe.xed+json; version={major version} Raw con $ref e allOf, ha titoli e descrizioni
application/vnd.adobe.xed-notext+json; version={major version} Raw con $ref e allOf, senza titoli o descrizioni
application/vnd.adobe.xed-full-notext+json; version={major version} $refs e allOf risolti, senza titoli o descrizioni
application/vnd.adobe.xed-full-desc+json; version={major version} $refs e allOf risolti, descrittori inclusi
NOTA

application/vnd.adobe.xed-id+json e application/vnd.adobe.xed-full+json; version={major version} sono le intestazioni Accept più comunemente utilizzate. application/vnd.adobe.xed-id+json è da preferire per elencare le risorse in Schema Registry quanto restituisce solo "title", "id" e "version". application/vnd.adobe.xed-full+json; version={major version} è da preferirsi per visualizzare una risorsa specifica (in base al suo "id"), in quanto restituisce tutti i campi (nidificati sotto "proprietà"), nonché titoli e descrizioni.

Risposta

Lo schema JSON restituito descrive la struttura e le informazioni a livello di campo ("tipo", "formato", "minimo", "massimo", ecc.) dei dati, serializzati come JSON. Se utilizzi un formato di serializzazione diverso da JSON per l’acquisizione (ad esempio Parquet o Scala), la Guida al Registro di sistema dello schema contiene una tabella che mostra il tipo JSON desiderato ("meta:xdmType") e la relativa rappresentazione corrispondente in altri formati.

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

Proprietà "schema" del set di dati (OBSOLETO - EOL 2019-05-30)

I set di dati possono contenere una proprietà "schema" che ora è obsoleta e rimane temporaneamente disponibile per la compatibilità con le versioni precedenti. Ad esempio, una richiesta di elenco (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, questo 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: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
NOTA

Un parametro di query facoltativo, expansion=xdm, indica all’API di espandere completamente e in linea tutti gli schemi di riferimento. È consigliabile eseguire questa operazione quando si presenta all’utente un elenco di tutti i campi potenziali.

Risposta

Simile 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.

NOTA

Quando il campo "schema" è completamente vuoto o assente, il connettore deve leggere il campo "schemaRef" e utilizzare l' API del Registro di sistema dello schema come mostrato nei passaggi precedenti per visualizzare uno schema di set di dati.

Proprietà "osservableSchema"

La proprietà "osservableSchema" di un set di dati presenta una struttura JSON corrispondente a quella dello schema XDM JSON. Lo "schema osservabile" contiene i campi presenti nei file di input in arrivo. Quando si scrivono dati a Experience Platform, non è necessario che un utente utilizzi ogni campo dello schema di destinazione. Dovrebbero invece fornire solo i campi in uso.

Lo schema osservabile è lo schema da utilizzare per la lettura dei dati o la presentazione di un elenco di campi disponibili per la lettura/mappatura.

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

Anteprima dati

L'applicazione ETL può fornire una capacità di visualizzare in anteprima i dati ("Figura 8" nel flusso di lavoro ETL). L’API di accesso ai dati fornisce diverse opzioni per l’anteprima dei dati.

Ulteriori informazioni, incluse istruzioni dettagliate per visualizzare in anteprima i dati utilizzando l'API di accesso ai dati, sono disponibili nell' tutorial sull'accesso ai dati.

Ottieni 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 sulla query dei set di dati e sui filtri di risposta disponibili, consulta la Panoramica del servizio catalogo .

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

Risposta

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

{
  "5bf479a6a8c862000050e3c7": {
    "files": "@/dataSets/5bf479a6a8c862000050e3c7/views/5bf479a654f52014cfffe7f1/files"
  }
}

Elencare file di 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: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

Risposta

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

{
    "194e89b976494c9c8113b968c27c1472-1": {
        "batchId": "194e89b976494c9c8113b968c27c1472",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{IMS_ORG}",
        "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": "{IMS_ORG}",
        "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": "{IMS_ORG}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542756935535,
        "updated": 1542756935535
    }
}

Dettagli del file di recupero

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

La panoramica sull'accesso ai dati contiene informazioni dettagliate su come utilizzare l'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: {IMS_ORG}" \
  -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: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

La risposta alla richiesta di cui sopra contiene 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, data engineer sceglierà un set di dati di output ("Figure 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à di 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}
Proprietà Descrizione
{DATASET_ID} Il valore id del set di dati a cui si sta tentando di accedere.

Richiesta

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/59c93f3da7d0c00000798f68" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-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 API di acquisizione dati. La scrittura di dati è un processo asincrono. Quando i dati vengono scritti in Adobe Experience Platform, un batch viene creato e contrassegnato come un successo 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 di Experience Platform utilizzando Data Access API. Il processo di trasformazione leggerà i dati per un determinato intervallo di tempo. Internamente, eseguirà query sui batch di set di dati di origine. Durante l’esecuzione delle query, utilizzerà un valore parametrizzato (che continua per i dati delle serie temporali o i dati incrementali) per la data di inizio e i file di set di dati per tali batch, quindi inizierà a richiedere i dati per tali file di set di dati.

Trasformazioni di esempio

Il documento trasformazioni ETL di esempio contiene una serie di trasformazioni di esempio, tra cui la gestione dell'identità e le mappature del tipo di dati. Usa queste trasformazioni per riferimento.

Leggi i dati da Experience Platform

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

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

I dettagli sui batch di filtri si trovano in Esercitazione sull'accesso ai dati.

Estrarre file da un batch

Una volta ottenuto l'ID per il batch che stai cercando ({BATCH_ID}), è possibile recuperare un elenco di file appartenenti a un batch specifico tramite Data Access API. I dettagli per farlo 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: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key : {API_KEY}"

Accedere ai file utilizzando l’ID file

Utilizzando l'ID univoco di un file ({FILE_ID), è possibile utilizzare Data Access API per accedere ai dettagli specifici del file, inclusi nome, dimensioni 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: {IMS_ORG}" \
  -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 di essi sono disponibili nel tutorial Data Access tutorial.

Accedere al contenuto del file

È possibile utilizzare Data Access API per accedere al contenuto di un file specifico. Per recuperare il contenuto, viene effettuata una richiesta di 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: {IMS_ORG}" \
  -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, compresi i dettagli sull'impaginazione delle risposte, consulta l' esercitazione Come eseguire query sui dati tramite API di accesso ai dati .

Convalida dei record per la conformità allo schema

Quando i dati vengono scritti, 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 su GitHub.

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

La convalida può essere eseguita per i tipi XDM logici, utilizzando attributi come 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 sistema dello schema contiene una tabella che descrive i tipi XDM e le proprietà che possono essere utilizzate per la convalida.

NOTA

I valori minimo e massimo forniti per vari tipi integer sono i valori MIN e MAX che il tipo può supportare, ma questi valori possono essere ulteriormente vincolati a valori minimi e massimi scelti.

Creare un batch

Una volta elaborati i dati, lo strumento ETL restituirà i dati a Experience Platform utilizzando l’ API di acquisizione batch. 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: {IMS_ORG}" \
  -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 di esempio e le risposte, sono disponibili nella Panoramica sull'acquisizione in 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 pubblicare 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 viene superato, puoi utilizzare l’API di caricamento file di grandi dimensioni. I dettagli sull'utilizzo di Caricamento 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:{IMS_ORG}" \
  -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 completato

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

I dati verranno prima trasferiti nella posizione di staging su Adobe Experience Platform e quindi spostati nella posizione finale dopo la catalogazione e la convalida. I batch verranno contrassegnati come completati una volta che tutti i dati saranno stati 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: {IMS_ORG}" \
  -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 si accerterà di annotare la marca temporale dei set di dati di origine durante la lettura dei dati.

Nell’esecuzione della trasformazione successiva, probabilmente per pianificazione o chiamata dell’evento, l’ETL inizierà a richiedere i dati dalla marca temporale salvata in precedenza e tutti i dati in corso.

Ottieni stato ultimo batch

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

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: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Risposta

È possibile programmare nuove attività se il precedente valore di "stato" del batch è "successo", come illustrato di seguito:

"{BATCH_ID}": {
    "imsOrg": "{IMS_ORG}",
    "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 stato ultimo batch per ID

È possibile recuperare uno stato batch singolo attraverso Catalog Service API emettendo una richiesta di GET utilizzando {BATCH_ID}. Il {BATCH_ID} utilizzato corrisponde 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: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Risposta - Operazione riuscita

La risposta seguente mostra un "successo":

"{BATCH_ID}": {
    "imsOrg": "{IMS_ORG}",
    "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": "{IMS_ORG}",
    "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 e profili

I dati possono essere rappresentati in due da due matrici come segue:

Eventi incrementali Profili incrementali
Eventi di snapshot (con minore probabilità) Profili snapshot

I dati evento sono in genere presenti nelle colonne di marca temporale indicizzate di ogni riga.

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

I dati incrementali sono il punto in cui solo i dati nuovi/aggiornati vengono inseriti nel sistema e vengono aggiunti ai dati correnti nei set di dati.

I dati snapshot vengono generati quando tutti i dati vengono inseriti nel sistema e sostituiscono alcuni o tutti i dati precedenti in un set di dati.

Nel caso di eventi incrementali, lo strumento ETL deve utilizzare le date disponibili/creare la data dell’entità batch. Nel caso del servizio push, le date disponibili non saranno presenti, quindi lo strumento utilizzerà la data di creazione/aggiornamento in batch per contrassegnare gli incrementi. È necessario elaborare ogni batch di eventi incrementali.

Per i profili incrementali, lo strumento ETL utilizzerà date create/aggiornate di entità batch. Di solito, ogni batch di dati di profilo incrementali deve essere elaborato.

Gli eventi snapshot sono molto meno probabili a causa della dimensione pura dei dati. Tuttavia, se ciò dovesse essere necessario, lo strumento ETL deve selezionare solo l'ultimo batch da elaborare.

Quando si utilizzano i profili di snapshot, lo strumento ETL dovrà scegliere l'ultimo batch di dati arrivati nel sistema. Ma se il requisito è quello di tenere traccia delle versioni delle modifiche, tutti i batch saranno tenuti ad essere elaborati. L'elaborazione della deduplicazione all'interno del processo ETL contribuirà a controllare i costi di storage.

Riproduzione in batch e rielaborazione dei dati

La riproduzione in batch e la rielaborazione dei dati possono essere necessarie nei casi in cui un cliente scopra che, negli ultimi "n" giorni, i dati in fase di elaborazione ETL non si sono verificati come previsto o che i dati sorgente stessi potrebbero non essere stati corretti.

A questo scopo, gli amministratori di dati del client utilizzeranno l’ Platform interfaccia utente per rimuovere i batch contenenti dati corrotti. Quindi, sarà probabilmente necessario rieseguire l’ETL, ripopolando in tal modo i dati corretti. Se l’origine stessa conteneva dati corrotti, l’ingegnere/amministratore dei dati 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à l’ingegnere dei dati a scegliere di rimuovere un singolo batch o tutti i batch da determinati set di dati. I dati verranno rimossi/archiviati secondo le linee guida Experience Platform .

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

Una volta completata l'eliminazione, gli amministratori client dovranno riconfigurare Adobe Experience Platform per riavviare l'elaborazione dei servizi principali 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 d’uso in cui il cliente 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, potrebbe essere necessario elaborare rigorosamente i processi con trasformazioni ETL sequenziali.

In altri casi, i dati fuori ordine possono essere elaborati da applicazioni/processi a valle che eseguono l’ordinamento interno utilizzando una data marca temporale. In questi casi, le trasformazioni parallele ETL possono essere fattibili per migliorare i tempi di elaborazione.

Per i batch di origine, dipenderà nuovamente dalla preferenza del cliente e dal vincolo del consumatore. Se i dati di origine possono essere raccolti in parallelo senza tenere conto della regenza/ordinamento di una riga, allora il processo di trasformazione può creare batch di processi con un più alto grado di parallelismo (ottimizzazione basata sull'elaborazione fuori ordine). Tuttavia, se la trasformazione deve rispettare timestamp o modificare l’ordine di precedenza, la pianificazione/chiamata dell’API di accesso ai dati o dello strumento ETL dovrà garantire che i batch non vengano elaborati in modo non ordinato, ove possibile.

Differenza

Il differimento è un processo in cui i dati di input non sono ancora abbastanza completi da essere inviati ai processi a valle, ma possono essere utilizzabili in futuro. I clienti determineranno la propria tolleranza individuale per l'ottimizzazione dei dati per future corrispondenze rispetto al costo del trattamento per informare la loro decisione di mettere da parte i dati e rielaborarli nella successiva esecuzione della trasformazione, sperando che possano essere arricchiti e riconciliati/uniti in un futuro momento all'interno della finestra di conservazione. Questo ciclo è in corso fino a quando la riga non viene elaborata a sufficienza o è considerato troppo vecchio per continuare ad investire in. Ogni iterazione genera dati differiti che è un superset di tutti i dati differiti nelle iterazioni precedenti.

Adobe Experience Platform non identifica i dati differiti al momento, pertanto le implementazioni client devono basarsi sulle configurazioni ETL e del manuale del set di dati per creare un altro set di dati in Platform mirroring del set di dati sorgente che può essere utilizzato per mantenere i dati differiti. In questo caso, i dati differiti saranno simili ai dati snapshot. In ogni esecuzione della trasformazione ETL, i dati di origine saranno uniti ai dati differiti e inviati per l’elaborazione.

Changelog

Data Azione Descrizione
01/01/2019 Proprietà "fields" rimossa dai set di dati I set di dati in precedenza includevano una proprietà "field" che conteneva una copia dello schema. Questa funzionalità non deve più essere utilizzata. Se viene trovata la proprietà "fields", ignorarla e utilizzare invece "osservSchema" o "schemaRef".
03/03/2019 proprietà "schemaRef" aggiunta ai 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 e rappresenta tutti i campi potenziali che possono essere utilizzati dal set di dati.
03/03/2019 Tutti gli identificatori dell'utente finale vengono mappati sulla proprietà "identityMap" "identityMap" è un'incapsulazione di tutti gli identificatori univoci di un soggetto, come ID CRM, ECID o ID programma fedeltà. Questa mappa viene utilizzata da Identity Service per risolvere tutte le identità note e anonime di un soggetto, creando un unico grafico di identità per ogni utente finale.
05/05/2019 Fine del ciclo vita e rimozione della proprietà "schema" dai set di dati La proprietà "schema" del set di dati ha fornito un collegamento di riferimento allo schema utilizzando l’endpoint /xdms obsoleto nell’ API Catalog . Questo è stato sostituito da un "schemaRef" che fornisce "id", "version" e "contentType" dello schema come indicato nella nuova API Schema Registry.

In questa pagina