バッチ設定 batch-configuration

Destination SDK でバッチ設定オプションを使用して、ユーザーに、書き出されたファイル名のカスタマイズと、その環境設定に応じた書き出しスケジュールの設定を許可します。

Destination SDK でファイルベースの宛先を作成する場合、デフォルトのファイル名および書き出しスケジュールを設定したり、Platform UI からこれらの設定を行うオプションをユーザーに与えたりできます。例えば、以下のような動作を設定できます。

  • ファイル名に特定の情報(オーディエンス ID、宛先 ID、カスタム情報など)を含める。
  • ユーザーに Platform UI からのファイル名のカスタマイズを許可する。
  • 設定した間隔でファイル書き出しが発生するように設定する。
  • Platform UI でユーザーが表示できるファイル名および書き出しスケジュールのカスタマイズオプションを定義する。

バッチ設定は、ファイルベースの宛先に対する宛先設定の一部です。

このコンポーネントがDestination SDKで作成される統合のどこに適合するかを把握するには、 設定オプションドキュメントの図を参照するか、Destination SDKを使用したファイルベースの宛先の設定方法に関するガイドを参照してください。

/authoring/destinations エンドポイントを介してファイル名および書き出しスケジュールを設定できます。このページに表示されるコンポーネントを設定できる、詳細な API 呼び出しの例については、以下の API リファレンスページを参照してください。

この記事では、宛先に使用できる、サポートされるすべてのバッチ設定オプションを説明し、Platform UI で顧客に何が表示されるかを示します。

IMPORTANT
Destination SDK でサポートされているすべてのパラメーター名および値は、大文字と小文字が区別 ​されます。大文字と小文字を区別することに関するエラーを避けるために、ドキュメントに示すように、パラメーター名および値を正確に使用してください。

サポートされる統合タイプ supported-integration-types

このページで説明される機能をサポートする統合のタイプについて詳しくは、以下の表を参照してください。

統合タイプ
機能のサポート
リアルタイム(ストリーミング)統合
×
ファイルベースの(バッチ)統合

サポートされるパラメーター supported-parameters

ここで設定する値は、ファイルベース宛先アクティブ化ワークフローのオーディエンスの書き出しスケジュールを設定ステップで表示されます。

"batchConfig":{
   "allowMandatoryFieldSelection":true,
   "allowDedupeKeyFieldSelection":true,
   "defaultExportMode":"DAILY_FULL_EXPORT",
   "allowedExportMode":[
      "DAILY_FULL_EXPORT",
      "FIRST_FULL_THEN_INCREMENTAL"
   ],
   "allowedScheduleFrequency":[
      "DAILY",
      "EVERY_3_HOURS",
      "EVERY_6_HOURS",
      "EVERY_8_HOURS",
      "EVERY_12_HOURS",
      "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%"
      },
   "segmentGroupingEnabled": true
   }
パラメーター
タイプ
説明
allowMandatoryFieldSelection
ブール値
true に設定すると、顧客は必須のプロファイル属性を指定できます。デフォルト値は false です。詳しくは、必須の属性を参照してください。
allowDedupeKeyFieldSelection
ブール値
true に設定すると、顧客は重複排除キーを指定できます。デフォルト値は false です。詳しくは、重複排除キーを参照してください。
defaultExportMode
列挙

デフォルトのファイルのエクスポートモードを定義します。サポートされている値:

  • DAILY_FULL_EXPORT
  • FIRST_FULL_THEN_INCREMENTAL

デフォルト値は DAILY_FULL_EXPORT です。ファイルエクスポートのスケジューリングについて詳しくは、バッチ有効化ドキュメントを参照してください。

allowedExportModes
リスト

顧客が使用できるファイルのエクスポートモードを定義します。サポートされている値:

  • DAILY_FULL_EXPORT
  • FIRST_FULL_THEN_INCREMENTAL
allowedScheduleFrequency
リスト

顧客が使用できるファイルエクスポートの頻度を定義します。サポートされている値:

  • ONCE
  • EVERY_3_HOURS
  • EVERY_6_HOURS
  • EVERY_8_HOURS
  • EVERY_12_HOURS
  • DAILY
defaultFrequency
列挙

デフォルトのファイルエクスポートの頻度を定義します。サポートされている値を以下に示します。

  • ONCE
  • EVERY_3_HOURS
  • EVERY_6_HOURS
  • EVERY_8_HOURS
  • EVERY_12_HOURS
  • DAILY

デフォルト値は DAILY です。

defaultStartTime
文字列
ファイルエクスポートのデフォルトの開始時間を定義します。24 時間のファイル形式を使用します。デフォルト値は「00:00」です。
filenameConfig.allowedFilenameAppendOptions
文字列

必須。ユーザーが選択できる、使用可能なファイル名マクロのリスト。書き出されたファイル名に追加される項目を決定します(オーディエンス ID、組織名、書き出し日時など)。defaultFilename を設定する場合、必ずマクロが重複するのを避けてください。

サポートされている値:

  • DESTINATION
  • SEGMENT_ID
  • SEGMENT_NAME
  • DESTINATION_INSTANCE_ID
  • DESTINATION_INSTANCE_NAME
  • ORGANIZATION_NAME
  • SANDBOX_NAME
  • DATETIME
  • CUSTOM_TEXT

