Creare una connessione di base Amazon S3 utilizzando l'API Flow Service

Una connessione di base rappresenta la connessione autenticata tra un'origine e Adobe Experience Platform.

Questo tutorial illustra i passaggi necessari per creare una connessione di base per Amazon S3 (di seguito "S3") utilizzando Flow Service API.

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 e consente 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, utili per le attività di sviluppo e aggiornamento delle applicazioni di esperienza digitale.

Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere per connettersi correttamente a un archivio S3 tramite l'API Flow Service.

Raccogli le credenziali richieste

Affinché Flow Service possa connettersi all'archivio S3, è necessario fornire i valori per le proprietà di connessione seguenti:

Credenziali
Descrizione
s3AccessKey
ID della chiave di accesso per il bucket S3.
s3SecretKey
ID della chiave segreta per il bucket S3.
serviceUrl
(Facoltativo) L'endpoint S3 personalizzato a cui connettersi. Questo campo è obbligatorio quando il bucket S3 è specifico per l'area geografica. Il formato per serviceUrl è: https://s3.{REGION}.amazonaws.com/).
bucketName
Il bucket S3 contiene i dati e i metadati descrittivi corrispondenti. Il nome del bucket S3 deve contenere tra tre e 63 caratteri e deve iniziare e terminare con una lettera o un numero. Il nome del bucket può contenere solo lettere minuscole, numeri o trattini (-) e non può essere formattato come indirizzo IP.
folderPath
Percorso della cartella nel bucket S3 in cui sono memorizzati i dati. Questa credenziale è necessaria quando l'utente dispone di un accesso limitato.
s3SessionToken
(Facoltativo) Un token temporaneo a breve termine che consente di fornire accesso temporaneo alle risorse S3 agli utenti in ambienti non attendibili. Per ulteriori informazioni, vedere S3 panoramica.
connectionSpec.id
La specifica di connessione restituisce le proprietà del connettore di un'origine, incluse le specifiche di autenticazione relative alla creazione delle connessioni di base e di origine. ID della specifica di connessione per S3: ecadc60c-7455-4d87-84dc-2a0e293d997b.

Per ulteriori informazioni, visita questo Amazon Web Services documento.

Utilizzo delle API di Platform

Per informazioni su come effettuare correttamente chiamate alle API di Platform, consulta la guida in guida introduttiva alle API di Platform.

Creare una connessione di base

Una connessione di base mantiene le informazioni tra l’origine e Platform, incluse le credenziali di autenticazione dell’origine, lo stato corrente della connessione e l’ID univoco della connessione di base. L’ID della connessione di base consente di esplorare e navigare tra i file dall’interno dell’origine e identificare gli elementi specifici che desideri acquisire, comprese le informazioni relative ai tipi di dati e ai formati.

Per creare un ID di connessione di base, effettuare una richiesta POST all'endpoint /connections fornendo le credenziali di autenticazione S3 come parte dei parametri della richiesta.

Formato API

POST /connections

Richiesta

La richiesta seguente crea una connessione di base per S3:

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: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Amazon S3 base connection",
        "description": "Amazon S3 base connection with temporary session token",
        "auth": {
            "specName": "Access Key",
            "params": {
                "s3AccessKey": "{S3_ACCESS_KEY}",
                "s3SecretKey": "{S3_SECRET_KEY}",
                "s3SessionToken": "{S3_SESSION_TOKEN}
            }
        },
        "connectionSpec": {
            "id": "ecadc60c-7455-4d87-84dc-2a0e293d997b",
            "version": "1.0"
        }
    }'
Proprietà
Descrizione
auth.params.s3AccessKey
Chiave di accesso associata al bucket S3.
auth.params.s3SecretKey
La chiave segreta associata al bucket S3.
auth.params.s3SessionToken
(Facoltativo) Il token S3 temporaneo a breve termine utilizzato per accedere al bucket.
connectionSpec.id
ID della specifica di connessione S3: ecadc60c-7455-4d87-84dc-2a0e293d997b

Risposta

In caso di esito positivo, la risposta restituisce i dettagli della connessione appena creata, incluso il relativo identificatore univoco (id). Questo ID è necessario per esplorare lo spazio di archiviazione nella prossima esercitazione.

{
    "id": "4cb0c374-d3bb-4557-b139-5712880adc55",
    "etag": "\"1700d77b-0000-0200-0000-5e3b41a10000\""
}

Passaggi successivi

Seguendo questa esercitazione, hai creato una connessione S3 utilizzando le API ed è stato ottenuto un ID univoco come parte del corpo della risposta. Puoi usare questo ID connessione per esplorare gli archivi cloud utilizzando l'API del servizio Flusso.

Appendice

La sezione seguente fornisce informazioni aggiuntive sull'utilizzo dell'origine S3.

Aggiorna il token di sessione S3

s3SessionToken è temporaneo e deve essere aggiornato alla scadenza. È possibile aggiornare il token di sessione associato alla connessione di base effettuando una richiesta PATCH all'API Flow Service. Per ulteriori informazioni sulle credenziali di sicurezza temporanee per S3, vedere la S3 panoramica.

IMPORTANT
L'intestazione If-Match è obbligatoria quando si effettua una richiesta PATCH. Il valore di questa intestazione è il tag univoco della connessione che desideri aggiornare.

Formato API

PATCH /connections

Richiesta

La richiesta seguente crea una connessione di base per S3:

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/connections/4cb0c374-d3bb-4557-b139-5712880adc55' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'If-Match: "1700d77b-0000-0200-0000-5e3b41a10000"'
    -d '[
        {
            "op": "replace",
            "path": "/auth/params/s3SessionToken",
            "value": "{SESSION_TOKEN}"
        }
    ]'
Parametro
Descrizione
op
Chiamata di operazione utilizzata per definire l'azione necessaria per aggiornare la connessione. Le operazioni includono: add, replace e remove.
path
Percorso del parametro da aggiornare.
value
Il nuovo valore con cui desideri aggiornare il parametro.

Risposta

In caso di esito positivo, la risposta restituisce l’ID della connessione di base e un tag aggiornato. È possibile verificare l'aggiornamento effettuando una richiesta di GET all'API Flow Service e fornendo l'ID di connessione.

{
    "id": "4cb0c374-d3bb-4557-b139-5712880adc55",
    "etag": "\"3600e378-0000-0200-0000-5f40212f0000\""
}
recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089