概要
HubSpotへデータを転送する設定のDocsです。
設定項目
STEP1 基本設定
| 項目名 | 必須 | デフォルト値 | 内容 |
|---|---|---|---|
| HubSpot接続情報 | Yes | - | あらかじめ登録してあるHubSpotの接続情報から、今回の転送設定に必要な権限を持つものを選択します。 認証方式としてOAuth 2.0で作成された接続情報のみ、選択可能です。 |
| オブジェクトタイプ | Yes | - | 転送先として指定したいオブジェクト名を選択します。
|
| 転送モード | Yes | UPSERT |
オブジェクトに対し、データ転送するときの方式を選択します。
|
| UPSERT キー | Yes | hs_object_id |
転送モードでUPSERTを選択したときに入力します。マージキー(主キー)扱いとする、値の重複のないプロパティーの名前を入力してください。 なお、デフォルト値の hs_object_idは、HubSpot側で設定されたユニークな値を持つプロパティーです。hs_object_id以外のプロパティーを指定したい場合は、HubSpot側で事前準備が必要となります。詳しくは、後述の任意のプロパティーをUPSERTキーに設定する場合を参照ください。 |
| オブジェクトへの関連付け | Yes | - | オブジェクトタイプでエンゲージメントオブジェクトまたはordersを選択した場合に設定します。詳しくは、オブジェクトへの関連付けを参照ください。 |
subscriptionオブジェクト
オブジェクトタイプにsubscriptionを選択した場合、UPSERTで転送が行われます。
また、UPSERT キーはemailおよびsubscription_idが自動で指定されます。
詳しくは、後述のsubscriptionオブジェクトを更新する場合を参照ください。
HubSpot上で作成したカスタムオブジェクトにデータを転送できます。
カスタムオブジェクトを読み込むをクリックすると、選択した接続情報に紐づくカスタムオブジェクトが選択できるようになります。
STEP1 詳細設定
詳細設定をクリックすると、設定項目が表示されます。
オブジェクトタイプがsubscriptionの場合、設定は利用できません。
| 項目名 | 必須 | デフォルト値 | 内容 |
|---|---|---|---|
| 転送の並列数 | Yes | 1 | HubSpot API呼び出しの並列実行数を入力します。 1以上10以下の整数を入力できます。 |
| 削除されたカラムをSTEP2のカラム定義から自動削除する | - | 無効 | 転送実行前にHubSpot APIでスキーマを取得し、HubSpot側に存在しないカラムを削除したのち、転送を実行します。以下が削除対象のカラムです。
プログラミングETLを利用している場合、カラムの自動削除は行われません。 削除したカラムは、ジョブの実行ログに出力されます。 |
- ワークフローで複数ジョブを並列実行する際は、HubSpot APIのレート制限に注意してください。
- HubSpot APIには一定時間内の呼び出し回数にレート制限が設けられています。並列実行数を増やすと、一定時間にAPIを呼び出す回数が増加するため、処理時間を短縮できるかわりにレート制限にも到達しやすくなります。
- レート制限に到達した場合、一定の待ち時間を経てリトライを実行するため、処理時間が長くなる可能性があります。また、リトライ回数の上限に到達するとエラーとなります。
- 使用する転送モードによってAPI呼び出し回数が異なります。
INSERTモードは1回の呼び出しで完了しますが、UPSERTモードでは最大3回の呼び出しが必要となるため、レート制限に達しやすくなります。 - オブジェクトへの関連付けを設定している場合は、関連付けの取得・作成・解除のためにAPI呼び出し回数がさらに増えます。
Terraform Provider for TROCCOで管理している転送設定では、「削除されたカラムをSTEP2のカラム定義から自動削除する」を無効にしてください。
本項目によってSTEP2のカラム定義からカラムが削除されると、Terraformの適用(terraform apply)時に元の設定へ戻されるため、削除と復元が繰り返されるおそれがあります。
オブジェクトへの関連付け
HubSpotでは、あるオブジェクトのレコードを他のオブジェクトのレコードに関連付けることができます。
TROCCOでは、エンゲージメントオブジェクトまたはordersを転送する際に、既存のHubSpotオブジェクトに対する関連付けを合わせて行います。
関連付け先のレコードは、先にHubSpotに登録してください。
ワークフローで、関連付け先のオブジェクトを先に転送する順番にすることを推奨します。
TROCCOから関連付けにラベル(Primaryなど)は付与できません。
関連付けられるオブジェクトの一覧
関連付けを設定できるオブジェクトタイプと、それぞれが関連付けられるオブジェクトの一覧は以下のとおりです。
orders以外はエンゲージメントオブジェクトです。
| オブジェクトタイプ | 関連付けられるオブジェクト一覧 |
|---|---|
call |
contact, company, deal, ticket |
email |
contact, company, deal, ticket |
meeting |
contact, company, deal, ticket |
note |
contact, company, deal, ticket |
postal_mail |
contact, company, deal, ticket |
task |
contact, company, deal, ticket, quote |
orders |
contact, company, deal, カスタムオブジェクト |
ordersとカスタムオブジェクトの関連付け
ordersをカスタムオブジェクトに関連付ける場合は、HubSpot側でordersと対象のカスタムオブジェクトの間の関連付けを定義してください。
カスタムオブジェクトを読み込むをクリックすると、対象オブジェクトでカスタムオブジェクトを選択できます。
オブジェクトへの関連付けの設定項目
オブジェクトタイプにてエンゲージメントオブジェクトまたはordersを選択すると、オブジェクトへの関連付けが表示されます。

