Acquisizione di dati crittografati

Puoi acquisire i file di dati crittografati in Adobe Experience Platform utilizzando origini batch di archiviazione cloud. Con l’acquisizione di dati crittografati, puoi sfruttare meccanismi di crittografia asimmetrica per trasferire in modo sicuro i dati batch in Experienci Platform. Attualmente, i meccanismi di crittografia asimmetrica supportati sono PGP e GPG.

Il processo di acquisizione dei dati crittografati è il seguente:

  1. Creare una coppia di chiavi di crittografia utilizzando le API Experienci Platform. La coppia di chiavi di crittografia è costituita da una chiave privata e da una chiave pubblica. Una volta creata, puoi copiare o scaricare la chiave pubblica, insieme all’ID della chiave pubblica e all’ora di scadenza corrispondenti. Durante questa procedura, la chiave privata verrà memorizzata da Experienci Platform in un archivio protetto. NOTA: La chiave pubblica nella risposta è codificata in Base64 e deve essere decrittografata prima dell’utilizzo.
  2. Utilizza la chiave pubblica per crittografare il file di dati che desideri acquisire.
  3. Inserisci il file crittografato nell’archiviazione cloud.
  4. Quando il file crittografato è pronto, creare una connessione di origine e un flusso di dati per l’origine di archiviazione cloud. Durante il passaggio di creazione del flusso, devi fornire un encryption e includere l'ID della chiave pubblica.
  5. L’Experience Platform recupera la chiave privata dall’archivio protetto per decrittografare i dati al momento dell’acquisizione.
IMPORTANT
La dimensione massima di un singolo file crittografato è di 1 GB. Ad esempio, puoi acquisire dati per un valore di 2 GB in una singola esecuzione del flusso di dati; tuttavia, qualsiasi singolo file in tali dati non può superare 1 GB.

In questo documento vengono descritti i passaggi necessari per generare una coppia di chiavi di crittografia per crittografare i dati e acquisirli per l’Experience Platform utilizzando origini di archiviazione cloud.

Introduzione get-started

Questo tutorial richiede una buona conoscenza dei seguenti componenti di Adobe 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.

Utilizzo delle API di Platform

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

Estensioni di file supportate per i file crittografati supported-file-extensions-for-encrypted-files

L’elenco delle estensioni di file supportate per i file crittografati è:

  • .csv
  • .tsv
  • .json
  • parquet
  • .csv.gpg
  • .tsv.gpg
  • .json.gpg
  • parquet, gpg
  • .csv.pgp
  • .tsv.pgp
  • .json.pgp
  • .parquet.pgp
  • gpg
  • .pgp
NOTE
L’acquisizione di file crittografati in Adobe Experience Platform Sources supporta openPGP e non qualsiasi versione proprietaria specifica di PGP.

Crea coppia di chiavi di crittografia create-encryption-key-pair

Il primo passaggio nell’acquisizione di dati crittografati da Experienci Platform consiste nel creare la coppia di chiavi di crittografia effettuando una richiesta POST al /encryption/keys endpoint del Connectors API.

Formato API

POST /data/foundation/connectors/encryption/keys

Richiesta

Visualizza richiesta di esempio

La richiesta seguente genera una coppia di chiavi di crittografia utilizzando l’algoritmo di crittografia PGP.

code language-shell
curl -X POST \
  'https://platform.adobe.io/data/foundation/connectors/encryption/keys' \
  -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 '{
      "encryptionAlgorithm": "PGP",
      "params": {
          "passPhrase": "{{PASSPHRASE}}"
      }
  }'
table 0-row-2 1-row-2 2-row-2
Parametro Descrizione
encryptionAlgorithm Tipo di algoritmo di crittografia in uso. I tipi di crittografia supportati sono PGP e GPG.
params.passPhrase La passphrase fornisce un ulteriore livello di protezione per le chiavi di crittografia. Al momento della creazione, Experienci Platform memorizza la passphrase in un archivio protetto diverso dalla chiave pubblica. Specificare una stringa non vuota come passphrase.

Risposta

Visualizza risposta di esempio

In caso di esito positivo, la risposta restituisce la chiave pubblica con codifica Base64, l’ID della chiave pubblica e l’ora di scadenza delle chiavi. Il tempo di scadenza viene impostato automaticamente su 180 giorni dopo la data di generazione della chiave. L’ora di scadenza non è attualmente configurabile.

