# Salesforce Marketing Cloud Import Integration CLI

## 'td' コマンド v0.11.9 以降をインストール

最新の [Treasure Data Toolbelt](https://toolbelt.treasuredata.com/) をインストールできます。


```
$ td --version
0.15.3
```

## 設定ファイルの作成

Salesforce Marketing Cloud アカウントのアクセス情報を使用して、次の例のように設定ファイル(例: `load.yml`)を準備します。


```yaml
in:
  type: salesforce_marketing_cloud_v2
  client_id: client_id
  client_secret: client_secret
  auth_type: v2
  auth_uri: auth_uri
  account_id: account_id
  target: target_name
  data_extension_names: data_extension_names
  shared_data_extension: false
  incremental: false
  maximum_retries: 7
  initial_retry_interval_millis: 1000
  maximum_retry_interval_millis: 120000

filters:
- type: add_time
  to_column:
    name: time
    type: timestamp
  from_value:
    mode: upload_time
- type: rename
  rules:
  - rule: upper_to_lower
  - rule: character_types
    pass_types: [ "a-z", "0-9" ]
    pass_characters: "_"
    replace: "_"

out:
  type: td
  apikey: td_api_key
  endpoint: td_endpoint
  database: database
  table: table
  time_column: time
  mode: replace
  default_timestamp_format: '%d/%m/%Y'
```

この例では、Salesforce Marketing Cloud の `Campaign` Data Source をダンプします:

- `client_id`: Salesforce Marketing Cloud のクライアント ID。
- `client_secret`: Salesforce Marketing Cloud のクライアントシークレット。
- `target`: インポートする Salesforce Marketing Cloud のエンティティオブジェクト。


## インポートするデータのプレビュー(オプション)

`td connector:preview` コマンドを使用して、インポートされるデータをプレビューできます。


```
$ td connector:preview load.yml
```

## ロードジョブの実行

ロードジョブを送信します。データサイズによっては数時間かかることがあります。ユーザーは、データが保存されるデータベースとテーブルを指定する必要があります。

Treasure Data のストレージは時間でパーティショニングされているため、`--time-column` オプションを指定することをお勧めします([データパーティショニング](https://docs.treasuredata.com/smart/project-product-documentation/data-partitioning-in-treasure-data)も参照してください)。このオプションが指定されていない場合、データコネクタは最初の `long` または `timestamp` カラムをパーティショニング時間として選択します。`--time-column` で指定するカラムのタイプは、`long` または `timestamp` タイプのいずれかである必要があります。

データに時間カラムがない場合は、`add_time` フィルターオプションを使用して追加できます。詳細は [add_time filter plugin](https://docs.treasuredata.com/smart/project-product-documentation/add_time-filter-function) を参照してください。


```bash
$ td connector:issue load.yml --database td_sample_db --table td_sample_table --time-column modifieddate
```

上記のコマンドは、*database(td_sample_db)* と *table(td_sample_table)* がすでに作成されていることを前提としています。データベースまたはテーブルが TD に存在しない場合、このコマンドは成功しません。したがって、[データベースとテーブルを手動で作成](https://docs.treasuredata.com/smart/project-product-documentation/data-management)するか、`td connector:issue` コマンドで `--auto-create-table` オプションを使用して、データベースとテーブルを自動作成します:


```
$ td connector:issue load.yml --database td_sample_db --table td_sample_table --time-column modifieddate --auto-create-table
```

"--time-column" オプションを使用して、Time Format カラムを "Partitioning Key" に割り当てることができます。

## スケジュール実行

定期的な Salesforce Marketing Cloud インポートのために、データコネクタの定期実行をスケジュールできます。高可用性を確保するために、スケジューラーを注意深く設定しています。この機能を使用することで、ローカルデータセンターに `cron` デーモンを用意する必要がなくなります。

## スケジュールの作成

新しいスケジュールは、`td connector:create` コマンドを使用して作成できます。スケジュールの名前、cron スタイルのスケジュール、データが保存されるデータベースとテーブル、Data Connector 設定ファイルが必要です。


```
$ td connector:create \
    daily_salesforce_marketing_cloud_import \
    "10 0 * * *" \
    td_sample_db \
    td_sample_table \
    load.yml
```

`cron` パラメータは、次の3つのオプションも受け入れます: `@hourly`、`@daily`、`@monthly`。| デフォルトでは、スケジュールは UTC タイムゾーンで設定されます。-t または --timezone オプションを使用して、タイムゾーンでスケジュールを設定できます。`--timezone` オプションは、'Asia/Tokyo'、'America/Los_Angeles' などの拡張タイムゾーン形式のみをサポートします。PST、CST などのタイムゾーン略語は*サポートされておらず*、予期しないスケジュールにつながる可能性があります。

## 増分ロード

### Data Extensions の場合

Treasure Data は、日付フィールドを持つ **Data Extensions** の増分ロードをサポートしています。

`incremental: true` が設定されている場合、データコネクタは、指定された日付フィールドの `from_date` と `fetch_days` で指定された範囲に従ってレコードをロードします。

例:


```
  incremental_column_name: mydatefield
  from_date: "2016-09-01T00:00:00.000Z"
  fetch_days: 2
```

- 1回目のイテレーション: データコネクタは **2016年9月1日 00:00:00 UTC** から **2016年9月3日 00:00:00 UTC** までのレコードを取得します
- 2回目のイテレーション: データコネクタは次に利用可能な2日間の期間のレコードを取得します。**2016年9月3日 00:00:00 UTC** から **2016年9月5日 00:00:00 UTC** まで。このプロセスは、以降の各イテレーションで繰り返されます。
- 増分に現在の日付が含まれる場合、各完全な期間が利用可能になると、追加のレコードが取得されます。


`incremental: false` が設定されている場合、データコネクタは指定されたターゲットのすべてのレコードをロードします。これは1回限りのアクティビティです。

## Email Events の場合

Treasure Data は、イベント日付に基づく **Email Events** の増分ロードをサポートしています。

`incremental: true` が設定されている場合

- 1回目の実行: コネクタは指定された開始時刻（設定されていない場合は全期間）から指定された終了時刻（設定されていない場合はジョブが実行予定の時刻）までのデータを読み込みます
- 2回目の実行: コネクタは前回の終了時刻からジョブが予定されている時刻までのデータを読み込みます


`incremental: false` が設定されている場合、データコネクタは指定されたターゲットのすべてのレコードを読み込みます。これは1回限りの処理です。

## 各ターゲットのサンプル設定

`Campaign` ターゲットの場合


```
in:
 type: salesforce_marketing_cloud
 client_id: XXXXXX
 client_secret: XXXXXX
 target: campaign
out:
 ...
```

| **パラメータ** | **説明** | **デフォルト値** |
|  --- | --- | --- |
| type | salesforce_marketing_cloud である必要があります |  |
| client_id | Salesforce Marketing Cloud の `Client ID` |  |
| client_secret | Salesforce Marketing Cloud の `Client Secret` |  |
| target | campaign である必要があります（この場合） |  |


`Contact` ターゲットの場合


```
in:
 type: salesforce_marketing_cloud
 client_id: XXXXXX
 client_secret: XXXXXX
 target: contact
 contact_page_size: 50
 contact_attributes_request_limit: 100
 contact_multiple_requests: true
 ignore_attribute_set_names:
 - attribute_1
 - attribute_2
out:
 ...
```

| **パラメータ** | **説明** | **デフォルト値** |
|  --- | --- | --- |
| type | salesforce_marketing_cloud である必要があります |  |
| client_id | Salesforce Marketing Cloud の `Client ID` |  |
| client_secret | Salesforce Marketing Cloud の `Client Secret` |  |
| target | contact である必要があります（この場合） |  |
| contact_page_size | ターゲット `contact` のページあたりのレコード数。このオプションは大量のデータがある場合に役立ちます | 1000 |
| contact_attributes_request_limit | 1回のリクエストで各コンタクトに対して取得する属性の数。属性の数がこの値より大きい場合、複数のリクエストに分割されます | 100 |
| contact_multiple_requests | プラグインが非常に多くの属性を持つコンタクト詳細を複数のリクエストで取得できるようにします（これは属性の数が100を超える場合にのみ影響します） | false |
| ignore_attribute_set_names | 無視される属性のリスト。不要な属性を除外したい場合に役立ちます | null |


`Data Extension` ターゲットの場合


```
in:
  type: salesforce_marketing_cloud_v2
  client_id: client_id
  client_secret: client_secret
  auth_type: v2
  auth_uri: auth_uri
  account_id: account_id

  target: data_extension
  data_extension_names:
  - data_extension_1
  - data_extension_2
  incremental: true
  shared_data_extension: true
  incremental_column_name: date
  from_date: "2016-09-01T00:00:00.000Z"
  fetch_days: 1


out:
  type: td
  apikey: td_api_key
  endpoint: td_endpoint
  database: database
  table: table
  time_column: time
  mode: replace
  default_timestamp_format: '%d/%m/%Y'
```

| **パラメータ** | **説明** | **デフォルト値** |
|  --- | --- | --- |
| type | salesforce_marketing_cloud である必要があります |  |
| client_id | Salesforce Marketing Cloud の `Client ID` |  |
| client_secret | Salesforce Marketing Cloud の `Client Secret` |  |
| target | data_extension である必要があります（この場合） |  |
| data_extension_names | 取り込みたいデータエクステンション名のリスト。すべてを取り込む場合は null のままにします | null |
| shared_data_extension | 共有データエクステンションからデータを取り込む場合は、このフラグを true に設定します | false |
| incremental | スケジュール間で新しいデータのみを取得したい場合は、このフラグを true に設定します | false |
| incremental_column_name | 増分読み込みに使用される列。incremental = true を設定する場合は必須です | null |
| from_date | この日付からデータを取り込む場合に設定します | null |
| fetch_days | 取り込み期間は from_date から from_date + fetch_days までです | 1 |


`Email Event` ターゲットの場合


```
in:
 type: salesforce_marketing_cloud
 client_id: XXXXXX
 client_secret: XXXXXX
 target: email_event
 search_term: "email name"
 search_mode: "exact"
 email_event_types:
 - value : all
 start_time: "2019-03-26T07:20:00.000Z"
 end_time: "2019-03-26T07:53:00.000Z"
 incremental: true
out:
 ...
```

| **パラメータ** | **説明** | **デフォルト値** |
|  --- | --- | --- |
| type | salesforce_marketing_cloud である必要があります |  |
| client_id | Salesforce Marketing Cloud の `Client ID` |  |
| client_secret | Salesforce Marketing Cloud の `Client Secret` |  |
| target | email_event である必要があります（この場合） |  |
| search_term | 取り込みたいメールの名前 | null |
| search_mode | 名前のマッチングパターンのモード。**exact** または **partial** のみ指定可能です | exact |
| email_event_types | インポートしたいイベントタイプのリスト。有効なオプションは以下のとおりです：   - value : all - value : bounce - value : click - value : forward - value : forwardOptIn - value : open - value : sent - value : survey - value : unsub | null |
| start_time | この時刻からデータを取り込む場合に設定します | null |
| end_time | この時刻までデータを取り込む場合に設定します | null |
| incremental | スケジュール間で新しいデータのみを取得したい場合は、このフラグを true に設定します | false |