Esplora un sistema di archiviazione cloud utilizzando l' Flow Service API

Questa esercitazione utilizza l' Flow Service API per esplorare un sistema di archiviazione cloud di terze parti.

Introduzione

Questa guida richiede una buona conoscenza dei seguenti componenti di Adobe Experience Platform:

  • Origini: Experience Platform consente l'acquisizione di dati da varie origini, fornendo al contempo la possibilità di strutturare, etichettare e migliorare i dati in arrivo tramite Platform i servizi.
  • Sandbox: Experience Platform fornisce sandbox virtuali che dividono una singola Platform istanza in ambienti virtuali separati per sviluppare e sviluppare applicazioni per esperienze digitali.

Le sezioni seguenti forniscono informazioni aggiuntive che sarà necessario conoscere per collegarsi correttamente a un sistema di archiviazione cloud utilizzando l' Flow Service API.

Ottenere un ID connessione

Per esplorare un archivio cloud di terze parti tramite Platform le API, è necessario possedere un ID connessione valido. Se non si dispone già di una connessione per lo storage con cui si desidera lavorare, è possibile crearne una tramite le seguenti esercitazioni:

Lettura di chiamate API di esempio

Questa esercitazione fornisce esempi di chiamate API per dimostrare come formattare le richieste. Questi includono percorsi, intestazioni richieste e payload di richieste formattati correttamente. Viene inoltre fornito un JSON di esempio restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, vedete la sezione come leggere chiamate API di esempio nella guida alla Experience Platform risoluzione dei problemi.

Raccogli valori per le intestazioni richieste

Per effettuare chiamate alle Platform API, è prima necessario completare l'esercitazione sull'autenticazione. Completando l'esercitazione sull'autenticazione, vengono forniti i valori per ciascuna delle intestazioni richieste in tutte le chiamate Experience Platform API, come illustrato di seguito:

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

Tutte le risorse in Experience Platform, comprese quelle appartenenti a Flow Service, sono isolate in sandbox virtuali specifiche. Tutte le richieste alle Platform API richiedono un'intestazione che specifica il nome della sandbox in cui avrà luogo l'operazione:

  • x-sandbox-name: {SANDBOX_NAME}

Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un'intestazione aggiuntiva per il tipo di supporto:

  • Content-Type: application/json

Esplora l'archiviazione cloud

Utilizzando l'ID connessione per l'archiviazione cloud, potete esplorare file e directory eseguendo richieste di GET. Quando si eseguono richieste di GET per esplorare l'archiviazione cloud, è necessario includere i parametri di query elencati nella tabella seguente:

Parametro Descrizione
objectType Il tipo di oggetto che si desidera esplorare. Imposta questo valore come:
  • folder: Esplora una directory specifica
  • root: Esplora la directory principale.
object Questo parametro è richiesto solo quando si visualizza una directory specifica. Il suo valore rappresenta il percorso della directory che desiderate esplorare.

Utilizzate la seguente chiamata per trovare il percorso del file in cui desiderate inserire Platform:

Formato API

GET /connections/{CONNECTION_ID}/explore?objectType=root
GET /connections/{CONNECTION_ID}/explore?objectType=folder&object={PATH}
Parametro Descrizione
{CONNECTION_ID} L'ID di connessione per il connettore di origine dell'archiviazione cloud.
{PATH} Percorso di una directory.

Richiesta

curl -X GET \
    'http://platform.adobe.io/data/foundation/flowservice/connections/{CONNECTION_ID}/explore?objectType=folder&object=/some/path/' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

Una risposta corretta restituisce un array di file e cartelle presenti nella directory interrogata. Prendete nota della path proprietà del file che desiderate caricare, in quanto dovete fornire al passaggio successivo per ispezionarne la struttura.

[
    {
        "type": "File",
        "name": "data.csv",
        "path": "/some/path/data.csv"
    },
    {
        "type": "Folder",
        "name": "foobar",
        "path": "/some/path/foobar"
    }
]

Inspect la struttura di un file

Per esaminare la struttura del file di dati dall'archivio cloud, eseguire una richiesta di GET fornendo il percorso del file e digitare come parametro di query.

Potete esaminare la struttura di un file CSV o TSV specificando un delimitatore personalizzato come perimetro di query. Qualsiasi valore di carattere singolo è un delimitatore di colonna consentito. Se non viene fornito, come valore predefinito (,) viene utilizzata una virgola.

Formato API

GET /connections/{CONNECTION_ID}/explore?objectType=file&object={FILE_PATH}&fileType={FILE_TYPE}
GET /connections/{CONNECTION_ID}/explore?objectType=file&object={FILE_PATH}&fileType={FILE_TYPE}&preview=true&fileType=delimited&columnDelimiter=;
GET /connections/{CONNECTION_ID}/explore?objectType=file&object={FILE_PATH}&fileType={FILE_TYPE}&preview=true&fileType=delimited&columnDelimiter=\t
Parametro Descrizione
{CONNECTION_ID} L'ID di connessione del connettore di origine dell'archiviazione cloud.
{FILE_PATH} Percorso del file da esaminare.
{FILE_TYPE} Il tipo di file. I tipi di file supportati includono:
  • DELIMITATO: Valore separato da delimitatore. I file DSV devono essere separati da virgole.
  • JSON: Notazione oggetto JavaScript. I file JSON devono essere conformi a XDM
  • PARQUET: Parquet Apache. I file parquet devono essere conformi a XDM.
columnDelimiter Il valore del singolo carattere specificato come delimitatore di colonna per esaminare i file CSV o TSV. Se il parametro non è specificato, per impostazione predefinita il valore è una virgola (,).

Richiesta

curl -X GET \
    'http://platform.adobe.io/data/foundation/flowservice/connections/{CONNECTION_ID}/explore?objectType=file&object=/some/path/data.csv&fileType=DELIMITED' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {IMS_ORG}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

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

[
    {
        "name": "Id",
        "type": "String"
    },
    {
        "name": "FirstName",
        "type": "String"
    },
    {
        "name": "LastName",
        "type": "String"
    },
    {
        "name": "Email",
        "type": "String"
    },
    {
        "name": "Phone",
        "type": "String"
    }
]

Passaggi successivi

Seguendo questa esercitazione, hai esplorato il sistema di archiviazione cloud, trovato il percorso del file a cui desideri accedere Platforme ne hai visualizzato la struttura. Potete utilizzare queste informazioni nell'esercitazione successiva per raccogliere i dati dall'archiviazione cloud e portarli nella piattaforma.

In questa pagina