code language-json
{
    ​"publicKey": "{PUBLIC_KEY}",
    ​"publicKeyId": "{PUBLIC_KEY_ID}",
    ​"expiryTime": "1684843168"
}
table 0-row-2 1-row-2 2-row-2 3-row-2
Proprietà Descrizione
publicKey La chiave pubblica viene utilizzata per crittografare i dati nell’archiviazione cloud. Questa chiave corrisponde alla chiave privata creata durante questo passaggio. Tuttavia, la chiave privata viene immediatamente recapitata all’Experience Platform.
publicKeyId L’ID della chiave pubblica viene utilizzato per creare un flusso di dati e acquisire i dati di archiviazione cloud crittografati per Experienci Platform.
expiryTime L'ora di scadenza definisce la data di scadenza della coppia di chiavi di crittografia. Questa data viene impostata automaticamente su 180 giorni dopo la data di generazione della chiave e viene visualizzata in formato timestamp unix.

Recuperare le chiavi di crittografia retrieve-encryption-keys

Per recuperare tutte le chiavi di crittografia dell’organizzazione, effettua una richiesta GET al /encryption/keys endpoint=nt.

Formato API

GET /data/foundation/connectors/encryption/keys

Richiesta

Visualizza richiesta di esempio

La richiesta seguente recupera tutte le chiavi di crittografia dell’organizzazione.

code language-shell
curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/encryption/keys' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'x-api-key: {{API_KEY}}' \
  -H 'x-gw-ims-org-id: {{ORG_ID}}' \

Risposta

Visualizza risposta di esempio

In caso di esito positivo, la risposta restituisce l’algoritmo di crittografia, la chiave pubblica, l’ID della chiave pubblica e la corrispondente data di scadenza delle chiavi.

code language-json
{
    "encryptionAlgorithm": "{ENCRYPTION_ALGORITHM}",
    "publicKeyId": "{PUBLIC_KEY_ID}",
    "publicKey": "{PUBLIC_KEY}",
    "expiryTime": "{EXPIRY_TIME}"
}

Recupera chiavi di crittografia per ID retrieve-encryption-keys-by-id

Per recuperare un set specifico di chiavi di crittografia, effettuare una richiesta GET al /encryption/keys e fornire l'ID della chiave pubblica come parametro di intestazione.

Formato API

GET /data/foundation/connectors/encryption/keys/{PUBLIC_KEY_ID}

Richiesta

Visualizza richiesta di esempio
code language-shell
curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/encryption/keys/{publicKeyId}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'x-api-key: {{API_KEY}}' \
  -H 'x-gw-ims-org-id: {{ORG_ID}}' \

Risposta

Visualizza risposta di esempio

In caso di esito positivo, la risposta restituisce l’algoritmo di crittografia, la chiave pubblica, l’ID della chiave pubblica e la corrispondente data di scadenza delle chiavi.

code language-json
{
    "encryptionAlgorithm": "{ENCRYPTION_ALGORITHM}",
    "publicKeyId": "{PUBLIC_KEY_ID}",
    "publicKey": "{PUBLIC_KEY}",
    "expiryTime": "{EXPIRY_TIME}"
}

Creare una coppia di chiavi gestite dal cliente create-customer-managed-key-pair

Facoltativamente, puoi creare una coppia di chiavi per la verifica della firma per firmare e acquisire i dati crittografati.

Durante questa fase, devi generare la tua combinazione di chiave privata e chiave pubblica e quindi utilizzare la tua chiave privata per firmare i dati crittografati. Successivamente, devi codificare la chiave pubblica in Base64 e condividerla con Experienci Platform affinché Platform possa verificare la firma.

Condividi la chiave pubblica per Experience Platform

Per condividere la chiave pubblica, invia una richiesta POST al /customer-keys fornendo l'algoritmo di crittografia e la chiave pubblica con codifica Base64.

Formato API

POST /data/foundation/connectors/encryption/customer-keys

Richiesta

Visualizza richiesta di esempio
code language-shell
curl -X POST \
  'https://platform.adobe.io/data/foundation/connectors/encryption/customer-keys' \
  -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 '{
      "encryptionAlgorithm": {{ENCRYPTION_ALGORITHM}},
      "publicKey": {{BASE_64_ENCODED_PUBLIC_KEY}}
    }'
table 0-row-2 1-row-2 2-row-2
Parametro Descrizione
encryptionAlgorithm Tipo di algoritmo di crittografia in uso. I tipi di crittografia supportati sono PGP e GPG.
publicKey La chiave pubblica che corrisponde alle chiavi gestite dal cliente utilizzate per la firma del file crittografato. Questa chiave deve avere la codifica Base64.

Risposta

