# Hubspot インポート連携

[HubSpot エクスポート連携の詳細はこちら](/ja/int/hubspot-export-integration)。

HubSpotは、企業が訪問者を引き付け、リードを変換し、取引を成立させることを支援するインバウンドマーケティングおよび営業プラットフォームです。この連携を使用してHubSpotデータをTDにインポートすることで、データサイロを排除し、すべてのタッチポイントにわたる顧客行動を理解し、顧客とのより関連性の高いタイムリーなインタラクションを作成し、より良いリテンションとロイヤルティを実現します。

この連携では、Contacts、Companies、Contact Lists、Email events、Engagement activities、Deals、その他のデータオブジェクトなど、さまざまなHubSpotオブジェクトがサポートされています。

## 前提条件

- Treasure Dataの基礎知識
- HubSpotの基礎知識


## Treasure Data Integration の静的 IP アドレス

セキュリティポリシーで IP ホワイトリストが必要な場合は、接続を成功させるために Treasure Data の IP アドレスを許可リストに追加する必要があります。

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります:
[IP Addresses for Integrations](/apis/endpoints/ip-addresses-integrations-result-workers)

## Treasure コンソールで新しい認証を作成する

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

1. **Integrations Hub** > **Catalog** に移動します
2. **HubSpot** を検索して選択します


![](/assets/hubspot-import-integration-2024-12-11.5bde931f7b4dbd26258a20ac4ebc17dc0b7f7c929d1e1221e17940894872e103.899d1e34.png)

1. **Create Authentication** を選択し、HubSpotアカウントのOAuthを提供します
2. Integration Hubにリダイレクトされた後、上記の手順を繰り返します（今回は提供したOAuthが表示されます）。認証の名前を入力し、**Done** を選択します


## ソースを作成する

1. Treasure コンソールを開きます
2. **Integrations Hub > Authentications** に移動します
3. 新しい認証を見つけて **New Source** を選択します
4. 最初のステップ `1 - Connection` で、**Data Transfer Name** フィールドにソース名を入力し、**Next** を選択します


### ソースデータを特定する

以下のパラメータを使用してTreasure Dataに取り込むデータを特定し、**Next** を選択します。

![](/assets/hubspot-import-integration-2024-12-11-1.044522dca7f1b31e29c9413a5a17d786f70471375fe13fe4c6e15256f4d25b3e.899d1e34.png)

後方互換性をサポートするため、この連携では以下のデータオブジェクトにAPI V1を使用します：

- Contacts（カスタム属性を含む）
- Companies（カスタム属性を含む）
- Contact Lists
- Email events
- Engagement activities
- Deals（カスタム属性を含む）


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では、Contacts、Companies、Email eventsの増分読み込みが可能です

- **Start date**：HubSpotでデータオブジェクトを取得する開始日
- **Number of days to fetch**：取得する日数。過去最大30日まで取得できます


API V1の既知の制限事項：

- すべてのカスタム属性がサポートされているわけではありません
- データインポートには10,000レコードの上限があります


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とは異なります。出力先テーブルのカラム名と型が変わります。

**API V3**

より新しいAPIバージョンであるAPI V3は、より多くのデータオブジェクトをサポートし、10kレコード制限を回避するために使用されます

| **フィールド** | **説明** |
|  --- | --- |
| Source | - **API v3 Search**：このオプションを選択し、次のフィールドでインポートするデータオブジェクト名を宣言します
- **API v3 Properties**：HubSpotアカウントで利用可能なデータオブジェクトの属性を調べたい場合は、このオプションを使用します

 |
