Salesforce Marketing Cloud V2 Export Integration

Treasure Dataは、ユーザーセグメントをSalesforce Marketing Cloud (ExactTarget)に公開し、顧客にパーソナライズされたメールを送信できるようにします。Web、モバイル、CRM、およびその他のデータソースからのファーストパーティデータを使用して、データ駆動型のメールキャンペーンを実行できます。

サンプルワークフローについては、Treasure Boxesをご覧ください。

Treasure Dataは、ジョブ結果をSalesforce Marketing Cloud（SFMC）に書き込むための2つの方法、SFTPとSFMCプラグインを提供しています。

このSFMCプラグインは、小規模および中規模のデータセットに使用できます。大規模なデータセットの場合は、SFTPの使用をお勧めします。

この統合は、SFMCにレコードを配置するための2種類のAPIをサポートしています: 同期APIと非同期API。

ベストプラクティスとして、100,000レコード未満の結果セットをSFMCに配置しようとしている場合、同期APIが最適です。ただし、100万以上のデータセットを送信する予定がある場合は、同期APIと比較してより高い可用性と信頼性を提供する非同期APIの使用を検討してください。

非同期APIを使用するには、SFMCアカウントがSalesforce Marketing CloudからData Extensions Async REST APIとして有効になっていることを確認してください。また、Salesforce Marketing Cloudでサポートケースを作成して、有効にしてもらうこともできます。

この統合は、Add、Upsert、Replaceの3つのデータ操作をサポートしています。

Addは、主キーがターゲットdata extensionにまだ存在しないレコードのみを挿入します。主キーが既に存在するレコードはスキップされ、更新されることはありません。そのため、既存レコードのフィールド値はそのまま維持されます。data extension内の既存レコードを変更せずに、新規のオーディエンスメンバーのみを取り込みたい場合にAddを使用します。

Addは常に非同期APIを使用します。エクスポートUIでは、Addを選択するとUsing Async APIが自動的に有効になり、設定した値は無視されます。CLIまたはYAMLでエクスポートを設定する場合は、async: trueを明示的に指定してください。指定しない場合、ジョブは設定エラーで失敗します。

ターゲットdata extensionには主キーが必要です。この統合は主キーを使用して、レコードが既に存在するかどうかを判断します。data extensionが複合主キーを持つ場合、すべての主キー列が一致したときにのみ、レコードが既存として扱われます。

Upsertは、既存のデータを更新し、data extensionに新しい追加データを挿入します。更新と挿入の両方の操作は、data extension主キーを使用して、レコードが存在したかどうかを判断し、更新または挿入を実行します。ターゲットdata extension内のすべての既存データは保持されます。

Replaceは、データを更新する前に、ターゲットdata extension内のすべての既存データをクリアします。このモードは、毎回ターゲット顧客にメールを送信するために、data extension内の最新のデータのみが必要な場合に便利です。

この統合でreplaceが選択されている場合:

• エクスポート結果にデータエラー（NULL値、誤ったデータ型、無効な主キー）がある場合、Data Extension内のすべてのレコードがクリアされ、回復できませんが、無効なデータはエクスポートされません。
• エクスポート結果にスキーマエラー（primary_keyの欠落）がある場合、data extension内の既存のレコードはクリアされません。

replaceを使用するには、アカウントがEnterprise 2.0アカウントであり、インストールされたパッケージに管理者権限が必要です。詳細については、カスタマーサクセス担当者にお問い合わせください。

• Treasure AIの基本知識
• Salesforce Marketing Cloudの基本知識
• Treasure アカウント

このコネクタでは、Data Extensionに各レコードを一意に識別する主キーが必要です。さらに、同期APIを使用する場合、Data Extensionには2つ以上のフィールドが必要です。新しいData Extensionを作成するために'Create Data Extension'を指定する場合、列名をカンマ区切りで指定することで、最大4列までの複合主キーを指定できます。

Treasure Dataは、Salesforce Marketing CloudでLegacyとEnhanced Packageの両方をサポートしています。

Enhanced Packageの作成を強くお勧めします。

1. Salesforce Marketing Cloudアカウントにログオンします。
2. Welcome Pageで、右上隅の名前を選択します。Setupを選択します。

3. 新しい画面の左側メニューで、App > Installed Packagesに移動します。

4. Installed Packages画面で、Newを選択します。

5. NameとDescriptionを入力します。 6. Saveを選択します。

7. Add Componentを選択します。 8. API Integrationを選択します。 9. Nextを選択します。

10. Server-to-Serverを選択します。 11. Nextを選択します。

12. Contacts > AudiencesとContacts > List and Subscribersを見つけます。
13. Replace Audience機能を使用するには、両方の下でReadとWriteを選択します。
14. Data > Data Extensionsを見つけます。
15. ReadとWriteを選択します。 Salesforce Marketing Cloudにデータを書き込むには、これらの権限が必要です。
16. Saveを選択します。

