Configurar um destino de exportação para o conjunto de dados

Visão geral overview

Esta página descreve como usar o Destination SDK para configurar um destino que ofereça suporte a exportações de conjunto de dados. Use um destino de exportação do conjunto de dados para exportar conjuntos de dados brutos do Experience Platform para locais de armazenamento externos para relatórios, fluxos de trabalho de ciência de dados e muitos outros casos de uso.

Este guia usa Amazon S3 como exemplo em todo o projeto, mas os mesmos princípios de configuração se aplicam a qualquer tipo de destino baseado em arquivo com suporte no Destination SDK (Azure Blob Storage, SFTP, Azure Data Lake Storage Gen2, Google Cloud Storage e Data Landing Zone).

Para obter descrições detalhadas de todos os parâmetros usados neste guia, consulte opções de configuração no Destination SDK.

Pré-requisitos prerequisites

Antes de seguir para as etapas descritas abaixo, leia a página Introdução ao Destination SDK para obter informações sobre como obter as credenciais de autenticação do Adobe I/O necessárias e outros pré-requisitos para trabalhar com as APIs do Destination SDK.

Etapa 1: criar uma configuração de servidor e arquivo create-server-file-configuration

Comece usando o ponto de extremidade /destination-servers para criar uma configuração de servidor e arquivo.

Formato da API

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

Solicitação

A solicitação a seguir cria uma nova configuração de servidor de destino para um destino Amazon S3. Os valores fileType e compression são de modelo, o que significa que serão fornecidos pelo cliente no momento da conexão de destino através do customerDataFields que você definir na próxima etapa.

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

Uma resposta bem-sucedida retorna a nova configuração do servidor de destino, incluindo o identificador exclusivo (instanceId) da configuração. Armazene esse valor conforme necessário na próxima etapa.

Etapa 2: Criar configuração de destino create-destination-configuration

Depois de criar a configuração do servidor de destino na etapa anterior, use o ponto de extremidade da API /destinations para criar a configuração de destino.

Para conectar a configuração do servidor da etapa 1 a esta configuração de destino, substitua o valor destinationServerId na solicitação de API abaixo pelo valor instanceId obtido ao criar o servidor de destino na etapa 1.

Formato da API

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

Solicitação

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

As principais diferenças em relação a uma configuração de destino de exportação de público estão destacadas acima:

Parâmetro
Valor para exportações de conjunto de dados
Descrição
sources
["DATASETS"]
Marca esse destino como um destino de exportação do conjunto de dados. Consulte Configurar tipo de dados de público-alvo para obter detalhes.
schemaConfig.profileRequired
false
Os conjuntos de dados não exigem mapeamento de perfil.
schemaConfig.segmentRequired
false
Os conjuntos de dados não exigem seleção de público-alvo.
schemaConfig.identityRequired
false
Os conjuntos de dados não exigem mapeamento de identidade.
aggregation.aggregationType
BEST_EFFORT
As exportações de conjunto de dados usam agregação de melhor esforço.
batchConfig.datasetBatchConfig
Ver acima
Controla as opções de nomenclatura e agendamento da pasta específicas para exportações de conjunto de dados. Consulte Configuração de exportação do conjunto de dados para obter detalhes completos sobre o parâmetro.

Uma resposta bem-sucedida retorna a nova configuração de destino, incluindo o identificador exclusivo (instanceId) da configuração.

Etapa 3: configurar autenticação set-up-authentication

Dependendo de você ter especificado "authenticationRule": "CUSTOMER_AUTHENTICATION" ou "authenticationRule": "PLATFORM_AUTHENTICATION" na configuração de destino acima, é possível configurar a autenticação usando o ponto de extremidade /destination ou /credentials.

NOTE
CUSTOMER_AUTHENTICATION é a mais comum das duas regras de autenticação e é a que deve ser usada se você quiser que os usuários forneçam suas próprias credenciais de armazenamento ao se conectarem ao seu destino.

Etapa 4: verificar a interface do usuário do Experience Platform verify-ui

Com base nas configurações acima, o catálogo Experience Platform agora exibirá um novo cartão de destino privado para você usar.

Quando os usuários se conectarem ao destino e selecionarem conjuntos de dados para exportar, eles verão as opções de agendamento e nomenclatura de pastas definidas no datasetBatchConfig.

Etapa 5: (opcional) publicar seu destino publish-destination

NOTE
Esta etapa não é necessária se você estiver criando um destino privado para uso próprio e não estiver procurando publicá-lo no catálogo de destinos para que outros clientes usem.

Depois de configurar seu destino, use a API de publicação de destino para enviar sua configuração ao Adobe para revisão.

Etapa 6: (opcional) documentar seu destino document-destination

NOTE
Esta etapa não é necessária se você estiver criando um destino privado para uso próprio e não estiver procurando publicá-lo no catálogo de destinos para que outros clientes usem.

Se você for um ISV (Fornecedor Independente de Software) ou um SI (Integrador de Sistemas) criando uma integração de produtos, use o processo de documentação de autoatendimento para criar uma página de documentação de produto para seu destino no catálogo de destinos do Experience Platform.

Próximas etapas next-steps

Após a leitura deste artigo, agora você sabe como criar um destino de exportação de conjunto de dados usando o Destination SDK. Em seguida, sua equipe pode usar o fluxo de trabalho de exportação do conjunto de dados para exportar conjuntos de dados para seu destino.

Para saber mais sobre o que você pode fazer com o Destination SDK, leia os seguintes artigos:

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