Visualizza risposta di esempio
code language-json
{
  "publicKeyId": "e31ae895-7896-469a-8e06-eb9207ddf1c2"
}
table 0-row-2 1-row-2
Proprietà Descrizione
publicKeyId Questo ID di chiave pubblica viene restituito in risposta alla condivisione della chiave gestita dal cliente con Experienci Platform. Puoi fornire questo ID di chiave pubblica come ID della chiave di verifica della firma durante la creazione di un flusso di dati per dati firmati e crittografati.

Connetti l’origine dell’archiviazione cloud a Experienci Platform utilizzando Flow Service API

Dopo aver recuperato la coppia di chiavi di crittografia, ora puoi procedere e creare una connessione di origine per l’origine dell’archiviazione cloud e trasferire i dati crittografati a Platform.

Innanzitutto, devi creare una connessione di base per autenticare l’origine su Platform. Per creare una connessione di base e autenticare l'origine, selezionare dall'elenco seguente l'origine che si desidera utilizzare:

Dopo aver creato una connessione di base, è necessario seguire i passaggi descritti nell'esercitazione per creazione di una connessione di origine per un'origine di archiviazione cloud per creare una connessione sorgente, una connessione di destinazione e una mappatura.

Creare un flusso di dati per i dati crittografati create-a-dataflow-for-encrypted-data

NOTE
Per creare un flusso di dati per l’acquisizione di dati crittografati, è necessario disporre dei seguenti elementi:

Per creare un flusso di dati, effettua una richiesta POST al /flows endpoint del Flow Service API. Per acquisire i dati crittografati, è necessario aggiungere una encryption sezione al transformations e includere publicKeyId creato in un passaggio precedente.

Formato API

POST /flows
Creare un flusso di dati per l’acquisizione di dati crittografati

Richiesta

accordion
Visualizza richiesta di esempio

La seguente richiesta crea un flusso di dati per acquisire dati crittografati per un’origine di archiviazione cloud.

code language-shell
curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/flows' \
  -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": "ACME Customer Data",
    "description": "ACME Customer Data (Encrypted)",
    "flowSpec": {
        "id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
        "version": "1.0"
    },
    "sourceConnectionIds": [
        "655f7c1b-1977-49b3-a429-51379ecf0e15"
    ],
    "targetConnectionIds": [
        "de688225-d619-481c-ae3b-40c250fd7c79"
    ],
    "transformations": [
        {
            "name": "Mapping",
            "params": {
                "mappingId": "6b6e24213dbe4f57bd8207d21034ff03",
                "mappingVersion":"0"
            }
        },
        {
            "name": "Encryption",
            "params": {
                "publicKeyId":"311ef6f8-9bcd-48cf-a9e9-d12c45fb7a17"
            }
        }
    ],
    "scheduleParams": {
        "startTime": "1675793392",
        "frequency": "once"
    }
}'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2
Proprietà Descrizione
flowSpec.id ID della specifica di flusso che corrisponde alle origini dell’archiviazione cloud.
sourceConnectionIds ID della connessione di origine. Questo ID rappresenta il trasferimento di dati dall’origine a Platform.
targetConnectionIds ID della connessione di destinazione. Questo ID rappresenta dove arrivano i dati una volta trasferiti a Platform.
transformations[x].params.mappingId ID di mappatura.
transformations.name Quando si acquisiscono file crittografati, è necessario fornire Encryption come parametro di trasformazione aggiuntivo per il flusso di dati.
transformations[x].params.publicKeyId ID della chiave pubblica creato. Questo ID è la metà della coppia di chiavi di crittografia utilizzata per crittografare i dati di archiviazione cloud.
scheduleParams.startTime L’ora di inizio del flusso di dati in tempo epoca.
scheduleParams.frequency La frequenza con cui il flusso di dati raccoglierà i dati. I valori accettabili includono: once, minute, hour, day, o week.
scheduleParams.interval L’intervallo indica il periodo tra due esecuzioni consecutive del flusso. Il valore dell'intervallo deve essere un numero intero diverso da zero. Intervallo non richiesto quando la frequenza è impostata come once e deve essere maggiore o uguale a 15 per altri valori di frequenza.

Risposta

accordion
Visualizza risposta di esempio

In caso di esito positivo, la risposta restituisce l’ID (id) del flusso di dati appena creato per i dati crittografati.

