最新のTD Toolbeltをインストールできます。
$ td --version
0.15.0HubSpotアカウントのアクセス情報を含む設定ファイル（例：load.yml）を以下の例のように準備します。
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、searchadditional_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：最大リトライ回数。デフォルト：7max_retry_wait_msec：最大リトライ待機時間（ミリ秒）。デフォルト：30000from_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を参照してください。
td connector:previewコマンドを使用して、インポートされるデータをプレビューできます。
td connector:preview load.ymlロードジョブを送信します。データサイズによっては数時間かかる場合があります。ユーザーはデータが保存されるデータベースとテーブルを指定する必要があります。
Treasure Dataのストレージは時間で分割されているため、--time-columnオプションを指定することをお勧めします。このオプションが指定されていない場合、データコネクタは最初のlongまたはtimestamp列を分割時間として選択します。--time-columnで指定される列の型は、long型またはtimestamp型のいずれかである必要があります。
データに時間列がない場合は、add_timeフィルタオプションを使用して追加できます。詳細については、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に存在しない場合、このコマンドは成功しないため、データベースとテーブルを手動で作成するか、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 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」でリストを分割するサイズを決定できます。
定期的な HubSpot インポートのために、データコネクタの定期実行をスケジュールできます。高可用性を確保するため、スケジューラーは慎重に設定されています。この機能を使用することで、ローカルデータセンターに cron デーモンを配置する必要がなくなります。
新しいスケジュールは td connector:create コマンドを使用して作成できます。スケジュールの名前、cron スタイルのスケジュール、データが保存されるデータベースとテーブル、およびデータコネクタの設定ファイルが必要です。
$ td connector:create daily_hubspot_import "10 0 * * *" td_sample_db td_sample_table load.ymlcron パラメータは、@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_tabletd 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 settd connector:delete はスケジュールを削除します。
$ td connector:delete daily_hubspot_importload.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 |