Configurare la destinazione di esportazione per un set di dati

Panoramica overview

In questa pagina viene descritto come utilizzare Destination SDK per configurare una destinazione che supporti esportazioni di set di dati. Utilizzare una destinazione di esportazione del set di dati per esportare i set di dati non elaborati da Experience Platform in posizioni di archiviazione esterne per la creazione di rapporti, flussi di lavoro di data science e molti altri casi d’uso.

Questa guida utilizza Amazon S3 come esempio in tutto, ma gli stessi principi di configurazione si applicano a qualsiasi tipo di destinazione basato su file supportato da Destination SDK (Azure Blob Storage, SFTP, Azure Data Lake Storage Gen2, Google Cloud Storage e Data Landing Zone).

Per le descrizioni dettagliate di tutti i parametri utilizzati in questa guida, vedere opzioni di configurazione in Destination SDK.

Prerequisiti prerequisites

Prima di procedere con i passaggi descritti di seguito, leggere la pagina della guida introduttiva Destination SDK per informazioni su come ottenere le credenziali di autenticazione Adobe I/O necessarie e altri prerequisiti per l’utilizzo delle API Destination SDK.

Passaggio 1: creare una configurazione di server e file create-server-file-configuration

Iniziare utilizzando l’endpoint /destination-servers per creare una configurazione del server e del file.

Formato API

POST platform.adobe.io/data/core/activation/authoring/destination-servers

Richiesta

La richiesta seguente crea una nuova configurazione del server di destinazione per una destinazione Amazon S3. I valori fileType e compression sono modelli, ovvero verranno forniti dal cliente al momento della connessione di destinazione tramite customerDataFields definito nel passaggio successivo.

curl -X POST https://platform.adobe.io/data/core/activation/authoring/destination-servers \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '
{
   "name":"Amazon S3 dataset export destination server",
   "destinationServerType":"FILE_BASED_S3",
   "fileBasedS3Destination":{
      "bucket":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.bucketName}}"
      },
      "path":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.path}}"
      }
   },
   "fileConfigurations":{
      "compression":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.compression}}"
      },
      "fileType":{
         "templatingStrategy":"PEBBLE_V1",
         "value":"{{customerData.fileType}}"
      },
      "csvOptions":{
         "quoteAll":{
            "templatingStrategy":"NONE",
            "value":"false"
         },
         "header":{
            "templatingStrategy":"NONE",
            "value":"true"
         },
         "ignoreLeadingWhiteSpace":{
            "templatingStrategy":"NONE",
            "value":"true"
         },
         "ignoreTrailingWhiteSpace":{
            "templatingStrategy":"NONE",
            "value":"true"
         },
         "nullValue":{
            "templatingStrategy":"NONE",
            "value":""
         },
         "dateFormat":{
            "templatingStrategy":"NONE",
            "value":"yyyy-MM-dd"
         },
         "timestampFormat":{
            "templatingStrategy":"NONE",
            "value":"yyyy-MM-dd'\''T'\'':mm:ss[.SSS][XXX]"
         }
      }
   }
}'

Una risposta corretta restituisce la nuova configurazione del server di destinazione, incluso l’identificatore univoco (instanceId) della configurazione. Memorizza questo valore come richiesto nel passaggio successivo.

Passaggio 2: creare la configurazione di destinazione create-destination-configuration

Dopo aver creato la configurazione del server di destinazione nel passaggio precedente, utilizzare l’endpoint API /destinations per creare la configurazione di destinazione.

Per connettere la configurazione del server da passaggio 1 a questa configurazione di destinazione, sostituire il valore destinationServerId nella richiesta API seguente con il valore instanceId ottenuto durante la creazione del server di destinazione in passaggio 1.

Formato API

POST platform.adobe.io/data/core/activation/authoring/destinations

Richiesta