17. Componentsパネルを見つけます。
18. Client Id、Client Secret、およびAuthentication Base URIをメモします。 Treasure DataからSalesforce Marketing Cloudにデータを書き込むために、この情報を使用します。

TDクエリ結果をSalesforce Marketing Cloud Data Extensionにエクスポートするには、次の手順を実行します:

データ接続を設定する際、統合にアクセスするための認証を提供します。Treasure Dataでは、認証を設定してから、ソース情報を指定します。

1. Treasure コンソールを開きます。
2. Integrations Hub > Catalogに移動します。
3. Salesforce Marketing Cloud Version 2を検索して選択します。

4. Enhanced Package Integrationを選択します。

5. Enhanced Functionality Packageを選択し、Client Id、Client Secret、およびAuthentication Base URI（SFMCでenhanced packageを作成した際に取得したもの）を入力します。オプションで、以下を指定できます:

• 複数のBUにアクセスするためのAccount identifier or MID
• トークンのスコープを制限するためのScope（詳細はAPI scopesを参照）

6. Continueを選択します。

1. 接続の名前を入力します。
2. Doneを選択します。

この手順では、クエリを作成または再利用します。クエリで、データ接続を設定します。

場合によっては、クエリで列マッピングを定義する必要があります。

1. Treasure コンソールを開きます。
2. Data Workbench > Queries > New Queryに移動します。

3. クエリエディタでクエリを入力します。例えば:

SELECT
 name as customer_name,
 email as primary_key
FROM
 data_extension
limit 10

主キーはテキストフィールドにすることができます。

4. クエリエディタの上部にあるExport Resultsを選択します。

5. 既存の接続を選択します。
6. Data Extension Nameを指定します。オプションで、Data Extensionが存在しない場合は、Create Data Extensionを選択して、まったく新しいdata extensionを作成します。

7. Folder Pathを指定します。オプションで、Folder Path内のいずれかのフォルダが存在しない場合は、Create New Folder if not Existsを選択してフォルダを作成します。

8. 既存のData Extension Nameを使用していて、非同期APIを使用する場合は、Using Async APIを選択します。同期APIを使用する場合は、ボックスをオフのままにします。後述のData OperationでAddを選択した場合は、常に非同期APIが使用され、この設定は無視されます。
9. 新しいdata extensionを作成する場合は、Create Data Extensionを選択します。新しく作成されたdata extensionで、Data Extension Nameを入力し、新しいdata extensionのPrimary Columnに名前を付けます。

10. LongとTextは、Primary Columnでサポートされている2つのデータ型です。列名をカンマ区切りで最大4つまで入力することで（例: customer_id,region_code）、複合主キーを指定できます。Text列がPrimary Columnの場合、Text length for Primary Keyを指定して、未使用のスペースを不必要に割り当てないことで、data extensionのパフォーマンスを最適化できます。この長さは、Data Type Mappingに独自のエントリを持たないすべてのtextのPrimary Columnに適用されます。
11. 新しいData Extensionを作成する際に各列のデータ型を定義するには、Data Type Mappingを使用します。
12. data extensionが送信可能な場合は、Is Sendableオプションを選択します。
13. Subscriber KeyまたはEmail AddressでSendable Ruleを設定します。
14. data extensionの送信可能なプロパティとしてSendable Columnを選択します。

15. オプションで、新しいdata extensionを作成する場合は、行ベースのデータリテンションを設定します:
    • Enable Row-Based Retention を選択すると、各行が独自の保持期間を個別に追跡します。選択すると Retention Period (Days) フィールドが表示されます。
    • Retention Period (Days) に各行を保持する日数を設定します（例: 30）。

• Enable Row-Based Retention を選択すると、各行が独自の保持期間を個別に追跡します。選択すると Retention Period (Days) フィールドが表示されます。
• Retention Period (Days) に各行を保持する日数を設定します（例: 30）。

16. data extensionのData Operationを選択します

• data extensionに主キーがまだ存在しないレコードのみを挿入するにはAdd。既存のレコードはスキップされ、変更されることはありません。常に非同期APIが使用されます。
• 新しいレコードがある場合は追加し、レコードが重複している場合は更新するにはUpsert
• 各新しいエクスポートでレコードを削除して完全に置き換えるにはReplace 置き換えられたデータは回復できません。

17. Doneを選択します。

1. Runを選択してクエリを実行します。
2. クエリ結果が設定されたdata extensionに書き込まれていることを確認します。

You can also send segment data to the target platform by creating an activation in the Audience Studio.

