Configuración de un destino de exportación de conjunto de datos

Información general overview

En esta página se describe cómo usar Destination SDK para configurar un destino que admita exportaciones de conjuntos de datos. Use un destino de exportación de conjunto de datos para exportar conjuntos de datos sin procesar de Experience Platform a ubicaciones de almacenamiento externo para informes, flujos de trabajo de ciencia de datos y muchos otros casos de uso.

Esta guía utiliza Amazon S3 como ejemplo en, pero los mismos principios de configuración se aplican a cualquier tipo de destino basado en archivos compatible con Destination SDK (Azure Blob Storage, SFTP, Azure Data Lake Storage Gen2, Google Cloud Storage y Data Landing Zone).

Para obtener descripciones detalladas de todos los parámetros utilizados en esta guía, consulte opciones de configuración en Destination SDK.

Requisitos previos prerequisites

Antes de avanzar a los pasos descritos a continuación, lea la página de Introducción a Destination SDK para obtener información sobre cómo obtener las credenciales de autenticación de Adobe I/O necesarias y otros requisitos previos para trabajar con las API de Destination SDK.

Paso 1: Crear un servidor y una configuración de archivo create-server-file-configuration

Comience por usar el extremo /destination-servers para crear un servidor y una configuración de archivo.

Formato de API

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

Solicitud

La siguiente solicitud crea una nueva configuración del servidor de destino para un destino Amazon S3. Los valores fileType y compression están formados por plantillas, lo que significa que serán proporcionados por el cliente en el momento de la conexión de destino a través de customerDataFields que defina en el siguiente paso.

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 respuesta correcta devuelve la nueva configuración del servidor de destino, incluido el identificador único (instanceId) de la configuración. Almacene este valor tal como se requiere en el siguiente paso.

Paso 2: Crear la configuración de destino create-destination-configuration

Después de crear la configuración del servidor de destino en el paso anterior, use el extremo de la API /destinations para crear la configuración de destino.

Para conectar la configuración del servidor desde el paso 1 a esta configuración de destino, reemplace el valor destinationServerId de la solicitud de API siguiente por el valor instanceId obtenido al crear el servidor de destino en el paso 1.

Formato de API

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

Solicitud

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
}'

Las principales diferencias con respecto a la configuración de destino de exportación de una audiencia se resaltan arriba:

Parámetro
Valor de las exportaciones de conjuntos de datos
Descripción
sources
["DATASETS"]
Marca este destino como un destino de exportación de conjunto de datos. Consulte Configurar tipo de datos de audiencia para obtener más información.
schemaConfig.profileRequired
false
Los conjuntos de datos no requieren asignación de perfil.
schemaConfig.segmentRequired
false
Los conjuntos de datos no requieren la selección de audiencias.
schemaConfig.identityRequired
false
Los conjuntos de datos no requieren asignación de identidad.
aggregation.aggregationType
BEST_EFFORT
Las exportaciones de conjuntos de datos utilizan la agregación de mejor esfuerzo.
batchConfig.datasetBatchConfig
Véase más arriba
Controla las opciones de nomenclatura y programación de carpetas específicas de las exportaciones de conjuntos de datos. Consulte Configuración de exportación de conjuntos de datos para obtener detalles completos sobre el parámetro.

Una respuesta correcta devuelve la nueva configuración de destino, incluido el identificador único (instanceId) de la configuración.

Paso 3: Configuración de la autenticación set-up-authentication

Dependiendo de si especificó "authenticationRule": "CUSTOMER_AUTHENTICATION" o "authenticationRule": "PLATFORM_AUTHENTICATION" en la configuración de destino anterior, puede configurar la autenticación mediante el extremo /destination o /credentials.

NOTE
CUSTOMER_AUTHENTICATION es la más común de las dos reglas de autenticación y es la que debe usarse si desea que los usuarios proporcionen sus propias credenciales de almacenamiento al conectarse a su destino.

Paso 4: Verificar la interfaz de usuario de Experience Platform verify-ui

Según las configuraciones anteriores, el catálogo Experience Platform ahora mostrará una nueva tarjeta de destino privada para que la use.

Cuando los usuarios se conecten al destino y seleccionen los conjuntos de datos que se van a exportar, verán las opciones de programación y nomenclatura de carpetas que definió en datasetBatchConfig.

Paso 5: (Opcional) Publicación del destino publish-destination

NOTE
Este paso no es necesario si está creando un destino privado para su propio uso y no desea publicarlo en el catálogo de destinos para que lo utilicen otros clientes.

Después de configurar el destino, usa la API de publicación de destino para enviar la configuración a Adobe para que la revise.

Paso 6: (Opcional) Documente su destino document-destination

NOTE
Este paso no es necesario si está creando un destino privado para su propio uso y no desea publicarlo en el catálogo de destinos para que lo utilicen otros clientes.

Si es un proveedor de software independiente (ISV) o integrador de sistemas (SI) que crea una integración de productos, use el proceso de documentación de autoservicio para crear una página de documentación de producto para su destino en el catálogo de destinos de Experience Platform.

Próximos pasos next-steps

Al leer este artículo, ahora sabe cómo crear un destino de exportación de conjunto de datos con Destination SDK. A continuación, su equipo puede usar el flujo de trabajo de exportación del conjunto de datos para exportar conjuntos de datos a su destino.

Para obtener más información sobre lo que puede hacer con Destination SDK, lea los siguientes artículos:

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