# 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 | ## 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 |