# Hubspot Import Integration CLI

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

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


```
$ td --version
0.15.0
```

## 設定ファイルの作成

HubSpotアカウントのアクセス情報を含む設定ファイル（例：`load.yml`）を以下の例のように準備します。


```yaml
in:
  type: hubspot
  client_id: xxxxxxxxxxxxx
  client_secret: xxxxxxxxxxxxx
  refresh_token: xxxxxxxxxxxxx
  target: contacts
  additional_properties: prop_1, prop_2, prop_3
  retry_intial_wait_msec: 500
  retry_limit: 3
  max_retry_wait_msec: 30000
  from_date: 2016-09-01
  fetch_days: 2
  incremental: true
  connect_timeout_millis: 60000
  idle_timeout_millis: 60000
out:
  mode: replace
```

この例はHubSpotの`Contact`オブジェクトをダンプします：

- `client_id` および `client_secret`：HubSpotアプリの認証情報（文字列、必須）
- `refresh_token`：HubSpot OAuth2のrefresh_token。HubSpotユーザーアカウントを使用してHubSpotアプリへのアクセスを許可する必要があります（文字列、必須）
- `target`：インポートするHubSpotオブジェクト。サポートされる値：`contacts`、`engagements`、`companies`、`contact_lists`、`email_events`、deals、properties、search
- `additional_properties`：カンマ区切りの追加カスタムプロパティのリスト。このフィールドはほとんどの場合必要ありません。この設定は`contacts`、companies、`deals`のターゲットでのみ有効です。指定したリストはHubSpot APIからのカスタムプロパティのリストとマージされます（文字列、オプション）
- `custom_properties_chunk_size`：カスタムプロパティのリストが大きすぎる場合（> 200）、コネクタは複数のリクエストに分割します。このパラメータを使用して、各リクエストのカスタムプロパティリストのパーティションサイズを定義します（整数、オプション、デフォルト：`200`）
- object_names：カンマ区切りのHubSpotオブジェクトのリスト。これはpropertiesターゲットにのみ必要です。
- object_name：HubSpotオブジェクト。これはsearchターゲットにのみ必要です。
- fetch_all_properties：searchターゲットのすべてのプロパティを取得するフラグ。これはsearchターゲットにのみ必要です。
- incremental_column：dateまたはdatetime型のみをサポートします。これはsearchターゲットに必要です。
- start_time：検索オブジェクトの開始時刻。
- end_time：検索オブジェクトの終了時刻。
- retry_intial_wait_msec：初回のリトライ待機時間（ミリ秒）。デフォルト：1000。
- `retry_limit`：最大リトライ回数。デフォルト：7
- `max_retry_wait_msec`：最大リトライ待機時間（ミリ秒）。デフォルト：`30000`
- `from_date`：この日付からデータをインポートします。フォーマット：YYYY-MM-DD。これはcontacts、companies、deals、email_eventsに必要です。
- `fetch_days`：データをインポートする日数。デフォルト：1。これはcontacts、companies、deals、email_eventsに必要です。
- `incremental`：データインポートが継続的か1回限りかを決定します。デフォルト：`false（非増分）`
- connect_timeout_millis：接続が宛先に接続するまでの最大時間（ミリ秒）。デフォルト：60000。
- `idle_timeout_millis`：接続がアイドル状態（つまり、どちらの方向にもデータトラフィックがない状態）になる最大時間（ミリ秒）。デフォルト：60000。


