データセットのエクスポート先を設定

概要 overview

ここでは、​ データセットの書き出しをサポートする宛先をDestination SDKで設定する方法について説明します。 データセットの書き出し先を使用して、レポート、データサイエンスワークフロー、その他の多くのユースケースのために、Experience Platformから外部ストレージの場所に生データセットを書き出します。

このガイドでは、全体を通してAmazon S3を例として使用しますが、Destination SDKでサポートされているファイルベースの宛先タイプ(Azure Blob Storage、SFTP、Azure Data Lake Storage Gen2、Google Cloud Storage、およびData Landing Zone)にも同じ設定原則が適用されます。

このガイドで使用されるすべてのパラメーターについて詳しくは、Destination SDKの設定オプション ​を参照してください。

前提条件 prerequisites

以下の手順に進む前に、Destination SDK入門 ページで、Destination SDK APIを操作するために必要なAdobe I/O認証情報およびその他の前提条件を取得する方法を参照してください。

手順 1:サーバーとファイル設定の作成 create-server-file-configuration

最初に、/destination-servers エンドポイントを使用して、​ サーバーとファイル設定を作成します。

API 形式

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

リクエスト

次のリクエストは、Amazon S3宛先の新しい宛先サーバー設定を作成します。 fileTypecompressionの値はテンプレート化されています。つまり、次の手順で定義したcustomerDataFieldsを介して、宛先接続時に顧客によって指定されます。

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

応答が成功すると、設定の一意の識別子(instanceId)を含む、新しい宛先サーバー設定が返されます。 この値は、次の手順で必要に応じて保存します。

手順 2:宛先の構成の作成 create-destination-configuration

前の手順で宛先サーバー設定を作成した後、/destinations API エンドポイントを使用して宛先設定を作成します。

サーバー設定を​ ステップ 1からこの宛先設定に接続するには、以下のAPI リクエストのdestinationServerId値を、​ ステップ 1で宛先サーバーを作成する際に取得したinstanceId値に置き換えます。

API 形式

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

リクエスト

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

オーディエンス書き出し先の設定との主な違いは次のとおりです。

パラメーター
データセット書き出しの値
説明
sources
["DATASETS"]
この宛先をデータセット書き出し先としてマークします。 詳しくは、​ オーディエンスデータタイプの設定を参照してください。
schemaConfig.profileRequired
false
データセットにはプロファイルマッピングは必要ありません。
schemaConfig.segmentRequired
false
データセットはオーディエンス選択を必要としません。
schemaConfig.identityRequired
false
データセットにID マッピングは必要ありません。
aggregation.aggregationType
BEST_EFFORT
データセットの書き出しは、ベストエフォート集計を使用します。
batchConfig.datasetBatchConfig
上記を参照
データセットの書き出しに固有のフォルダーの命名とスケジュール設定オプションを制御します。 パラメーターの詳細については、​ データセット書き出し設定を参照してください。

応答が成功すると、設定の一意の識別子(instanceId)を含む、新しい宛先設定が返されます。

手順3:認証の設定 set-up-authentication

上記の宛先設定で"authenticationRule": "CUSTOMER_AUTHENTICATION"または"authenticationRule": "PLATFORM_AUTHENTICATION"を指定したかどうかに応じて、/destinationまたは/credentials エンドポイントを使用して認証を設定できます。

NOTE
CUSTOMER_AUTHENTICATIONは、2つの認証ルールの中で最も一般的なものであり、ユーザーが宛先に接続する際に独自のストレージ資格情報を提供する場合に使用するものです。

手順4: Experience Platform UIの確認 verify-ui

上記の設定に基づいて、Experience Platform カタログには、新しいプライベート宛先カードが表示されるようになりました。

ユーザーが宛先に接続し、書き出すデータセットを選択すると、datasetBatchConfigで定義したスケジュールとフォルダーの命名オプションが表示されます。

手順5:(オプション)宛先の公開 publish-destination

NOTE
この手順は、自分で使用するプライベート宛先を作成しており、他の顧客が使用するために宛先カタログで公開することを検討していない場合は必要ありません。

宛先を設定した後、destination publishing APIを使用して、レビュー用にAdobeに設定を送信します。

手順6:(オプション)宛先を文書化する document-destination

NOTE
この手順は、自分で使用するプライベート宛先を作成しており、他の顧客が使用するために宛先カタログで公開することを検討していない場合は必要ありません。

独立系ソフトウェアベンダー(ISV)またはシステムインテグレータ(SI)で製品化統合を作成する場合、セルフサービスドキュメント化プロセスを使用して、宛先の製品ドキュメントページを Experience Platform 宛先カタログに作成します。

次の手順 next-steps

この記事では、Destination SDKを使用してデータセットの書き出し先を作成する方法について説明します。 次に、​ データセット書き出しワークフローを使用して、データセットを宛先に書き出すことができます。

Destination SDKの詳細については、次の記事をご覧ください。

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