curl -X POST https://platform.adobe.io/data/core/activation/authoring/destinations \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '
{
   "name":"Amazon S3 dataset export destination",
   "description":"Amazon S3 destination for exporting Experience Platform datasets.",
   "status":"TEST",
   "sources":[
      "DATASETS"
   ],
   "customerAuthenticationConfigurations":[
      {
         "authType":"S3"
      }
   ],
   "customerDataFields":[
      {
         "name":"bucketName",
         "title":"Enter the name of your Amazon S3 bucket",
         "description":"Amazon S3 bucket name",
         "type":"string",
         "isRequired":true,
         "pattern":"(?=^.{3,63}$)(?!^(\\d+\\.)+\\d+$)(^(([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])\\.)*([a-z0-9]|[a-z0-9][a-z0-9\\-]*[a-z0-9])$)",
         "readOnly":false,
         "hidden":false
      },
      {
         "name":"path",
         "title":"Enter the path to your S3 bucket folder",
         "description":"Enter the path to your S3 bucket folder",
         "type":"string",
         "isRequired":true,
         "pattern":"^[0-9a-zA-Z\\/\\!\\-_\\.\\*\\''\\(\\)]*((\\%SEGMENT_(NAME|ID)\\%)?\\/?)+$",
         "readOnly":false,
         "hidden":false
      },
      {
         "name":"compression",
         "title":"Compression format",
         "description":"Select the desired file compression format.",
         "type":"string",
         "isRequired":true,
         "readOnly":false,
         "enum":[
            "GZIP",
            "NONE"
         ]
      },
      {
         "name":"fileType",
         "title":"File type",
         "description":"Select the exported file type.",
         "type":"string",
         "isRequired":true,
         "readOnly":false,
         "hidden":false,
         "enum":[
            "json",
            "parquet"
         ],
         "default":"parquet"
      }
   ],
   "uiAttributes":{
      "documentationLink":"https://www.adobe.com/go/destinations-amazon-s3-en",
      "category":"cloudStorage",
      "connectionType":"S3",
      "flowRunsSupported":true,
      "monitoringSupported":true,
      "frequency":"Batch"
   },
   "destinationDelivery":[
      {
         "deliveryMatchers":[
            {
               "type":"SOURCE",
               "value":[
                  "batch"
               ]
            }
         ],
         "authenticationRule":"CUSTOMER_AUTHENTICATION",
         "destinationServerId":"{{destinationServerId}}"
      }
   ],
   "schemaConfig":{
      "profileRequired":false,
      "segmentRequired":false,
      "identityRequired":false
   },
   "aggregation":{
      "aggregationType":"BEST_EFFORT"
   },
   "batchConfig":{
      "allowMandatoryFieldSelection":false,
      "allowDedupKeyFieldSelection":false,
      "defaultExportMode":"FIRST_FULL_THEN_INCREMENTAL",
      "allowedExportModes":[
         "DAILY_FULL_EXPORT",
         "FIRST_FULL_THEN_INCREMENTAL"
      ],
      "allowedScheduleFrequency":[],
      "defaultFrequency":"EVERY_6_HOURS",
      "defaultStartTime":"00:00",
      "filenameConfig":{
         "allowedFilenameAppendOptions":[],
         "defaultFilenameAppendOptions":[],
         "defaultFilename":""
      },
      "datasetBatchConfig":{
         "allowedFoldernameAppendOptions":[
            "DESTINATION",
            "DATASET_ID",
            "DATASET_NAME",
            "DESTINATION_INSTANCE_ID",
            "DESTINATION_INSTANCE_NAME",
            "ORGANIZATION_NAME",
            "SANDBOX_NAME",
            "DATETIME",
            "EXPORT_TIME",
            "CUSTOM_TEXT"
         ],
         "defaultFoldernameAppendOptions":[
            "DATASET_ID",
            "EXPORT_TIME"
         ],
         "allowedExportModes":[
            "DAILY_FULL_EXPORT",
            "FIRST_FULL_THEN_INCREMENTAL"
         ],
         "allowedScheduleFrequency":[
            "DAILY",
            "EVERY_3_HOURS",
            "EVERY_6_HOURS",
            "EVERY_8_HOURS",
            "EVERY_12_HOURS",
            "ONCE"
         ]
      }
   },
   "maxProfileAttributes":9000,
   "maxIdentityAttributes":1000,
   "backfillHistoricalProfileData":true
}'