利用可能な`out`モードの詳細については、[Modes for Out Plugin](#modes-for-out-plugin)を参照してください。

## （オプション）：インポートするデータのプレビュー

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


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

## ロードジョブの実行

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

Treasure Dataのストレージは時間で分割されているため、`--time-column`オプションを指定することをお勧めします。このオプションが指定されていない場合、データコネクタは最初の`long`または`timestamp`列を分割時間として選択します。--time-`column`で指定される列の型は、`long`型または`timestamp`型のいずれかである必要があります。

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


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

上記のコマンドは、*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 updated_date --auto-create-table
```

--time-columnオプションを使用して、時刻フォーマット列を「パーティショニングキー」に割り当てることができます。

## 増分ロード

HubSpot APIは、**Contacts**、**Companies**、**Email Events**、**Deals**、および**Search**の増分ロードをサポートしています。

**Companies**、**Contacts**、および**Deals**は、**過去30日間**に変更されたレコード、または最近変更された10,000件のレコードのみを返します。

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

例：


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

- 1回目の反復：データコネクタは**Sep 01 00:00:00 UTC 2016**から**Sep 03 00:00:00 UTC 2016**までのレコードを取得します
- 2回目の反復：データコネクタは**Sep 03 00:00:00 UTC 2016**から開始し、**Sep 03 00:00:00 UTC 2016**から**Sep 05 00:00:00 UTC 2016**までのレコードを取得します。指定されたターゲットに対して次の増分も同様に続きます。


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

**API v3 Search**ターゲットの場合、異なる増分設定を使用します。


```
linenumbers trueincremental_column: createdatestart_time: 2016-09-01T00:00:00.000Zend_time: 2017-09-01T00:00:00.000Z
```

## ページネーション

ほとんどのHubSpot APIエンドポイントは1ページあたり250レコードを返します。ただし、`deals`は増分エンドポイントで1ページあたり100レコード、非増分エンドポイントで1ページあたり250レコードを返します。

Email Eventsの場合、HubSpot APIは各キャンペーンIDとアプリIDに属するイベントをサポートします。イベントは、キャンペーンとアプリのすべての組み合わせに対してページごとに取得されます。

## ターゲット名

HubSpot API がサポートするオブジェクトには、**Contacts**、**Contact Lists**、**Companies**、**Engagements**、**Email Events**、**API v3 Properties**、**API v3 Search** があります。これらは以下の形式でターゲット名として指定する必要があります。

| **HubSpot オブジェクト** | **ターゲット名** |
|  --- | --- |
| Contacts | contacts |
| Contact Lists | contact_lists |
| Companies | companies |
| Engagements | engagements |
| Email Events | email_events |
| Deals | deals |
| API v3 Properties | properties |
| API v3 Search | search |


Contact Lists v1 サンセット — 対応が必要です
HubSpotはContact Lists v1 APIを2026-04-30にサンセットしました。`contact_lists`ターゲットは現在`POST /crm/v3/lists/search`を呼び出し、v1とは異なるv3スキーマを返します：

- **削除されたカラム**：`metaData`、`archived`、`internalListId`、`dynamic`、`filters`、`portalId`、`deleteable`、`listType`
- **型の変更**：`listId`、`createdAt`、`updatedAt`は`STRING`になりました（v3は文字列IDとISO-8601タイムスタンプを返します。以前は`LONG`）
- **新しいカラム**：`listVersion`、`processingType`、`processingStatus`、`objectTypeId`、`filtersUpdatedAt`、`createdById`、`updatedById`、`additionalProperties`


v1のカラム名や数値型の`listId`/`createdAt`/`updatedAt`に依存している下流のテーブルおよびクエリは更新が必要です。

参考：[Contact Lists v1 サンセット](https://developers.hubspot.com/changelog/extension-contact-lists-api-v1-sunset-moved-to-april-30-2026) · [v1 → v3 移行ガイド](https://developers.hubspot.com/docs/api-reference/legacy/crm/lists/v1-migration-guide)

API v1ターゲットからAPI v3 Searchへの移行
以下のAPI v1ターゲットは引き続き動作しますが、HubSpotによるv1のサンセットが順次進められています。将来の動作停止を避けるため、`search`ターゲット（API v3）への切り替えを推奨します：

| **変更前** | **変更後** |
|  --- | --- |
| `target: contacts` | `target: search`、`object_name: contacts`、`incremental_column: lastmodifieddate` |
| `target: companies` | `target: search`、`object_name: companies`、`incremental_column: hs_lastmodifieddate` |
| `target: deals` | `target: search`、`object_name: deals`、`incremental_column: hs_lastmodifieddate` |
| `target: engagements` | エンゲージメントタイプごとに別ジョブに分割 — `target: search`、`object_name: calls`（または `emails`、`meetings`、`notes`、`tasks`） |


**注意：** v3スキーマはv1とは異なります。出力先テーブルのカラム名と型が変わります。

## Custom Properties

データコネクタは Custom Property をサポートしています。データコネクタは、サポートされているターゲット（`contacts`、`companies`、`deals`）のすべての Custom Properties のデータを自動的に取得します。この機能はデフォルトで有効になっているため、新しい Custom Property を作成する際に特別な操作は必要ありません。

ほとんどの場合、すべての Custom Properties が HubSpot API から自動的に取得されるため、「Additional Custom Properties」フィールドを指定する必要はありません。インポートされたデータに一部の Custom Properties が欠落していると思われる場合は、`prop_1, prop_2, prop_3,...` の形式（カンマ区切り）で「Additional Custom Properties」を指定できます。

入力したリストは HubSpot API からの Custom Properties のリストとマージされます。最終的な Custom Properties のリストが十分に大きい場合（> 200）、HubSpot API が `GET` メソッドを使用するため、データコネクタは URL の長さ制限を回避するために各リクエストを複数に分割します。

「New Transfer」を作成する際、「Advanced Settings」でリストを分割するサイズを決定できます。

![](/assets/image-20191021-164124.1bcdf50665706a70827ab3a15c1fc448728726fc0f8b66cccf0c6b08cd278237.d9a10a69.png)

## スケジュール実行

定期的な HubSpot インポートのために、データコネクタの定期実行をスケジュールできます。高可用性を確保するため、スケジューラーは慎重に設定されています。この機能を使用することで、ローカルデータセンターに `cron` デーモンを配置する必要がなくなります。

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

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


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

`cron` パラメータは、`@hourly`、`@daily`、`@monthly` の3つのオプションも受け付けます。

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

### スケジュールのリスト表示

`td connector:list` と入力すると、スケジュールされたエントリのリストを表示できます。


```
$ td connector:list
+-----------------------+--------------+----------+-------+--------------+-----------------+----------------------------+
| Name                  | Cron         | Timezone | Delay | Database     | Table           | Config                     |
+-----------------------+--------------+----------+-------+--------------+-----------------+----------------------------+
| daily_hubspot_import  | 10 0 * * *   | UTC      | 0     | td_sample_db | td_sample_table | {"type"=>"hubspot", ... }  |
+-----------------------+--------------+----------+-------+--------------+-----------------+----------------------------+
```

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

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


```
% td connector:show daily_hubspot_import
Name     : daily_hubspot_import
Cron     : 10 0 * * *
Timezone : UTC
Delay    : 0
Database : td_sample_db
Table    : td_sample_table
```

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


```
% td connector:history daily_hubspot_import
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
| JobID  | Status  | Records | Database     | Table           | Priority | Started                   | Duration |
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
| 578066 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-18 00:10:05 +0000 | 160      |
| 577968 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-17 00:10:07 +0000 | 161      |
| 577914 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-16 00:10:03 +0000 | 152      |
| 577872 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-15 00:10:04 +0000 | 163      |
| 577810 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-14 00:10:04 +0000 | 164      |
| 577766 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-13 00:10:04 +0000 | 155      |
| 577710 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-12 00:10:05 +0000 | 156      |
| 577610 | success | 10000   | td_sample_db | td_sample_table | 0        | 2015-04-11 00:10:04 +0000 | 157      |
+--------+---------+---------+--------------+-----------------+----------+---------------------------+----------+
8 rows in set
```

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

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


```
$ td connector:delete daily_hubspot_import
```

## Out Plugin のモード

load.yml ファイルの out セクションでファイルインポートモードを指定できます。

out: セクションは、Treasure Data テーブルへのデータのインポート方法を制御します。たとえば、Treasure Data の既存のテーブルにデータを追加したり、データを置き換えたりすることができます。

|  | モード | 説明 | 例 |

| --- | --- | --- |
| Append | レコードがターゲットテーブルに追加されます。 | ​in: ...  out:  mode: append |
| Always Replace | ターゲットテーブルのデータを置き換えます。ターゲットテーブルに対して行われた手動のスキーマ変更はそのまま残ります。 | in:  ...  out:  mode: replace |
| Replace on new data | 新しいデータがインポートされる場合にのみ、ターゲットテーブルのデータを置き換えます。 | in: ...  out:  mode: replace_on_new_data |