Creare una connessione sorgente SFTP utilizzando l'API Flow Service

Questa esercitazione utilizza l’ Flow Service API per seguire i passaggi necessari per collegare l’Experience Platform a un server SFTP (Secure File Transfer Protocol).

Introduzione

Questa guida richiede una buona comprensione dei seguenti componenti di Adobe 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.
IMPORTANTE

Si consiglia di evitare la restituzione di nuove righe o ritorni a capo durante l’acquisizione di oggetti JSON con una connessione sorgente SFTP. Per aggirare il limite, utilizza un singolo oggetto JSON per riga e utilizza più righe per i file successivi.

Le sezioni seguenti forniscono informazioni aggiuntive che sarà necessario conoscere per connettersi correttamente a un server SFTP utilizzando l’ API Flow Service .

Raccogli credenziali richieste

Affinché Flow Service possa connettersi a SFTP, è necessario fornire valori per le seguenti proprietà di connessione:

Credenziali Descrizione
host Nome o indirizzo IP associato al server SFTP.
username Il nome utente con accesso al server SFTP.
password Password per il server SFTP.
privateKeyContent Contenuto della chiave privata SSH codificata Base64. Il tipo di chiave OpenSSH deve essere classificato come RSA o DSA.
passPhrase La frase o password per decrittografare la chiave privata se il file di chiave o il contenuto della chiave sono protetti da una frase di passaggio. Se PrivateKeyContent è protetto da password, questo parametro deve essere utilizzato con la passphrase PrivateKeyContent come valore.

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 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 di 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 di Experience Platform, come mostrato 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 API Platform richiedono un’intestazione che specifichi 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 di tipo multimediale aggiuntiva:

  • Content-Type: application/json

Creare una connessione

Una connessione specifica un'origine e contiene le credenziali per tale origine. È necessaria una sola connessione in quanto può essere utilizzata per creare più flussi di dati per immettere dati diversi.

Creare una connessione SFTP utilizzando l’autenticazione di base

Per creare una connessione SFTP utilizzando l’autenticazione di base, effettua una richiesta POST all’API Flow Service fornendo al contempo i valori per le connessioni host, userName e password.

Formato API

POST /connections

Richiesta

Per creare una connessione SFTP, è necessario fornire l’ID univoco della specifica di connessione come parte della richiesta di POST. L'ID della specifica di connessione per SFTP è b7bf2577-4520-42c9-bae9-cad01560f7bc.

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/connections' \
    -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 'Content-Type: application/json' \
    -d  '{
        "name": "SFTP connector with password",
        "description": "SFTP connector password",
        "auth": {
            "specName": "Basic Authentication for sftp",
            "params": {
                "host": "{HOST}",
                "userName": "{USERNAME}",
                "password": "{PASSWORD}"
            }
        },
        "connectionSpec": {
            "id": "b7bf2577-4520-42c9-bae9-cad01560f7bc",
            "version": "1.0"
        }
    }'
Proprietà Descrizione
auth.params.host Il nome host del server SFTP.
auth.params.username Nome utente associato al server SFTP.
auth.params.password Password associata al server SFTP.
connectionSpec.id ID delle specifiche di connessione del server SFTP: b7bf2577-4520-42c9-bae9-cad01560f7bc

Risposta

Una risposta corretta restituisce l'identificatore univoco (id) della nuova connessione creata. Questo ID è necessario per esplorare il server SFTP nella prossima esercitazione.

{
    "id": "bf367b0d-3d9b-4060-b67b-0d3d9bd06094",
    "etag": "\"1700cc7b-0000-0200-0000-5e3b3fba0000\""
}

Creare una connessione SFTP utilizzando l’autenticazione a chiave pubblica SSH

Per creare una connessione SFTP utilizzando l’autenticazione a chiave pubblica SSH, effettua una richiesta POST all’API Flow Service fornendo al contempo i valori per le connessioni host, userName, privateKeyContent e passPhrase.

IMPORTANTE

Il connettore SFTP supporta una chiave OpenSSH di tipo RSA o DSA. Assicurati che il contenuto del file chiave inizi con "-----BEGIN [RSA/DSA] PRIVATE KEY-----" e termini con "-----END [RSA/DSA] PRIVATE KEY-----". Se il file della chiave privata è un file in formato PPK, utilizza lo strumento PuTTY per convertire da PPK a formato OpenSSH.

Formato API

POST /connections

Richiesta

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/connections' \
    -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 'Content-Type: application/json' \
    -d '{
        "name": "SFTP connector with SSH authentication",
        "description": "SFTP connector with SSH authentication",
        "auth": {
            "specName": "SSH PublicKey Authentication for sftp",
            "params": {
                "host": "{HOST}",
                "userName": "{USERNAME}",
                "privateKeyContent": "{PRIVATE_KEY_CONTENT}",
                "passPhrase": "{PASSPHRASE}"
            }
        },
        "connectionSpec": {
            "id": "b7bf2577-4520-42c9-bae9-cad01560f7bc",
            "version": "1.0"
        }
    }'
Proprietà Descrizione
auth.params.host Il nome host del server SFTP.
auth.params.username Nome utente associato al server SFTP.
auth.params.privateKeyContent Contenuto della chiave privata SSH codificata Base64. Il tipo di chiave OpenSSH deve essere classificato come RSA o DSA.
auth.params.passPhrase La frase o password per decrittografare la chiave privata se il file di chiave o il contenuto della chiave sono protetti da una frase di passaggio. Se PrivateKeyContent è protetto da password, questo parametro deve essere utilizzato con la passphrase PrivateKeyContent come valore.
connectionSpec.id ID delle specifiche di connessione del server SFTP: b7bf2577-4520-42c9-bae9-cad01560f7bc

Risposta

Una risposta corretta restituisce l'identificatore univoco (id) della nuova connessione creata. Questo ID è necessario per esplorare il server SFTP nella prossima esercitazione.

{
    "id": "bf367b0d-3d9b-4060-b67b-0d3d9bd06094",
    "etag": "\"1700cc7b-0000-0200-0000-5e3b3fba0000\""
}

Passaggi successivi

Seguendo questa esercitazione, hai creato una connessione SFTP utilizzando l'API Flow Service e hai ottenuto il valore ID univoco della connessione. Puoi utilizzare questo ID connessione per esplorare gli archivi cloud utilizzando l'API del servizio di flusso o acquisire i dati del parquet utilizzando l'API del servizio di flusso.

In questa pagina