転送先 - HubSpot

概要

HubSpotへデータを転送する設定のDocsです。

設定項目

STEP1 基本設定

項目名	必須	デフォルト値	内容
HubSpot接続情報	Yes	-	あらかじめ登録してあるHubSpotの接続情報から、今回の転送設定に必要な権限を持つものを選択します。認証方式としてOAuth 2.0で作成された接続情報のみ、選択可能です。
オブジェクトタイプ	Yes	-	転送先として指定したいオブジェクト名を選択します。オブジェクトタイプ一覧 `contact` `company` `deal` `product` `ticket` `line_item` `quote` `subscription` `call` `email` `meeting` `note` `postal_mail` `task` カスタムオブジェクト
転送モード	Yes	`UPSERT`	オブジェクトに対し、データ転送するときの方式を選択します。 `UPSERT`：オブジェクトに対し、データを`UPSERT`します。追記 (`INSERT`)：オブジェクトに対し、データを追記します。
UPSERT キー	Yes	`hs_object_id`	転送モードで`UPSERT`を選択したときに入力します。マージキー（主キー）扱いとする、値の重複のないプロパティーの名前を入力してください。なお、デフォルト値の`hs_object_id`は、HubSpot側で設定されたユニークな値を持つプロパティーです。 `hs_object_id`以外のプロパティーを指定したい場合は、HubSpot側で事前準備が必要となります。詳しくは、後述の任意のプロパティーをUPSERTキーに設定する場合を参照ください。
オブジェクトへの関連付け	Yes	-	オブジェクトタイプでエンゲージメントオブジェクトを選択した場合に設定します。詳しくは、オブジェクトへの関連付けを参照ください。

subscriptionオブジェクト

オブジェクトタイプにsubscriptionを選択した場合、UPSERTで転送が行われます。
また、UPSERT キーはemailおよびsubscription_idが自動で指定されます。
詳しくは、後述のsubscriptionオブジェクトを更新する場合を参照ください。

カスタムオブジェクト

HubSpot上で作成したカスタムオブジェクトにデータを転送できます。
カスタムオブジェクトを読み込むをクリックすると、選択した接続情報に紐づくカスタムオブジェクトが選択できるようになります。

STEP1 詳細設定

詳細設定をクリックすると、設定項目が表示されます。

項目名	必須	デフォルト値	内容
転送の並列数	Yes	1	HubSpot API呼び出しの並列実行数を入力します。 1以上10以下の整数を入力できます。

転送の並列数に関する制約

オブジェクトタイプがsubscription以外の場合に適用されます。
ワークフローで複数ジョブを並列実行する際は、HubSpot APIのレート制限に注意してください。
- HubSpot APIには一定時間内の呼び出し回数にレート制限が設けられています。並列実行数を増やすと、一定時間にAPIを呼び出す回数が増加するため、処理時間を短縮できるかわりにレート制限にも到達しやすくなります。
- レート制限に到達した場合、一定の待ち時間を経てリトライを実行するため、処理時間が長くなる可能性があります。また、リトライ回数の上限に到達するとエラーとなります。
- 使用する転送モードによってAPI呼び出し回数が異なります。INSERTモードは1回の呼び出しで完了しますが、UPSERTモードでは最大3回の呼び出しが必要となるため、レート制限に達しやすくなります。

オブジェクトへの関連付け

HubSpotでは、あるオブジェクトのレコードを他のオブジェクトのレコードに関連付けることができます。
TROCCOでは、エンゲージメントオブジェクトを転送する際に、既存のHubSpotオブジェクトに対する関連付けを合わせて行います。

エンゲージメントオブジェクトの一覧

エンゲージメントオブジェクトの一覧と、それぞれが関連付けられるオブジェクトの一覧は以下のとおりです。

エンゲージメントオブジェクト	関連付けられるオブジェクト一覧
`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`

オブジェクトへの関連付けの設定項目

オブジェクトタイプにてエンゲージメントオブジェクトを選択すると、オブジェクトへの関連付けが表示されます。

対象オブジェクト
- 関連付けを行う対象のオブジェクトを選択します。
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キーに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`	配信登録ステータス `true`: 配信登録する `false`: 配信解除する

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です。