マクロを定義する順序にかかわらず、Experience Platform UI は、常に、ここに提示された順序で表示します。

defaultFilename が空の場合、allowedFilenameAppendOptions リストには、少なくとも 1 つのマクロが含まれている必要があります。

filenameConfig.defaultFilenameAppendOptions
文字列
必須。ユーザーがチェックを外すことができる、事前に選択されたデフォルトのファイル名マクロ。

このリストのマクロは、allowedFilenameAppendOptions で定義されたもののサブセットです。
filenameConfig.defaultFilename
文字列
オプション。書き出されたファイル用にデフォルトのファイル名マクロを定義します。ユーザーは、これらを上書きできません。

allowedFilenameAppendOptions で定義されたマクロは、defaultFilename マクロの後に追加されます。

defaultFilename が空の場合、allowedFilenameAppendOptions に少なくとも 1 つのマクロを定義する必要があります。
segmentGroupingEnabled
ブール値

オーディエンス結合ポリシーに基づいて、アクティブ化されたオーディエンスを単一のファイルで書き出すか複数のファイルで書き出すかを定義します。サポートされている値:

  • true:結合ポリシーごとに 1 つのファイルを書き出します。
  • false:結合ポリシーに関係なく、オーディエンスごとに 1 つのファイルを書き出します。これはデフォルトの動作です。このパラメーターを完全に省略しても、同じ結果を得ることができます。

ファイル名設定 file-name-configuration

ファイル名設定マクロを使用して、書き出されたファイル名に含まれる必要があるものを定義します。以下の表にあるマクロは、ファイル名設定画面の UI で見つかる要素を記述します。

TIP
ベストプラクティスとして、常に、書き出されたファイル名に SEGMENT_ID マクロを含める必要があります。セグメント ID は一意なので、ファイル名にそれらを含めることは、ファイル名も必ず一意にするための最適な方法です。
マクロ
UI ラベル
説明
DESTINATION
宛先
UI の宛先名。
Amazon S3
SEGMENT_ID
セグメント ID
一意の、Platform で生成されたオーディエンス ID
ce5c5482-2813-4a80-99bc-57113f6acde2
SEGMENT_NAME
セグメント名
ユーザー定義のオーディエンス名
VIP subscriber
DESTINATION_INSTANCE_ID
宛先 ID
一意の、宛先インスタンスの Platform で生成された ID
77b891e5f-025a-4f0d-9e73-1919e71da3b0
DESTINATION_INSTANCE_NAME
宛先名
宛先インスタンスのユーザー定義の名前。
My 2022 Advertising Destination
ORGANIZATION_NAME
組織名
Adobe Experience Platform でのお客様の組織の名前。
My Organization Name
SANDBOX_NAME
サンドボックス名
顧客によって使用されるサンドボックスの名前。
prod
DATETIME または TIMESTAMP
日時

DATETIMETIMESTAMP は両方とも、ファイルが生成されたタイミングを定義しますが、形式が異なります。

  • DATETIME は、YYYYMMDD_HHMMSS の形式を使用します。
  • TIMESTAMP は、10 桁の Unix 形式を使用します。

DATETIMETIMESTAMP は、相互に排他的で、同時に使用できません。

  • DATETIME:20220509_210543
  • TIMESTAMP:1652131584
CUSTOM_TEXT
カスタムテキスト
ファイル名に含まれる、ユーザー定義のカスタムテキスト。defaultFilename で使用することはできません。
My_Custom_Text
TIMESTAMP
日時
ファイルが生成された時間の 10 桁のタイムスタンプ(Unix 形式)。
1652131584
MERGE_POLICY_ID
結合ポリシー ID
書き出されたオーディエンスを生成するために使用される結合ポリシーの ID。このマクロは、結合ポリシーに基づいてファイル内の書き出されたオーディエンスをグループ化する際に使用します。このマクロは segmentGroupingEnabled:true と併用してください。
e8591fdb-2873-4b12-b63e-15275b1c1439
MERGE_POLICY_NAME
結合ポリシー名
書き出されたオーディエンスの生成に使用される結合ポリシーの名前。このマクロは、結合ポリシーに基づいてファイル内の書き出されたオーディエンスをグループ化する際に使用します。このマクロは segmentGroupingEnabled:true と併用してください。
カスタム結合ポリシー

ファイル名設定の例

以下の設定例に、API 呼び出しで使用される設定と UI に表示されるオプションの対応を示します。

"filenameConfig":{
   "allowedFilenameAppendOptions":[
      "CUSTOM_TEXT",
      "SEGMENT_ID",
      "DATETIME"
   ],
   "defaultFilenameAppendOptions":[
      "SEGMENT_ID",
      "DATETIME"
   ],
   "defaultFilename": "%DESTINATION%"
}

事前選択されたマクロを含むファイル名設定画面を示す UI 画像

次の手順 next-steps

この記事を読むことで、ファイルベースの宛先に対するファイル名および書き出しスケジュールの設定方法について、理解を深めることができました。

その他の宛先コンポーネントについて詳しくは、以下の記事を参照してください。

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6