1. Navigate to Audience Studio.
2. Select a parent segment.
3. Open the target segment, right-mouse click, and then select Create Activation.
4. In the Details panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
5. Customize the activation output in the Output Mapping panel.

• Attribute Columns
  • Select Export All Columns to export all columns without making any changes.
  • Select + Add Columns to add specific columns for the export. The Output Column Name pre-populates with the same Source column name. You can update the Output Column Name. Continue to select + Add Columnsto add new columns for your activation output.
• String Builder
  • + Add string to create strings for export. Select from the following values:
    • String: Choose any value; use text to create a custom value.
    • Timestamp: The date and time of the export.
    • Segment Id: The segment ID number.
    • Segment Name: The segment name.
    • Audience Id: The parent segment number.

6. Set a Schedule.

• Select the values to define your schedule and optionally include email notifications.

7. Select Create.

Salesforce Marketing Cloud V2エクスポート統合で使用可能な設定オプションを以下の表に示します。

/Data Extensions/FolderPath2/FolderPath3/FolderPath3

Enhanced packageを使用してdata extensionをupsertするために同期APIを使用する設定例。

out:
 type: salesforce_marketing_cloud_v2
 client_id: Th1s1s4n3x4mpl3Cl13nt1ds
 client_secret: Th1s1s4F4k3dCl13ntS3cr3t
 auth_type: v2
 auth_uri: https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/
 de_name: data_extension_name
 continue_on_failure: false

Enhanced packageを使用してdata extensionをupsertするために非同期APIを使用する設定例。

out:
 type: salesforce_marketing_cloud_v2
 client_id: Th1s1s4n3x4mpl3Cl13nt1ds
 client_secret: Th1s1s4F4k3dCl13ntS3cr3t
 auth_type: v2
 auth_uri: https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/
 de_name: data_extension_name
 async: true

Enhanced packageを使用してdata extensionをupsertし、存在しない場合は新しいSendable data Extensionを作成するために非同期APIを使用する設定例。

out:
 type: salesforce_marketing_cloud_v2
 client_id: Th1s1s4n3x4mpl3Cl13nt1ds
 client_secret: Th1s1s4F4k3dCl13ntS3cr3t
 auth_type: v2
 auth_uri: https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/
 de_name: data_extension_name
 create_new_de: true
 primary_column: primary_key
 primary_text_length: 32
 column_options: col1:TEXT(100);col2:NUMBER;col3:DECIMAL(18,2);col4:DATE
 is_sendable: true
 sendable_column: mytext
 sendable_rule: Subscriber Key
 async: true
 records_per_batch: 32000

行ベースのリテンションを設定して新しいData Extensionを作成する設定例。

out:
 type: salesforce_marketing_cloud_v2
 client_id: Th1s1s4n3x4mpl3Cl13nt1ds
 client_secret: Th1s1s4F4k3dCl13ntS3cr3t
 auth_type: v2
 auth_uri: https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/
 de_name: data_extension_name
 create_new_de: true
 primary_column: primary_key
 retention_period_days: 30
 enable_row_based_retention: true

特定のフォルダにdata extensionをエクスポートするための設定例

out:
 type: salesforce_marketing_cloud_v2
 client_id: xxxxxxxxxxxxxxxxxxxxxxxxx
 client_secret: xxxxxxxxxxxxxxxxxxxxxxxxx
 auth_type: v2
 auth_uri: https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/
 folder_path: /Data Extensions/FolderPath2/FolderPath3/FolderPath3
 create_folder_if_not_exists: true
 de_name: data_extension_name
 create_new_de: true
 primary_column: primary_key
 primary_text_length: 32
 column_options: col1:TEXT(100);col2:NUMBER;col3:DECIMAL(18,2);col4:DATE
 is_sendable: true
 sendable_column: mytext
 sendable_rule: Subscriber Key
 async: true
 records_per_batch: 32000

複合主キーを設定して新しいData Extensionを作成する設定例

out:
 type: salesforce_marketing_cloud_v2
 client_id: Th1s1s4n3x4mpl3Cl13nt1ds
 client_secret: Th1s1s4F4k3dCl13ntS3cr3t
 auth_type: v2
 auth_uri: https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/
 de_name: data_extension_name
 create_new_de: true
 primary_column: customer_id,region_code
 primary_text_length: 500
 column_options: customer_id:TEXT(100)

この例では、customer_idとregion_codeの両方が主キーです。customer_idはcolumn_optionsにより長さ100になります。region_codeにはcolumn_optionsのエントリがないため、primary_text_length（500）にフォールバックします。

• コネクタはHTTPS経由でSFMC v2サーバー/インスタンスエンドポイントと通信します。
• HTTPSおよびSSL/TLS暗号化はSFMC v2サーバーによって強制され、処理前にコネクタによってチェックされます。