Le differenze chiave rispetto a una configurazione di destinazione di esportazione del pubblico sono evidenziate qui sopra:

Parametro
Valore per esportazioni set di dati
Descrizione
sources
["DATASETS"]
Contrassegna questa destinazione come destinazione di esportazione del set di dati. Per ulteriori dettagli, consulta Configurare il tipo di dati del pubblico.
schemaConfig.profileRequired
false
I set di dati non richiedono la mappatura del profilo.
schemaConfig.segmentRequired
false
I set di dati non richiedono la selezione del pubblico.
schemaConfig.identityRequired
false
I set di dati non richiedono il mapping delle identità.
aggregation.aggregationType
BEST_EFFORT
Le esportazioni di set di dati utilizzano l’aggregazione basata su procedure ottimali.
batchConfig.datasetBatchConfig
Vedi sopra
Controlla le opzioni di denominazione e pianificazione delle cartelle specifiche per le esportazioni dei set di dati. Per i dettagli completi sui parametri, vedi Configurazione esportazione set di dati.

Una risposta corretta restituisce la nuova configurazione di destinazione, incluso l’identificatore univoco (instanceId) della configurazione.

Passaggio 3: configurare l’autenticazione set-up-authentication

A seconda che sia stato specificato "authenticationRule": "CUSTOMER_AUTHENTICATION" o "authenticationRule": "PLATFORM_AUTHENTICATION" nella configurazione di destinazione precedente, è possibile impostare l’autenticazione utilizzando l’endpoint /destination o /credentials.

NOTE
CUSTOMER_AUTHENTICATION è la più comune delle due regole di autenticazione ed è quella da utilizzare se si desidera che gli utenti forniscano le proprie credenziali di archiviazione durante la connessione alla destinazione.

Passaggio 4: verificare l’interfaccia utente Experience Platform verify-ui

In base alle configurazioni di cui sopra, nel catalogo Experience Platform verrà ora visualizzata una nuova scheda di destinazione privata da utilizzare.

Quando gli utenti si connettono alla destinazione e selezionano i set di dati da esportare, visualizzano le opzioni di pianificazione e denominazione delle cartelle definite in datasetBatchConfig.

Passaggio 5: (facoltativo) pubblica la destinazione publish-destination

NOTE
Questo passaggio non è necessario se stai creando una destinazione privata per il tuo utilizzo e non stai cercando di pubblicarla nel catalogo delle destinazioni affinché altri clienti la possano utilizzare.

Dopo aver configurato la destinazione, utilizza l’API di pubblicazione della destinazione per inviare la configurazione ad Adobe per la revisione.

Passaggio 6: (facoltativo) documenta la destinazione document-destination

NOTE
Questo passaggio non è necessario se stai creando una destinazione privata per il tuo utilizzo e non stai cercando di pubblicarla nel catalogo delle destinazioni affinché altri clienti la possano utilizzare.

Se sei un fornitore di software indipendente (ISV) o un integratore di sistemi (SI) che crea una integrazione prodotta, utilizza il processo di documentazione self-service per creare una pagina di documentazione del prodotto per la tua destinazione nel catalogo delle destinazioni di Experience Platform.

Passaggi successivi next-steps

Una volta letto questo articolo, saprai come creare una destinazione di esportazione di set di dati utilizzando Destination SDK. Successivamente, il tuo team può utilizzare il flusso di lavoro di esportazione dei set di dati per esportare i set di dati nella tua destinazione.

Per ulteriori informazioni sulle operazioni che è possibile eseguire con Destination SDK, leggere i seguenti articoli:

recommendation-more-help
experience-platform-help-destinations