code language-json
{
    "id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
    "etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}
Creare un flusso di dati per acquisire dati crittografati e firmati

Richiesta

accordion
Visualizza richiesta di esempio
code language-shell
curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/flows' \
  -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": "ACME Customer Data (with Sign Verification)",
    "description": "ACME Customer Data (with Sign Verification)",
    "flowSpec": {
        "id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
        "version": "1.0"
    },
    "sourceConnectionIds": [
        "655f7c1b-1977-49b3-a429-51379ecf0e15"
    ],
    "targetConnectionIds": [
        "de688225-d619-481c-ae3b-40c250fd7c79"
    ],
    "transformations": [
        {
            "name": "Mapping",
            "params": {
                "mappingId": "6b6e24213dbe4f57bd8207d21034ff03",
                "mappingVersion":"0"
            }
        },
        {
            "name": "Encryption",
            "params": {
                "publicKeyId":"311ef6f8-9bcd-48cf-a9e9-d12c45fb7a17",
                "signVerificationKeyId":"e31ae895-7896-469a-8e06-eb9207ddf1c2"
            }
        }
    ],
    "scheduleParams": {
        "startTime": "1675793392",
        "frequency": "once"
    }
}'
table 0-row-2 1-row-2
Proprietà Descrizione
params.signVerificationKeyId L’ID della chiave di verifica della firma è uguale all’ID della chiave pubblica recuperato dopo la condivisione della chiave pubblica con codifica Base64 con Experienci Platform.

Risposta

accordion
Visualizza risposta di esempio

In caso di esito positivo, la risposta restituisce l’ID (id) del flusso di dati appena creato per i dati crittografati.

code language-json
{
    "id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
    "etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}

Elimina chiavi di crittografia delete-encryption-keys

Per eliminare le chiavi di crittografia, invia una richiesta DELETE al /encryption/keys e fornire l'ID della chiave pubblica come parametro di intestazione.

Formato API

DELETE /data/foundation/connectors/encryption/keys/{PUBLIC_KEY_ID}

Richiesta

Visualizza richiesta di esempio
code language-shell
curl -X DELETE \
  'https://platform.adobe.io/data/foundation/connectors/encryption/keys/{publicKeyId}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'x-api-key: {{API_KEY}}' \
  -H 'x-gw-ims-org-id: {{ORG_ID}}' \

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 204 (nessun contenuto) e un corpo vuoto.

Convalidare le chiavi di crittografia validate-encryption-keys

Per convalidare le chiavi di crittografia, invia una richiesta di GET al /encryption/keys/validate/ e fornire l'ID della chiave pubblica da convalidare come parametro di intestazione.

GET /data/foundation/connectors/encryption/keys/validate/{PUBLIC_KEY_ID}

Richiesta

Visualizza richiesta di esempio
code language-shell
curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/encryption/keys/validate/{publicKeyId}' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'x-api-key: {{API_KEY}}' \
  -H 'x-gw-ims-org-id: {{ORG_ID}}' \

Risposta

In caso di esito positivo, la risposta restituisce la conferma che gli ID sono validi o non validi.

Valido

Un ID di chiave pubblica valido restituisce lo stato Active insieme all’ID della chiave pubblica.

code language-json
{
    "publicKeyId": "{PUBLIC_KEY_ID}",
    "status": "Active"
}
Non valido

Un ID di chiave pubblica non valido restituisce lo stato Expired insieme all’ID della chiave pubblica.

code language-json
{
    "publicKeyId": "{PUBLIC_KEY_ID}",
    "status": "Expired"
}

Limitazioni all’acquisizione ricorrente restrictions-on-recurring-ingestion

L’acquisizione di dati crittografati non supporta l’acquisizione di cartelle ricorrenti o a più livelli nelle origini. Tutti i file crittografati devono essere contenuti in una singola cartella. Non sono supportati neanche i caratteri jolly con più cartelle in un unico percorso di origine.

Di seguito è riportato un esempio di struttura di cartelle supportata, in cui il percorso di origine è /ACME-customers/*.csv.gpg.

In questo scenario, i file in grassetto vengono acquisiti in Experienci Platform.

  • ACME-clienti

    • File1.csv.gpg
    • File2.json.gpg
    • File3.csv.gpg
    • File4.json
    • File5.csv.gpg

Di seguito è riportato un esempio di struttura di cartelle non supportata in cui il percorso di origine è /ACME-customers/*.

In questo scenario, l’esecuzione del flusso non riuscirà e restituirà un messaggio di errore che indica che i dati non possono essere copiati dall’origine.

  • ACME-clienti

    • File1.csv.gpg

    • File2.json.gpg

    • Sottocartella1

      • File3.csv.gpg
      • File4.json.gpg
      • File5.csv.gpg
  • fedeltà ACME

    • File6.csv.gpg

Passaggi successivi

Seguendo questa esercitazione, hai creato una coppia di chiavi di crittografia per i dati dell’archiviazione cloud e un flusso di dati per acquisire i dati crittografati utilizzando Flow Service API. Per gli aggiornamenti sullo stato relativi a completezza, errori e metriche del flusso di dati, consulta la guida su monitoraggio del flusso di dati tramite Flow Service API.

recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089