見込み客オーディエンスをストレージの場所に書き出すためのファイルベースの宛先の設定
概要 overview
このページでは、Destination SDKを使用して、カスタムの ファイル形式オプションおよびカスタムの ファイル名設定を持つファイルベースの宛先を設定し、 見込み客オーディエンスを書き出す方法について説明します。 このガイドの例では、見込み客プロファイルのオーディエンスをAmazon S3 の場所に書き出す方法を説明しています。
また、STFP やその他のストレージの場所を設定して、見込み客オーディエンスを書き出すこともできます。 覚えておくべき重要な部分は、以下のスニペットを 手順 2 の宛先設定に追加して、 ワークフローで見込み客オーディエンスを書き出すを宛先に有効にすることです。
"sources": [
"UNIFIED_PROFILE_PROSPECTS"
],
以下で使用されるパラメーターについて詳しくは、Destinations SDK の設定オプションを参照してください。
前提条件 prerequisites
以下に説明する手順に進む前に、Destination SDKの概要ページを読んで、Destination SDKAPI を使用するために必要な認証資格情報およびその他の前提条件について確認してください。
手順 1：サーバーとファイル設定の作成 create-server-file-configuration
まず、/destination-server エンドポイントを使用して サーバーとファイル設定を作成します。
API 形式
POST platform.adobe.io/data/core/activation/authoring/destination-servers
リクエスト
次のリクエストは、ペイロード内のパラメーター設定に基づいて、新しい宛先サーバー設定を作成します。
以下のペイロードには、ユーザーがExperience PlatformUI で定義できるカスタム CSV ファイル形式設定パラメーターを含む、一般的なAmazon S3 設定が含まれています。
curl -X POST https://platform.adobe.io/data/core/activation/authoring/destination-server \
-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 destination server with custom file formatting options",
"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":{
"sep":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.sep}}"
},
"encoding":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.encoding}}"
},
"quote":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.quote}}"
},
"quoteAll":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.quoteAll}}"
},
"escape":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.escape}}"
},
"escapeQuotes":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.escapeQuotes}}"
},
"header":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.header}}"
},
"ignoreLeadingWhiteSpace":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.ignoreLeadingWhiteSpace}}"
},
"nullValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.nullValue}}"
},
"dateFormat":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.dateFormat}}"
},
"charToEscapeQuoteEscaping":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.charToEscapeQuoteEscaping}}"
},
"emptyValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{customerData.dateFormat}}"
}
}
}
}'
リクエストが成功した場合は、設定の一意の ID （instanceId）を含む、新しい宛先サーバー設定が返されます。 この値は、次の手順で必要になるので保存します。
手順 2：宛先の構成の作成 create-destination-configuration
前の手順で宛先サーバーとファイル形式設定を作成したら、/destinations API エンドポイントを使用して宛先設定を作成できるようになりました。
手順 1 のサーバー設定をこの宛先設定に接続するには、以下の API リクエストの destinationServerId の値を、 手順 1 で宛先サーバーを作成する際に取得した値に置き換えます。
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 destination to export prospect audiences",
"description":"Amazon S3 destination to export prospect audiences",
"status":"TEST",
"sources": [
"UNIFIED_PROFILE_PROSPECTS"
],
"customerAuthenticationConfigurations":[
{
"authType":"S3"
}
],
"customerEncryptionConfigurations":[
],
"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":"sep",
"title":"Enter your desired separator for each field and value",
"description":"Enter your desired separator for each field and value",
"type":"string",
"isRequired":false,
"readOnly":false,
"hidden":false
},
{
"name":"encoding",
"title":"Select the desired CSV file encoding",
"description":"Select the desired CSV file encoding",
"type":"string",
"enum":[
"UTF-8",
"UTF-16"
],
"isRequired":false,
"readOnly":false,
"hidden":false
},
{
"name":"quote",
"title":"Quoted values escape character",
"description":"Enter the desired character to be used for escaping quoted values.",
"type":"string",
"isRequired":false,
"readOnly":false,
"hidden":false
},
{
"name":"quoteAll",
"title":"Escape all quoted values",
"description":"Select whether to escape all quoted values.",
"type":"string",
"enum":[
"true",
"false"
],
"default":"true",
"isRequired":true,
"readOnly":false,
"hidden":false
},
{
"name":"escape",
"title":"Quote escaping character",
"description":"Enter the desired character to be used for escaping quotes inside an already quoted value.",
"type":"string",
"isRequired":false,
"readOnly":false,
"hidden":false
},
{
"name":"escapeQuotes",
"title":"Enclose quoted values within quotes",
"description":"Select whether values containing quotes should always be enclosed in quotes.",
"type":"string",
"enum":[
"true",
"false"
],
"isRequired":false,
"default":"true",
"readOnly":false,
"hidden":false
},
{
"name":"header",
"title":"Generate file header.",
"description":"Select whether to write the names of columns as the first line of the exported files.",
"type":"string",
"isRequired":false,
"enum":[
"true",
"false"
],
"readOnly":false,
"default":"true",
"hidden":false
},
{
"name":"ignoreLeadingWhiteSpace",
"title":"Ignore leading white space",
"description":"Select whether leading whitespaces should be trimmed from exported values.",
"type":"string",
"isRequired":false,
"enum":[
"true",
"false"
],
"readOnly":false,
"default":"true",
"hidden":false
},
{
"name":"nullValue",
"title":"NULL value string format",
"description":"Enter the string representation of a NULL value. ",
"type":"string",
"isRequired":false,
"readOnly":false,
"hidden":false
},
{
"name":"dateFormat",
"title":"Date format",
"description":"Enter the desired date format. ",
"type":"string",
"default":"yyyy-MM-dd",
"isRequired":false,
"readOnly":false,
"hidden":false
},
{
"name":"charToEscapeQuoteEscaping",
"title":"Quote escaping escape character",
"description":"Enter the desired character to be used for escaping the escaping of a quote character.",
"type":"string",
"isRequired":false,
"readOnly":false,
"hidden":false
},
{
"name":"emptyValue",
"title":"Empty value string format",
"description":"Enter the string representation of an empty value.",
"type":"string",
"isRequired":false,
"readOnly":false,
"default":"",
"hidden":false
},
{
"name":"compression",
"title":"Compression format",
"description":"Select the desired file compression format.",
"type":"string",
"isRequired":true,
"readOnly":false,
"enum":[
"SNAPPY",
"GZIP",
"DEFLATE",
"NONE"
]
},
{
"name":"fileType",
"title":"File type",
"description":"Select the exported file type.",
"type":"string",
"isRequired":true,
"readOnly":false,
"hidden":false,
"enum":[
"csv",
"json",
"parquet"
],
"default":"csv"
}
],
"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":true,
"segmentRequired":true,
"identityRequired":true
},
"batchConfig":{
"allowMandatoryFieldSelection":true,
"allowDedupeKeyFieldSelection":true,
"defaultExportMode":"DAILY_FULL_EXPORT",
"allowedExportMode":[
"DAILY_FULL_EXPORT"
],
"allowedScheduleFrequency":[
"DAILY",
"ONCE"
],
"defaultFrequency":"DAILY",
"defaultStartTime":"00:00",
"filenameConfig":{
"allowedFilenameAppendOptions":[
"SEGMENT_NAME",
"DESTINATION_INSTANCE_ID",
"DESTINATION_INSTANCE_NAME",
"ORGANIZATION_NAME",
"SANDBOX_NAME",
"DATETIME",
"CUSTOM_TEXT"
],
"defaultFilenameAppendOptions":[
"DATETIME"
],
"defaultFilename":"%DESTINATION%_%SEGMENT_ID%"
},
"backfillHistoricalProfileData":true
}
}'
リクエストが成功した場合は、設定の一意の ID （instanceId）を含む、新しい宛先設定が返されます。 宛先設定を更新するための HTTP リクエストを別途行う必要がある場合に、この値を必要に応じて保存します。
手順 3:Experience PlatformUI の確認 verify-ui
上記の設定に基づいて、Experience Platformカタログには、使用する新しいプライベート宛先カードが表示されるようになりました。
以下の画像と録画では、 ファイルベースの宛先のアクティベーションワークフローのオプションが、宛先設定で選択したオプションにどのように一致するかを確認してください。
宛先に関する詳細を入力する場合、設定で設定したカスタムデータフィールドが、どのようなフィールドで表示されるかを確認してください。
書き出し間隔をスケジュールする際には、batchConfig 設定で設定したフィールドが各フィールドにどのように表示されるかを確認してください。
ファイル名の設定オプションを表示すると、設定で設定した filenameConfig のオプションが、表示されるフィールドでどのように表れているかに注意してください。
上記のフィールドを調整する場合は、 手順 1 および 2 を繰り返し、必要に応じて設定を変更します。
手順 4:（オプション）宛先のPublish publish-destination
宛先を設定した後、destination publishing API を使用して、設定をレビュー用にAdobeに送信します。
手順 5:（オプション）宛先のドキュメント化 document-destination
独立系ソフトウェアベンダー（ISV）またはシステムインテグレータ（SI）で製品化統合を作成する場合、セルフサービスドキュメント化プロセスを使用して、宛先の製品ドキュメントページを Experience Platform 宛先カタログに作成します。
次の手順 next-steps
この記事を読むことで、Destination SDKを使用して、見込み客オーディエンスを書き出すカスタム Amazon S3 宛先を作成する方法を理解しました。