Connetti Data Landing Zone a Adobe Experience Platform utilizzando l’API del servizio Flusso
Data Landing Zone è una struttura di archiviazione dei file sicura e basata su cloud per importare i file in Adobe Experience Platform. I dati vengono eliminati automaticamente dal Data Landing Zone dopo sette giorni.
Questo tutorial illustra i passaggi necessari per creare un Data Landing Zone connessione sorgente tramite Flow Service API. Questo tutorial fornisce anche istruzioni su come recuperare Data Landing Zone, nonché visualizzare e aggiornare le credenziali.
Introduzione
Questa guida richiede una buona conoscenza dei seguenti componenti di Experience Platform:
- Sorgenti: un Experience Platform consente di acquisire dati da varie origini, consentendoti allo stesso tempo di strutturare, etichettare e migliorare i dati in arrivo tramite i servizi di Platform.
- Sandbox: Experienci Platform fornisce sandbox virtuali che permettono di suddividere una singola istanza Platform in ambienti virtuali separati, utili per le attività di sviluppo e aggiornamento delle applicazioni di esperienza digitale.
Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere per creare correttamente un Data Landing Zone connessione sorgente tramite Flow Service API.
Questo tutorial richiede anche di leggere la guida su introduzione alle API di Platform per scoprire come eseguire l’autenticazione nelle API di Platform e interpretare le chiamate di esempio fornite nella documentazione.
Recuperare una zona di destinazione utilizzabile
Il primo passaggio nell’utilizzo delle API per accedere a Data Landing Zone è effettuare una richiesta GET al /landingzone
endpoint del Connectors API durante la fornitura di type=user_drop_zone
come parte dell’intestazione della richiesta.
Formato API
GET /data/foundation/connectors/landingzone?type=user_drop_zone
user_drop_zone
user_drop_zone
Il tipo consente all’API di distinguere un contenitore per zona di destinazione dagli altri tipi di contenitori disponibili.Richiesta
La richiesta seguente recupera una zona di destinazione esistente.
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/landingzone?type=user_drop_zone' \
-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 'Content-Type: application/json'
Risposta
La risposta che segue restituisce informazioni su una zona di atterraggio, compresi i dati corrispondenti containerName
e containerTTL
.
{
"containerName": "dlz-user-container",
"containerTTL": "7"
}
containerName
containerTTL
Recupera Data Landing Zone credenziali
Per recuperare le credenziali per un Data Landing Zone, invia una richiesta GET al /credentials
endpoint del Connectors API.
Formato API
GET /data/foundation/connectors/landingzone/credentials?type=user_drop_zone
Richiesta
L’esempio di richiesta seguente recupera le credenziali per una zona di destinazione esistente.
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone' \
-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 'Content-Type: application/json' \
Risposta
La risposta seguente restituisce le informazioni sulle credenziali per l’area di destinazione dati, inclusa la SASToken
, SASUri
, storageAccountName
e data di scadenza.
{
"containerName": "dlz-user-container",
"SASToken": "sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
"storageAccountName": "dlblobstore99hh25i3dflek",
"SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
"expiryDate": "2024-01-06"
}
containerName
SASToken
SASUri
expiryDate
Aggiorna Data Landing Zone credenziali
È possibile aggiornare SASToken
facendo una richiesta POST al /credentials
endpoint del Connectors API.
Formato API
POST /data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh
user_drop_zone
user_drop_zone
Il tipo consente all’API di distinguere un contenitore per zona di destinazione dagli altri tipi di contenitori disponibili.refresh
refresh
consente di reimpostare le credenziali della zona di destinazione e generare automaticamente un nuovo SASToken
.Richiesta
La richiesta seguente aggiorna le credenziali della zona di destinazione.
curl -X POST \
'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh' \
-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 'Content-Type: application/json' \
Risposta
La seguente risposta restituisce valori aggiornati per il SASToken
e SASUri
.
{
"containerName": "dlz-user-container",
"SASToken": "sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
"storageAccountName": "dlblobstore99hh25i3dflek",
"SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
"expiryDate": "2024-01-06"
}
Esplora la struttura e il contenuto del file della zona di destinazione
Puoi esplorare la struttura del file e il contenuto della zona di destinazione effettuando una richiesta GET al connectionSpecs
endpoint del Flow Service API.
Formato API
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root
{CONNECTION_SPEC_ID}
26f526f2-58f4-4712-961d-e41bf1ccc0e8
.Richiesta
curl -X GET \
'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=root' \
-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
In caso di esito positivo, la risposta restituisce un array di file e cartelle presenti nella directory in cui è stata eseguita la query. Prendi nota della path
del file che desideri caricare, in quanto è necessario fornirlo nel passaggio successivo per esaminarne la struttura.
[
{
"type": "file",
"name": "account.csv",
"path": "dlz-user-container/account.csv",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "file",
"name": "data8.csv",
"path": "dlz-user-container/data8.csv",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "folder",
"name": "userdata1",
"path": "dlz-user-container/userdata1/",
"canPreview": false,
"canFetchSchema": false
}
]
Anteprima della struttura e del contenuto del file della zona di destinazione
Per controllare la struttura di un file nella zona di destinazione, esegui una richiesta di GET fornendo il percorso del file e digita come parametro di query.
Formato API
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}
{CONNECTION_SPEC_ID}
26f526f2-58f4-4712-961d-e41bf1ccc0e8
.{OBJECT_TYPE}
file
{OBJECT}
dlz-user-container/data8.csv
{FILE_TYPE}
delimited
json
parquet
{PREVIEW}
-
true
-
false
Richiesta
curl -X GET \
'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/data8.csv&fileType=delimited&preview=true' \
-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
In caso di esito positivo, la risposta restituisce la struttura del file oggetto della query, inclusi i nomi e i tipi di dati dei file.
{
"format": "flat",
"schema": {
"columns": [
{
"name": "Id",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "FirstName",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "LastName",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Email",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Phone",
"type": "string",
"xdm": {
"type": "string"
}
}
]
},
"data": [
{
"Email": "rsmith@abc.com",
"FirstName": "Richard",
"Phone": "111111111",
"Id": "12345",
"LastName": "Smith"
},
{
"Email": "morgan@bac.com",
"FirstName": "Morgan",
"Phone": "22222222222",
"Id": "67890",
"LastName": "Hart"
}
]
}
Utilizzare determineProperties
per rilevare automaticamente le informazioni sulle proprietà di un file Data Landing Zone
È possibile utilizzare determineProperties
parametro per rilevare automaticamente le informazioni sulle proprietà del contenuto del file Data Landing Zone quando effettui una chiamata di GET per esplorare il contenuto e la struttura dell’origine.
determineProperties
casi di utilizzo
La tabella seguente illustra i diversi scenari che possono verificarsi quando si utilizza determineProperties
parametro di query o fornire manualmente informazioni sul file.
determineProperties
queryParams
determineProperties
viene fornito come parametro di query, viene rilevato il rilevamento delle proprietà del file e la risposta restituisce un nuovo properties
chiave che include informazioni sul tipo di file, sul tipo di compressione e sul delimitatore di colonna.queryParams
, quindi vengono utilizzati per generare lo schema e le stesse proprietà vengono restituite come parte della risposta.Formato API
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true
determineProperties
true
Richiesta
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/garageWeek/file1&preview=true&determineProperties=true' \
-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
In caso di esito positivo, la risposta restituisce la struttura del file oggetto della query, inclusi i nomi e i tipi di dati, nonché una properties
chiave, contenente informazioni su fileType
, compressionType
, e columnDelimiter
.
code language-json |
---|
|
properties.fileType
delimited
, json
, e parquet
.properties.compressionType
Tipo di compressione corrispondente utilizzato per il file sottoposto a query. I tipi di compressione supportati sono:
bzip2
gzip
zipDeflate
tarGzip
tar
properties.columnDelimiter
(,)
.Creare una connessione sorgente
Una connessione di origine crea e gestisce la connessione all’origine esterna da cui vengono acquisiti i dati. Una connessione di origine è costituita da informazioni quali origine dati, formato dati e ID della connessione di origine necessari per creare un flusso di dati. Un'istanza della connessione di origine è specifica di un tenant e di un'organizzazione.
Per creare una connessione sorgente, effettua una richiesta POST al /sourceConnections
endpoint del Flow Service API.
Formato API
POST /sourceConnections
Richiesta
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-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 'Content-Type: application/json' \
-d '{
"name": "Data Landing Zone source connection",
"data": {
"format": "delimited"
},
"params": {
"path": "dlz-user-container/data8.csv"
},
"connectionSpec": {
"id": "26f526f2-58f4-4712-961d-e41bf1ccc0e8",
"version": "1.0"
}
}'
name
data.format
params.path
connectionSpec.id
26f526f2-58f4-4712-961d-e41bf1ccc0e8
.Risposta
In caso di esito positivo, la risposta restituisce l’identificatore univoco (id
) della connessione sorgente appena creata. Questo ID è richiesto nell’esercitazione successiva per creare un flusso di dati.
{
"id": "f5b46949-8c8d-4613-80cc-52c9c039e8b9",
"etag": "\"1400d460-0000-0200-0000-613be3520000\""
}
Passaggi successivi
Seguendo questa esercitazione, hai recuperato Data Landing Zone , ne ha esplorato la struttura per trovare il file da portare in Platform e ha creato una connessione di origine per iniziare a portare i dati in Platform. Ora puoi passare alla prossima esercitazione, dove scoprirai come crea un flusso di dati per portare i dati di archiviazione cloud su Platform utilizzando Flow Service API.