- 対象オブジェクト
- 関連付けを行う対象のオブジェクトを選択します。
- HubSpot側のユニークキー
- 関連付けを行う対象のオブジェクトから、ユニークな値を持つカラムを入力します。
- 転送データ側のカラム名
- 転送対象のデータに含まれる「関連付け対象のレコードを特定するためのカラム」の名前を入力します。
- カラム内の値がHubSpot側のユニークキーの値と一致するときに、転送したレコードが該当レコードに関連付けられます。
オブジェクトへの関連付けの設定例
以下のデータを転送するとします。
hs_timestamp,hs_call_body,company_id
2023-08-01T00:00:00.000Z,hoge,hoge@example.com,XXXXXXXXXX1
2023-08-02T00:00:00.000Z,fuga,fuga@example.com,XXXXXXXXXX1
2023-08-03T00:00:00.000Z,piyo,piyo@example.com,XXXXXXXXXX2
オブジェクトタイプにcallを選択し、オブジェクトへの関連付けにて以下のように設定します。
- 対象オブジェクト:
company - HubSpot側のユニークキー:
hs_object_id - 転送データ側のカラム名:
company_id
この転送設定を実行すると、転送データはそれぞれ以下のレコードに関連付けられます。
- 転送データの1~2行目:
companyオブジェクトのhs_object_idカラムの値がXXXXXXXXXX1であるレコード - 転送データの3行目:
companyオブジェクトのhs_object_idカラムの値がXXXXXXXXXX2であるレコード
転送モードがUPSERTの場合の関連付け
転送モードがUPSERTの場合、HubSpot上の今の関連付けを、転送データの内容に合わせて更新します。
誰が付けた関連付けかは区別しません。
- 関連付け先のレコードがHubSpotに見つからない場合は、対象のレコードはHubSpotに書き込まれません。
- 関連付けが外れたり、関連付け先が変わったりした場合は、関連付けに付いているラベル(Primaryなど)は削除されます。
- 1つの関連付け設定に対して、HubSpot上で複数のレコードが関連付いている場合は、転送データで指定したレコードだけになります。
以下は、UPSERTキーに注文番号のプロパティーを指定してordersを転送し、カスタムオブジェクト(定期管理)への関連付けを設定している場合の例です。
HubSpot上の関連付け(注文ORD-001の定期管理) |
転送データ | 転送後の関連付け |
|---|---|---|
SUB-A |
ORD-001 / SUB-A |
SUB-A(変更されません) |
SUB-A |
ORD-001 / SUB-B |
SUB-B |
SUB-A |
ORD-001 / 空欄 |
なし |
SUB-A、SUB-C |
ORD-001 / SUB-A |
SUB-A |
SUB-A |
ORD-001 / SUB-X(HubSpotに存在しない) |
エラー(SUB-Aのまま) |
なし(注文ORD-999が存在しない) |
ORD-999 / SUB-A |
ORD-999を作成し、SUB-Aと関連付け |
転送モードがINSERTの場合の関連付け
転送モードがINSERTの場合、新しく作成したレコードに、転送データで指定したレコードを関連付けます。
関連付け先のレコードがHubSpotに見つからない場合は、その関連付けだけ行わずに転送を続けます。
補足事項
任意のプロパティーをUPSERTキーに設定する場合
UPSERTキーにhs_object_idまたはcontactオブジェクトのemail以外のプロパティーを設定したい場合は、あらかじめHubSpot側で設定する必要があります。
以下で、設定手順を説明します。
- HubSpotにログインし、ご利用中のHubSpotアカウントをクリック
- 画面右上、赤枠内の設定アイコンをクリック

- プロパティーをクリック

- オブジェクトを選択し、UPSERTキーとして使用したいプロパティーをクリック

- ルールタブをクリック

- このプロパティーでは、重複にならない値を必須にするを有効化し、保存をクリック

subscriptionオブジェクトを更新する場合
subscriptionオブジェクトを更新するためには、TROCCO上でカラム名や型をマッピングする必要があります。
以下の表を参照し、TROCCOの転送設定STEP2「カラム定義」タブにて、マッピングを行ってください。
| カラム名 | データ型 | 必須 | 入力例 | 説明 |
|---|---|---|---|---|
email |
string |
✓ | hoge@example.com |
メールアドレス |
subscription_id |
long |
✓ | 12232 |
サブスクリプションID |
is_subscribed |
boolean |
✓ | true |
配信登録ステータス
|
is_subscribedに関する制約
-
is_subscribed(配信登録ステータス)がfalseである(解除されている)データは更新できません。
配信登録ステータスが登録されている状態に更新したい場合は、HubSpot側の画面上から更新してください。 -
HubSpot側のデータに対し、配信登録ステータスを変更しない形でのデータの更新には対応していません。
したがって、HubSpot側でis_subscribed(配信登録ステータス)がtrueである(登録されている)状態のデータに対し、is_subscribedがtrueのデータで更新できません。
サブスクリプションIDの確認方法
- HubSpotの画面上で設定>データ管理>プロパティーを選択します。
- プロパティー画面右上の全てのプロパティーをエクスポートを選択し、モーダルの「エクスポート」をクリックして、エクセル/CSVファイルをダウンロードします。
- エクセル/CSVファイルのCONTACTシートの中に
hs_email_optout_で始まる項目を探します。
例:hs_email_optout_111の場合、サブスクリプションIDは111です。