Connetti Data Landing Zone a Adobe Experience Platform tramite l’API del servizio di flusso

Data Landing Zone è una struttura di archiviazione dati basata su cloud per l’archiviazione temporanea dei file con provisioning di Adobe Experience Platform. I dati vengono eliminati automaticamente dal Data Landing Zone dopo sette giorni.

Questa esercitazione illustra i passaggi necessari per creare un Data Landing Zone connessione di origine tramite Flow Service API. Questa esercitazione fornisce anche istruzioni su come recuperare il Data Landing Zone, nonché visualizzare e aggiornare le credenziali.

Introduzione

Questa guida richiede una buona comprensione dei seguenti componenti dell’Experience Platform:

• Origini: L’Experience Platform consente di acquisire dati da varie sorgenti e allo stesso tempo di strutturare, etichettare e migliorare i dati in arrivo tramite i servizi Platform.
• Sandbox: Experience Platform fornisce sandbox virtuali che suddividono una singola istanza di Platform in ambienti virtuali separati per sviluppare e sviluppare applicazioni di esperienza digitale.

Le sezioni seguenti forniscono informazioni aggiuntive che sarà necessario conoscere per creare correttamente un Data Landing Zone connessione di origine tramite Flow Service API.

Questa esercitazione richiede anche di leggere la guida su guida introduttiva alle API di Platform per scoprire come autenticare le 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 deve effettuare una richiesta di GET al /landingzone punto finale Connectors API fornendo type=user_drop_zone come parte dell’intestazione della richiesta.

Formato API

GET /connectors/landingzone?type=user_drop_zone

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 seguente restituisce informazioni su una zona di destinazione, inclusa la corrispondente containerName e containerTTL.

{
    "containerName": "dlz-user-container",
    "containerTTL": "7"
}

Recupera Data Landing Zone credenziali

Per recuperare le credenziali di un Data Landing Zone, invia una richiesta di GET al /credentials punto finale Connectors API.

Formato API

GET /connectors/landingzone/credentials?type=user_drop_zone

Richiesta

Nell’esempio di richiesta seguente vengono recuperate 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 delle credenziali per la zona di destinazione, incluso l’attuale SASToken e SASUri, nonché storageAccountName corrisponde al contenitore della zona di destinazione.

{
    "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"
}

Aggiorna Data Landing Zone credenziali

È possibile aggiornare SASToken effettuando una richiesta di POST al /credentials punto finale Connectors API.

Formato API

POST /connectors/landingzone/credentials?type=user_drop_zone&action=refresh

Richiesta

La seguente richiesta 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 risposta seguente restituisce i valori aggiornati per la 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"
}

Esplorare la struttura e il contenuto dei file della zona di destinazione

Puoi esplorare la struttura dei file e il contenuto della zona di destinazione effettuando una richiesta di GET al connectionSpecs punto finale Flow Service API.

Formato API

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root

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

Una risposta corretta restituisce un array di file e cartelle presenti nella directory interrogata. Prendi nota della path proprietà del file che desideri caricare, in quanto devi 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 esaminare 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}

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

Una risposta corretta restituisce la struttura del file interrogato, inclusi i nomi dei file e i tipi di dati.

{
    "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"
        }
    ]
}

Utilizzo determineProperties per rilevare automaticamente le informazioni sulle proprietà dei file di un Data Landing Zone

È possibile utilizzare determineProperties per rilevare automaticamente le informazioni sulla proprietà del contenuto del file Data Landing Zone quando effettui una chiamata GET per esplorare i contenuti e la struttura della tua sorgente.

determineProperties casi di utilizzo

La tabella seguente illustra diversi scenari che è possibile incontrare quando si utilizza il determineProperties eseguire una query del parametro o fornire manualmente informazioni sul file.

Formato API

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&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

Una risposta corretta restituisce la struttura del file interrogato, inclusi i nomi dei file e i tipi di dati, nonché un properties chiave, contenente informazioni su fileType, compressionTypee columnDelimiter.

{
    "properties": {
        "fileType": "delimited",
        "compressionType": "tarGzip",
        "columnDelimiter": "~"
    },
    "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": "birthday",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            }
        ]
    },
    "data": [
        {
            "birthday": "1313-0505-19731973",
            "firstName": "Yvonne",
            "lastName": "Thilda",
            "id": "100",
            "email": "Yvonne.Thilda@yopmail.com"
        },
        {
            "birthday": "1515-1212-19731973",
            "firstName": "Mary",
            "lastName": "Pillsbury",
            "id": "101",
            "email": "Mary.Pillsbury@yopmail.com"
        },
        {
            "birthday": "0505-1010-19751975",
            "firstName": "Corene",
            "lastName": "Joeann",
            "id": "102",
            "email": "Corene.Joeann@yopmail.com"
        },
        {
            "birthday": "2727-0303-19901990",
            "firstName": "Dari",
            "lastName": "Greenwald",
            "id": "103",
            "email": "Dari.Greenwald@yopmail.com"
        },
        {
            "birthday": "1717-0404-19651965",
            "firstName": "Lucy",
            "lastName": "Magdalen",
            "id": "199",
            "email": "Lucy.Magdalen@yopmail.com"
        }
    ]
}

Creazione di 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 l’origine dati, il formato dati e l’ID di connessione di origine necessari per creare un flusso di dati. Un’istanza di connessione di origine è specifica per un tenant e un’organizzazione IMS.

Per creare una connessione di origine, invia una richiesta POST al /sourceConnections punto finale 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"
        }
    }'

Risposta

Una risposta corretta restituisce l'identificatore univoco (id) della nuova connessione sorgente creata. Questo ID è necessario 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 il tuo Data Landing Zone , ne è stata esplorata la struttura del file per trovare il file che si desidera portare in Platform e è stata creata una connessione di origine per iniziare a inserire i dati in Platform. È ora possibile passare all’esercitazione successiva, in cui verrà illustrato come creare un flusso di dati per portare i dati di archiviazione cloud a Platform utilizzando Flow Service API.