| Object Name
 | インポートするデータオブジェクト名。（サポートされているデータオブジェクトの完全なリストについては、[HubSpot](https://developers.hubspot.com/beta-docs/guides/api/crm/search)を参照してください。）
- Objects: carts、companies、contacts、deals、deal_split、discounts、feedback_submissions、fees、invoices、leads、...
- Engagements: calls、emails、meetings、notes、tasks

`API v3 Properties` の場合、カンマ区切りのオブジェクト名リストを入力できます。
 |
| Incremental Column | （`API v3 Search` の場合 - 必須）増分読み込みおよび/またはフィルタリングに使用される列。 |
| Fetch All Properties | （`API v3 Search` の場合）チェックを外すと、データオブジェクトのデフォルトプロパティのみがインポートされます。 |
| Incremental | （`API v3 Search` の場合）チェックを入れると、前回の実行以降の新しいデータのみがインポートされます。 |
| Start Date Time  End Date Time |  | (`API v3 Search`の場合) 開始時刻から終了時刻までのデータがインポートされます。これらのオプションは初期データロードに便利です。 |


### データ設定の定義

オプションで、高度なデータ設定を変更できます。**Next**を選択して次のステップに進みます。

![](/assets/google-ads-import-integration-v2-2024-08-06-5.9673dac09cfdafcf311c3895320451d2e018d8e5f17d194f5c066d1649402578.7c52a81f.png)

### データのプレビュー

- `4 Data Preview`ステップで、**Generate Preview**を選択して、インポートを実行する前にデータのサンプルを確認します(オプション)。
- **Next**を選択して続行します。


![](/assets/google-ads-import-integration-v2-2024-08-06-3.d1a7264878d399f9a4e744868a69b15ed5ab861a1fd396d9ecef55513fcc8527.7c52a81f.png)

### データ配置の定義

データ配置については、データを配置するターゲットdatabaseとtableを選択し、インポートを実行する頻度を指定してから、**Save**または**Save & Run Now**を選択します。

![](/assets/9bcff190-9edf-477a-9bb2-71ca68a875ef.c34f58af08ad9329b71e53eb2ce3a6e83cac5070a0e24696459c451b133b39e3.69844539.png)

## CLI(Toolbelt)を使用したHubSpotからのインポート

### 前提条件

- TD Toolbelt: 最新バージョンのTreasure CLIツールをインストールしてください: [TD Toolbelt](https://toolbelt.treasuredata.com/)
- Authentication ID: Treasure コンソールでこのインテグレーションのauthenticationを作成するには、上記の手順に従ってください。その後、authentication画面のURLの最後の部分でIDを確認できます。


![](/assets/google-ads-import-integration-v2-2024-08-06-9.fdc162a377e20998a8f41e69c38afef49bbd1ab0b84f6b913fd06fe82b2010f3.7c52a81f.png)

### 一般的な手順

1. YML設定ファイル(例: `**load.yml**`)を作成し、`**td\_authentication\_id**`フィールドで作成したauthenticationを参照します。
詳細については、以下の[Parameter Reference](/ja/int/hubspot-import-integration#h3_755695857)および[Example](/ja/int/hubspot-import-integration#h3_1689083776)を参照してください
2. 次のコマンドを使用して、入力データをプレビューします(オプション):
`$ td connector:preview load.yml`
3. 次のコマンドを使用して、データインポートをトリガーします:
`$ td connector:issue load.yml --database db-name --table table-name`
4. 次のコマンドを使用して、実行をスケジュールします:
`$ td connector:create daily\_import "10 0 \* \* \*" db-name table-name load.yml`


### パラメータリファレンス

次の表は、CLI経由でHubSpotインポートインテグレーションを設定するためのパラメータについて説明しています。

| Name | Description | Value | Default value | Required |
|  --- | --- | --- | --- | --- |
| `td_authentication_id` | UIで取得したauthentication id | `numeric` | N/A | Yes |
| `target` | ソース。`contacts`、`engagements`、`companies`、`deals`、`contact_lists`、`email_events`、`properties`、`search`のいずれか。 | `String` | `contacts` |  |
| `additional_properties` | 追加のCustom Properties。targetが`contacts`、`companies`、または`deals`の場合にのみ適用されます。 | `String` | N/A |  |
| `object_names` | オブジェクトのpropertiesを取得するためのカンマ区切りのオブジェクト名。targetが`properties`の場合にのみ適用されます。 | `String` | N/A | targetが`properties`の場合はYes |
| `object_name` | search API v3を使用する際に取り込むオブジェクト。targetが`search`の場合のみ適用されます | `String` | N/A | targetが`search`の場合は必須 |
| `incremental_column` | search API v3を使用する際に増分読み込みに使用するカラム。targetが`search`の場合のみ適用されます | `String` | N/A |  |
| `fetch_all_properties` | オブジェクトのすべてのプロパティを取得するかどうかを決定します。チェックを入れると実行にレイテンシが追加される可能性がありますが、より多くの情報が提供されます。targetが`search`の場合のみ適用されます | `Boolean` | `false` |  |
| `incremental` | 前回実行時以降の新しいデータのみをインポートするかどうか。targetが`contacts`、`companies`、`deals`、`email_events`、または`search`の場合のみ適用されます | `Boolean` | `false` |  |
| `from_date` | データを取り込む開始日（ISO-8601形式）。incrementalが`true`で、targetが`contacts`、`engagements`、`companies`、`deals`、`contact_lists`、または`email_events`の場合のみ適用されます | `Datetime` | N/A |  |
| `fetch_days` | 開始日から何日分のデータを取得するか。incrementalが`true`で、targetが`contacts`、`engagements`、`companies`、`deals`、`contact_lists`、または`email_events`の場合のみ適用されます | `Number` | `1` |  |
| `start_time` | データを取り込む開始時刻（ISO-8601形式）。targetが`search`の場合のみ適用されます | `Datetime` | N/A |  |
| `end_time` | データを取り込む終了時刻（ISO-8601形式）。targetが`search`の場合のみ適用されます | `Datetime` | N/A |  |


### 例


```yaml
in:
  type: hubspot
  td_authentication_id: 330392
  additional_properties: "prop_1, prop_2, prop_3"
  custom_properties_chunk_size: 100
  retry_intial_wait_msec : "500" # initial waiting time as 0.5 second
  retry_limit : "10"
  max_retry_wait_msec :  "90000" # maximum 1.5 minute of waiting time for each retry
  from_date: 2016-09-01T00:00:00.000Z
  fetch_days: 2
out:
  mode: append
```

## 関連トピック

- このインテグレーションの定期実行については、[TD Toolbeltを使用したスケジューリング](/ja/int/scheduling-a-data-connector-job-execution-from-the-cli)を参照してください
- ワークフローから作成したSourceをトリガーする方法については、[Treasure ワークフローとIntegrationsの使用](/ja/int/using-td-workflow-with-td-integrations)を参照してください