# Batch インポート インテグレーション

この TD インポートを使用すると、Batch Platform アカウントから Treasure AI へデータを転送できます。

## 前提条件

- [TD Toolbelt](/tools/cli-and-sdks/quickstart) を含む Treasure AI の基本的な知識
- Batch アカウント
- Batch アカウントの REST API キーとプロジェクトキー


## 要件と制限

- CLI からのインポートには [Ruby Gem for TD Toolbelt](https://toolbelt.treasuredata.com/) が必要です。
- Batch API は、セグメントフィルタ付き属性エクスポートを 1 時間あたり 5 リクエストに制限しています。セグメントフィルタ付きで ATTRIBUTES をインポートする場合、コネクターはリクエスト間に自動的に 12 分待機します。
- EVENTS および REACHABILITY ソースの日付範囲は、過去 90 日以内であり、未来の日付を指定することはできません。


## API 認証情報の取得

Batch.com からインポートするには、**REST API キー**と**プロジェクトキー**が必要です。

1. Batch.com ダッシュボードにログインします。
2. **Settings** > **API Keys** に移動します。
![](/assets/batch_setting.8d79b0b8f36efd25060e246947ed28fd055a52ae13a0d8fe7f725ed176846e1d.5fc22a4e.webp)
3. **REST API キー**と**プロジェクトキー**をコピーし、安全な場所に保管します。


## TD コンソールから Batch をインポートする

### 認証の作成

最初のステップは、認証情報を使用して新しい認証を作成することです。

1. **TD コンソール**を開きます。
2. **Integrations Hub** > **Catalog** に移動します。
3. **Batch** を検索して選択します。


![](/assets/batch.1018b3f9a89df8f7b611e9dbe0d439788a2dce3a7dce9d1bb7de2897a5f64ed7.5fc22a4e.webp)

1. **Create Authentication** を選択します。
2. **REST API キー**と**プロジェクトキー**を入力します。**Continue** を選択します。


![](/assets/new_authen.3f2e2f1b1ce3365f7ff97c01b21a0fff10f54a40eaeef7943c5165d8a3f522f4.5fc22a4e.webp)

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


### Treasure AI へのデータ転送

認証済み接続を作成すると、自動的に Authentications ページに遷移します。

1. 作成した接続を検索します。
2. **New Source** を選択します。
3. Data Transfer フィールドに**ソース**名を入力します。
4. **Next** を選択します。
Source Table ダイアログが開きます。
5. 以下のパラメーターを編集します。


![ATTRIBUTES configuration](/assets/attributes.870d28b36a9ee9d1f6d218e5f5d334d855253338ea85c684639802e1b84a7e63.5fc22a4e.webp)

![EVENTS configuration](/assets/events.98b11c435e538c7b89a5523f8d9b6aef8b91e7e1ea32c36ab40e4b53d6e25b76.5fc22a4e.webp)

![REACHABILITY configuration](/assets/reachability.8a1baa70365e3a11552955ebb62d1e4e7e53fad1d87c6ed5c383f1075ebf0b07.5fc22a4e.webp)

以下の表は、ソーステーブルを設定するためのパラメーターを説明します。

| パラメーター | 必須 | 説明 |
|  --- | --- | --- |
| Profile Source | はい | 取り込むデータを指定します。サポートされる値:- ATTRIBUTES
- EVENTS
- REACHABILITY

 |
| Identifiers | いいえ | 含める識別子列を指定します。Attributes の場合: `custom_id`、`installation_ids`。Events/Reachability の場合: `custom_id`、`installation_id`。指定しない場合は、有効なすべての識別子がデフォルトで使用されます。 |
| Native Attributes | いいえ | Attributes ソースにのみ適用されます。含める Batch ネイティブ属性のカンマ区切りリスト (例: `$email_address,$city`)。指定しない場合は、すべてのネイティブ属性がデフォルトで使用されます。ネイティブ属性の一覧: [`$city`, `$creation_date`, `$email_address`, `$email_marketing`, `$language`,`$last_activity`, `$last_email_marketing_click`, `$last_email_marketing_open`,`$last_email_transactional_click`, `$last_email_transactional_open`, `$last_visit_date`,`$phone_number`, `$region`, `$sms_marketing`, `$timezone`, `$push_subscriptions`,`$install_date`, `$email_open_tracking_consent`, `$topic_preferences`] |
| Custom Attributes | いいえ | Attributes ソースにのみ適用されます。含めるカスタム属性名のカンマ区切りリスト。属性名は小文字の英数字とアンダースコアのみで、各 30 文字以内にする必要があります。 |
| Segment | いいえ | Attributes ソースにのみ適用されます。エクスポートするプロファイルを特定のセグメントに絞り込むためのセグメントコードを指定します。 |
| Events | いいえ | Events ソースにのみ適用されます。含めるイベントタイプのカンマ区切りリスト (例: `email_sent,email_open`)。指定しない場合は、すべてのイベントタイプがデフォルトで使用されます。イベントの一覧: [`email_bounced`, `email_delivered`, `email_click`, `email_open`, `email_sent`,`email_spam_complaint`, `email_unsubscribed`, `sms_sent`, `sms_bounced`, `sms_delivered`, `sms_unsubscribed`, `push_sent`, `push_bounced`, `push_open`] |
| Orchestration IDs | いいえ | Events ソースにのみ適用されます。イベントを絞り込むオーケストレーション ID のカンマ区切りリスト。 |
| Channels | いいえ | Reachability ソースにのみ適用されます。含めるチャネルのカンマ区切りリスト: `email`、`push`、`sms`。指定しない場合は、すべてのチャネルがデフォルトで使用されます。 |
| Start Date | Profile Source が Events または Reachability の場合は必須 | データインポートの開始日を ISO 8601 形式で指定します (例: `2024-01-01T00:00:00Z`)。過去 90 日以内であり、未来の日付を指定することはできません。 |
| End Date | いいえ | データインポートの終了日を ISO 8601 形式で指定します。指定しない場合は現在時刻がデフォルトで使用されます。Start Date より後であり、未来の日付を指定することはできません。 |
| Incremental Loading | いいえ | Events および Reachability ソースにのみ適用されます。有効にすると、最後に成功したインポート以降の新しいデータのみをインポートします。 |


1. **Next** を選択して Data Settings を定義します。
2. **Next** を選択してデータをプレビューします。


- データをプレビューするには、**Generate Preview** を選択します。次のセクションにスキップする場合は、オプションで **Next** を選択します。


1. データの配置を定義します。


Storage セクションで、TD 内のデータの保存先の詳細を指定します。

- Database — データを保存するデータベースを選択します。
- Table — インポートしたデータを保存する宛先テーブル。
- Method
  - Append — 既存のテーブルにレコードを追加します。(データが重複する場合があります。)
  - Always Replace — レコードを追加する前に、常に宛先テーブルをクリアします。
  - Replace on new data — 新しいデータが見つかった場合、古いデータが新しいデータで上書きされます。
- Timestamp-based Partition Key — パーティションキーとして使用するカスタムタイムスタンプ列を選択します。
- Data Storage Timezone — データベースに設定するタイムゾーン。


**Schedule** セクションでは、クエリを実行する日時と頻度を選択できます。

- Repeat — **On** または **Off** を選択します。
- Schedule — ドロップダウンリストには次のオプションがあります: *@daily (midnight)*、*@hourly (:00)*、または *Custom cron*。
- Delay Transfer — 実行時間に遅延を指定できます。
- Scheduling Timezone — スケジューリングのタイムゾーンを選択します。


1. **Create & Run Now** を選択します。


転送が完了すると、**Data Workbench** > **Databases** で転送結果を確認できます。

## TD ワークフローから Batch をインポートする

ワークフローを作成して実行します。

```yaml
_export:
  td:
    database: workflow_batch
    table: batch_profiles
+import_from_batch:
  td_load>: imports/seed.yml
  database: ${td.database}
  table: ${td.table}
```

インポートの接続詳細を記載した *seed.yml* ファイルを編集します。

### 例: 属性データのインポート

```yaml
in:
  type: batch
  rest_api_key: "{your_rest_api_key}"
  project_key: "{your_project_key}"
  profile_source: ATTRIBUTES
  identifiers: "custom_id"
  native_attributes: "$email_address,$city,$language"
  custom_attributes: "loyalty_tier,signup_source"
  segment: "premium_users"
out:
  mode: append
```

### 例: 増分ローディングを使用したイベントのインポート

```yaml
in:
  type: batch
  rest_api_key: "{your_rest_api_key}"
  project_key: "{your_project_key}"
  profile_source: EVENTS
  events: "email_sent,email_open,email_click"
  orchestration_ids: "orch_068jtte5476ffqc6pe64qxgyj3kkadk7"
  start_date: "2024-01-01T00:00:00Z"
  end_date: "2024-12-31T00:00:00Z"
  incremental: true
out:
  mode: append
```

### 例: リーチャビリティデータのインポート

```yaml
in:
  type: batch
  rest_api_key: "{your_rest_api_key}"
  project_key: "{your_project_key}"
  profile_source: REACHABILITY
  channels: "email,sms"
  start_date: "2024-01-01T00:00:00Z"
  end_date: "2024-12-31T00:00:00Z"
  incremental: true
out:
  mode: append
```

| パラメーター | データ型 | 必須 | 説明 |
|  --- | --- | --- | --- |
| rest_api_key | string | はい | Batch の REST API キー。 |
| project_key | string | はい | Batch のプロジェクトキー。 |
| profile_source | string | はい | 取り込むデータを指定します。サポートされる値:- `ATTRIBUTES`
- `EVENTS`
- `REACHABILITY`

 |
| identifiers | string | いいえ | 含める識別子列のカンマ区切りリスト。ATTRIBUTES の場合: `custom_id`、`installation_ids`。EVENTS/REACHABILITY の場合: `custom_id`、`installation_id`。指定しない場合は、有効なすべての識別子がデフォルトで使用されます。 |
| native_attributes | string | いいえ | `ATTRIBUTES` ソースにのみ適用されます。Batch ネイティブ属性名のカンマ区切りリスト (例: `$email_address,$city`)。指定しない場合は、すべてのネイティブ属性がデフォルトで使用されます。ネイティブ属性の一覧: [`$city`, `$creation_date`, `$email_address`, `$email_marketing`, `$language`,`$last_activity`, `$last_email_marketing_click`, `$last_email_marketing_open`,`$last_email_transactional_click`, `$last_email_transactional_open`, `$last_visit_date`,`$phone_number`, `$region`, `$sms_marketing`, `$timezone`, `$push_subscriptions`,`$install_date`, `$email_open_tracking_consent`, `$topic_preferences`] |
| custom_attributes | string | いいえ | `ATTRIBUTES` ソースにのみ適用されます。カスタム属性名のカンマ区切りリスト。名前は `[a-z0-9_]` に一致し、30 文字以内である必要があります。 |
| segment | string | いいえ | `ATTRIBUTES` ソースにのみ適用されます。エクスポートするプロファイルを絞り込むセグメントコード。 |
| events | string | いいえ | `EVENTS` ソースにのみ適用されます。含めるイベントタイプのカンマ区切りリスト。指定しない場合は、サポートされているすべてのイベントタイプがデフォルトで使用されます。イベントの一覧: [`email_bounced`, `email_delivered`, `email_click`, `email_open`, `email_sent`,`email_spam_complaint`, `email_unsubscribed`, `sms_sent`, `sms_bounced`, `sms_delivered`, `sms_unsubscribed`, `push_sent`, `push_bounced`, `push_open`] |
| orchestration_ids | string | いいえ | `EVENTS` ソースにのみ適用されます。イベントを絞り込むオーケストレーション ID のカンマ区切りリスト。 |
| channels | string | いいえ | `REACHABILITY` ソースにのみ適用されます。カンマ区切りのチャネル: `email`、`push`、`sms`。指定しない場合は、すべてのチャネルがデフォルトで使用されます。 |
| start_date | string | profile_source が `EVENTS` または `REACHABILITY` の場合は必須 | ISO 8601 形式の開始日 (例: `2024-01-01T00:00:00Z`)。過去 90 日以内であり、未来の日付を指定することはできません。 |
| end_date | string | いいえ | ISO 8601 形式の終了日。指定しない場合は現在時刻がデフォルトで使用されます。`start_date` より後であり、未来の日付を指定することはできません。 |
| incremental | boolean (true/false)。デフォルトは false | いいえ | `EVENTS` および `REACHABILITY` ソースにのみ適用されます。有効にすると、最後に成功したインポート以降の新しいデータのみをインポートします。 |


## CLI (Toolbelt) から Batch をインポートする

TD Toolbelt を使用して Batch.com からデータをインポートできます。

### 前提条件

Ruby Gem を使用して最新の TD Toolbelt をインストールします。

```
$ gem install td
$ td --version
0.16.10
```

他のインストール方法もあります。詳細については、[Treasure AI Toolbelt](https://toolbelt.treasuredata.com/) を参照してください。

### 設定ファイルの作成

config.yml 設定ファイルを作成します。

```
in:
  type: batch
  rest_api_key: {your_rest_api_key}
  project_key: {your_project_key}
  profile_source: ATTRIBUTES
  identifiers: "custom_id"
  native_attributes: "$email_address,$city,$language"
  custom_attributes: "loyalty_tier"
out:
  ...........
```

### 設定ファイルから取り込まれるデータのプレビュー

設定ファイルで取り込まれるデータをプレビューできます。

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

### スケジュール実行

定期的な Batch インポートのために、データコネクターの定期実行をスケジュールできます。この機能を使用すると、ローカルデータセンターに `cron` デーモンを設置する必要がなくなります。

#### スケジュールの作成

新しいスケジュールは `td connector:create` コマンドを使用して作成できます。以下の情報を指定する必要があります。

- スケジュール名
- cron スタイルのスケジュール
- データの保存先データベースとテーブル
- Data Connector 設定ファイル


```
$ td connector:create \
  daily_batch_import \
  "10 0 * * *" \
  sample_db \
  sample_table \
  config.yml
```

cron パラメーターは、`@hourly`、`@daily`、`@monthly` の 3 つの特殊オプションも受け付けます。詳細については、[スケジュールされたジョブ](https://docs.treasure.ai/products/customer-data-platform/job-management/scheduling-jobs-using-td-console) を参照してください。

デフォルトでは、スケジュールは UTC タイムゾーンで設定されます。`-t` または `--timezone` オプションを使用して、タイムゾーンを指定してスケジュールを設定できます。`--timezone` オプションは 'Asia/Tokyo'、'America/Los_Angeles' などの拡張タイムゾーン形式のみをサポートしています。PST や CST などのタイムゾーン略称はサポートされておらず、予期しないスケジュールになる可能性があります。

#### スケジュールの一覧表示

`td connector:list` を入力すると、現在スケジュールされているエントリの一覧を確認できます。

```
$ td connector:list
  +--------------------+------------+----------+-------+-----------+--------------+
  | Name               | Cron       | Timezone | Delay | Database  | Table        |
  +--------------------+------------+----------+-------+-----------+--------------+
  | daily_batch_import | 10 0 * * * | UTC      | 0     | sample_db | sample_table |
  +--------------------+------------+----------+-------+-----------+--------------+
```

#### スケジュールの設定と履歴の表示

`td connector:show` はスケジュールエントリの実行設定を表示します。

```
$ td connector:show daily_batch_import
  Name     : daily_batch_import
  Cron     : 10 0 * * *
  Timezone : UTC
  Delay    : 0
  Database : sample_db
  Table    : sample_table
```

`td connector:history` はスケジュールエントリの実行履歴を表示します。各実行の結果を詳しく調べるには、`td job:show jobid` を使用します。

```
  | 577914 | success | 20000   | sample_db | sample_table | 0        | 2025-04-16 00:10:03 +0000 | 152      |
  | 577872 | success | 20000   | sample_db | sample_table | 0        | 2025-04-15 00:10:04 +0000 | 163      |
  | 577810 | success | 20000   | sample_db | sample_table | 0        | 2025-04-14 00:10:04 +0000 | 164      |
  | 577766 | success | 20000   | sample_db | sample_table | 0        | 2025-04-13 00:10:04 +0000 | 155      |
  | 577710 | success | 20000   | sample_db | sample_table | 0        | 2025-04-12 00:10:05 +0000 | 156      |
  | 577610 | success | 20000   | sample_db | sample_table | 0        | 2025-04-11 00:10:04 +0000 | 157      |
  +--------+---------+---------+-----------+--------------+----------+---------------------------+----------+
```

#### スケジュールの削除

`td connector:delete` はスケジュールを削除します。

```
$ td connector:delete daily_batch_import
```