# Salesforce Marketing Cloud V2 Export Integration

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

サンプルワークフローについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td/salesforce_marketing_cloud_exacttarget)をご覧ください。

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

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

## 同期または非同期API

この統合は、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でサポートケースを作成](https://help.salesforce.com/articleView?id=workcom_contact_support.htm&type=5)して、有効にしてもらうこともできます。

## Data Extension内の既存のオーディエンスデータを置換またはアップサート

この統合は、UpsertとReplaceもサポートしています。

### オーディエンスデータのアップサート

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

### オーディエンスデータの置換

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

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

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


replaceを使用すると、削除されたデータは回復できません。コネクタは新しいデータをプッシュする前にすべてのデータをクリアします。したがって、ジョブが成功するか失敗するかに関係なく、データはクリアされます。ベストプラクティスとして、一時的なデータやデータ履歴が重要でない場合にreplaceを使用してください。

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

## 前提条件

- Treasure Dataの基本知識
- Salesforce Marketing Cloudの基本知識
- TDアカウント


このコネクタでは、Data Extensionに各レコードを一意に識別する主キーが必要です。さらに、同期APIを使用する場合、Data Extensionには2つ以上のフィールドが必要です。新しいData Extensionを作成するために'Create Data Extension'を指定する場合、主キーとして1列のみがサポートされます。複数の列を指定するとエラーが発生します。

## Salesforce Marketing Cloudでインストール済みアプリを作成

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

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

### Enhanced Functionality Packageの作成

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


![](/assets/image-20191203-230537.e0bcdfcb7e2561762c7696348017cbdacc5ba65f7f802d2418ee8b77d769242c.3816ae6c.png)
3. 新しい画面の左側メニューで、**App** > **Installed Packages**に移動します。

![](/assets/image-20191203-230529.3bd5b94dddc4591cf914ae0be5d747aebc089a800d9012bc4f065f79b0894c19.3816ae6c.png)
4. Installed Packages画面で、**New**を選択します。

![](/assets/image-20191203-230520.b3ce22d3ac6c14b71d3179db2c83b6ad2bc76ea6cde6cc92354f9319c93303bf.3816ae6c.png)
5. **Name**と**Description**を入力します。
6. **Save**を選択します。

![](/assets/image-20191203-230511.fddfd1f6154dbd1b6c8f68a9931c82a18b1f6fe4ef53361e70cea3047d394444.3816ae6c.png)
7. Add Componentを選択します。
![](/assets/screen-shot-2022-05-27-16.27.17.5a0de3a6391853630496b0d42cec3bf348a24ea62175a17c782c91fbf2ca92de.3816ae6c.png)
8. **API Integration**を選択します。
9. **Next**を選択します。

![](/assets/image-20191203-230502.05e97edb5fa71052662c94ce53a805e48bd67c8fba685461aceaf8391d51cb1a.3816ae6c.png)
10. **Server-to-Server**を選択します。
11. **Next**を選択します。

![](/assets/image-20191203-230452.0549f71d5447c3b0504df60cb7a574569956b725c55e2721b191571026934996.3816ae6c.png)

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


![](/assets/screen-shot-2020-10-12-at-2.14.38-pm.ad0de0f5fc63fb8be9fe49f09040292c266999232b96ec7178da216cba3d6e53.3816ae6c.png)

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


![](/assets/image-20191203-230426.f3112d86f090248d0a16b48d4348f0b17af66704232fb6144437b0d50b20fdb5.3816ae6c.png)

## TD Consoleの使用

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

### 新しいデータ接続を作成

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

1. TD Consoleを開きます。
2. **Integrations Hub** > **Catalog**に移動します。
3. **Salesforce Marketing Cloud Version 2**を検索して選択します。


![](/assets/screen-shot-2022-05-27-16.37.54.e0fe3afa61c9868ee653ee5f3d1eec68d1d5a070f65e969290ace5795a33d42a.3816ae6c.png)
4. Enhanced Package Integrationを選択します。

![](/assets/image-20201106-212315.3d4c4002e0f5b268fde845df49e0e80b070a572437ab589713bf7de1efd42e36.3816ae6c.png)

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


- 複数のBUにアクセスするための**Account identifier or MID**
- トークンのスコープを制限するための**Scope**（詳細は[API scopes](https://developer.salesforce.com/docs/atlas.en-us.mc-apis.meta/mc-apis/rest-permissions-and-scopes.htm)を参照）


1. **Continue**を選択します。


![](/assets/image-20191203-230335.b828546b61ec5347e9550a24f61988f734754170ed0a8c717dffdac7cb10ad08.3816ae6c.png)

### 接続に名前を付ける

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


### Export Resultsの設定

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

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

1. TD Consoleを開きます。
2. **Data Workbench** > **Queries** > **New Query**に移動します。


![](/assets/image-20191203-230303.3c9be3f4b5261f47f8b8c475e4dee14e88168a433534524a562b9844ffd74f5c.3816ae6c.png)

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



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

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

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


![](/assets/image-20191203-230256.b3ecea9c19a2d4da4820f97082e0948c1c029522059012a707eb669f9d61f338.3816ae6c.png)

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


![](/assets/image-20251205-183442.9a2e2a9b42b58d80c353e1c9c446942172bc55a0ff9525c479bcc915e309ba5f.3816ae6c.png)

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


![](/assets/image-20251205-183634.aab337f5464f677d3921e59667bf16a09d6358e2bbb9f3df627bf026b99f9f31.3816ae6c.png)

1. 既存のData Extension Nameを使用していて、非同期APIを使用する場合は、**Using Async API**を選択します。同期APIを使用する場合は、ボックスをオフのままにします。
2. 新しいdata extensionを作成する場合は、**Create Data Extension**を選択します。新しく作成されたdata extensionで、Data Extension Nameを入力し、新しいdata extensionのPrimary Columnに名前を付けます。


![](/assets/image-20251205-183912.f42632c5cff1b64526cfcc9557d448b83135b3909fee3cf2ac7eeb00efbf1e92.3816ae6c.png)

1. **Long**と**Text**は、**Primary Column**でサポートされている2つのデータ型です。**Text**が**Primary Column**の場合、**Text length for Primary Key**を指定して、未使用のスペースを不必要に割り当てないことで、data extensionのパフォーマンスを最適化できます。
2. 新しいData Extensionを作成する際に各列のデータ型を定義するには、**Data Type Mapping**を使用します。
3. data extensionが送信可能な場合は、**Is Sendable**オプションを選択します。
4. **Subscriber Key**または**Email Address**で**Sendable Rule**を設定します。
5. data extensionの送信可能なプロパティとして**Sendable Column**を選択します。


![](/assets/image-20251205-184013.35ca57a62c11b7ce9cdde4616f4e5238677175cc0c47862d5463a06942c1e3c8.3816ae6c.png)

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


- 新しいレコードがある場合は追加し、レコードが重複している場合は更新するには**Upsert**
- 各新しいエクスポートでレコードを削除して完全に置き換えるには**Replace**
置き換えられたデータは**回復できません**。


![](/assets/image-20201020-225208.d972f688937823fbf90b1820df508fa72706de321f6ecec604383779d48513ed.3816ae6c.png)
16. **Done**を選択します。

### クエリの実行

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


![](/assets/image-20191203-230222.284b5bd59b85b34532412c3aee9c28c9e81788d270d8c33c4132e0a9227bd79f.3816ae6c.png)

Salesforce Marketing Cloud V2 Export統合にはタイムゾーン設定がないため、統合はSFMCアカウントのタイムゾーン設定を使用します。

## Activate a Segment in Audience Studio

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.


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- 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 Columns**to 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.


1. Set a **Schedule**.


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

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


1. Select **Create**.


If you need to create an activation for a batch journey, review [Creating a Batch Journey Activation](/products/customer-data-platform/journey-orchestration/batch/creating-a-batch-journey-activation).

## プラグインの設定とオプション

### 利用可能な設定

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

| Configuration name | Description  | Type | Sample value |
|  --- | --- | --- | --- |
| `client_id` | インストール済みパッケージのクライアントキー | string | `Th1s1s4n3x4mpl3Cl13nt1ds` |
| `client_secret` | インストール済みパッケージのクライアントシークレット | string | `Th1s1s4F4k3dCl13ntS3cr3t` |
| `auth_type` | 認証タイプ | string | `v1` (legacy packageの場合)
`v2` (enhanced packageの場合) |
| `auth_uri` | 認証URI (`auth_type=v2`の場合は必須) | string | `https://th1s1sf4k3d1nst4nc3h0st.auth.marketingcloudapis.com/` |
| `folder_path` | Data Extensionをエクスポートするフォルダパス
フォルダパスは以下の要件を満たす必要があります:- スラッシュで始まる
- 最大8レベルのフォルダを持つ
- 複数の連続したスラッシュがない
- フォルダパス内のフォルダ名は128文字を超えることはできません

 | string | 
```
/Data Extensions/FolderPath2/FolderPath3/FolderPath3
```
 |
| `create_folder_if_not_exists` | `folder_path`に新しいフォルダを作成するかどうかを示すフラグ
`folder_path`が提供されている（かつ空でない）場合にのみ有効 | boolean
デフォルトはfalse | `true` (パスで指定されたすべてのディレクトリが作成されます。既に存在する場合、またはパスの一部が無効な場合を除く)
`false` (存在しない場合、新しいフォルダを作成しない) |
| `de_name` | Data Extension名 | string | `data_extension_name` |
| `create_new_de` | data extensionが存在しない場合に新しいdata extensionを作成するかどうかを示すフラグ | boolean
デフォルトはfalse | `true` (DEが存在しない場合は新しいDEを作成)
`false` (DEが存在しない場合は新しいDEを作成しない) |
| `primary_column` | 主列の名前 (`create_new_de=true`の場合は必須)
1列のみ指定できます。 | string |  |
| `primary_text_length` | 主列として選択された場合のテキストフィールドの長さ | integer | max: 4000, min: 10 (デフォルト: 4000) |
| `column_options` | `create_new_de=true`の場合にのみ適用されます。
新しいData Extensionの各列のデータ型を指定します。
サポートされているデータ型: TEXT, NUMBER, DATE, BOOLEAN, EMAILADDRESS, PHONE, DECIMAL, LOCALE, BASE16ENCRYPTED, BASE16ENCRYPTEDEMAIL | string | `col1:TEXT(100);col2:NUMBER;col3:DECIMAL(18,2);col4:DATE` |
| `is_sendable` | 作成されたDEが送信可能かどうかを示すフラグ | boolean
デフォルトはfalse | `true`
`false` |
| `sendable_rule` | アカウントで設定された送信可能なビジネスルール (`is_sendable=true`の場合は必須) | string | `Subscriber Key` (ビジネスルールがSubscriber Keyの場合)
`Email Address` (ビジネスルールがEmail Addressの場合) |
| `sendable_column` | 送信可能なプロパティとして使用する列名 (`is_sendable=true`の場合は必須) | string | `my_sendable_column` |
| `data_operation` | 挿入前にDE内のデータをクリアするかどうかを決定 | string
デフォルトはupsert | `upsert`, `replace` |
| `async` | SFMCから非同期または同期APIを使用するかを示すフラグ | boolean
デフォルトはfalse | `true` (非同期APIを使用)
`false` (同期APIを使用) |
| `continue_on_failure`
 | 挿入エラーがある場合に実行を続けるかどうかを示すフラグ (同期APIにのみ適用) (ジョブはSFMCサーバー側エラーが発生した場合にのみ続行されます。Treasure Data側でエラーが発生した場合（誤った認証情報、レコードの無効な形式など）、ジョブはエラーで失敗します)
falseに設定されている場合、Salesforce Marketing Cloud側のAPI動作により、エクスポートは部分的にレコードを正常に送信できる可能性があります。
コネクタが101レコードをエクスポートすると仮定すると => これは3つのバッチ(50, 50, 1)に分割されます:
- 最初のバッチが失敗した場合 => 101レコードすべてが更新されません
- 2番目のバッチが失敗した場合 => 50レコードが更新され、51レコードが更新されません
- 3番目のバッチが失敗した場合 => 100レコードが更新され、1レコードが更新されません

 | boolean
デフォルトはtrue
 | `true`
`false`
 |
| `records_per_batch` | 1回のAPI呼び出しで送信されるレコード数。 (このオプションは非同期APIにのみ適用されます。) | integer | max: 32000 (デフォルト), min: 100 |


### 設定例

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


```yaml
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**を使用する設定例。


```yaml
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**を使用する設定例。


```yaml
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をエクスポート**するための設定例


```yml
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
```

## 付録

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