--- title: "転送先 - HubSpot | TROCCO Docs" slug: "data-destination-hubspot" updated: 2026-11-05T08:58:47Z published: 2026-11-05T08:58:47Z canonical: "documents.trocco.io/data-destination-hubspot" --- > ## Documentation Index > Fetch the complete documentation index at: https://documents.trocco.io/llms.txt > Use this file to discover all available pages before exploring further. # 転送先 - HubSpot ## 概要 HubSpotへデータを転送する設定のDocsです。 ## 設定項目 ### STEP1 基本設定 | 項目名 | 必須 | デフォルト値 | 内容 | | --- | --- | --- | --- | | HubSpot接続情報 | Yes | - | あらかじめ登録してある[HubSpotの接続情報](/docs/connection-configuration-hubspot)から、今回の転送設定に必要な権限を持つものを選択します。 **認証方式としてOAuth 2.0で作成された接続情報のみ、選択可能です。** | | オブジェクトタイプ | Yes | - | 転送先として指定したいオブジェクト名を選択します。 **オブジェクトタイプ一覧** - `contact` - `company` - `deal` - `product` - `ticket` - `line_item` - `orders` - `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キーに設定する場合](/docs/data-destination-hubspot#%E4%BB%BB%E6%84%8F%E3%81%AE%E3%83%97%E3%83%AD%E3%83%91%E3%83%86%E3%82%A3%E3%83%BC%E3%82%92upsert%E3%82%AD%E3%83%BC%E3%81%AB%E8%A8%AD%E5%AE%9A%E3%81%99%E3%82%8B%E5%A0%B4%E5%90%88)を参照ください。 | | オブジェクトへの関連付け | Yes | - | オブジェクトタイプで**エンゲージメント**オブジェクトまたは`orders`を選択した場合に設定します。 詳しくは、[オブジェクトへの関連付け](/docs/data-destination-hubspot#%E3%82%AA%E3%83%96%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%B8%E3%81%AE%E9%96%A2%E9%80%A3%E4%BB%98%E3%81%91)を参照ください。 | `subscription`オブジェクト オブジェクトタイプに`subscription`を選択した場合、`UPSERT`で転送が行われます。 また、UPSERT キーは`email`および`subscription_id`が自動で指定されます。 詳しくは、後述の[subscriptionオブジェクトを更新する場合](/docs/data-destination-hubspot#subscription%E3%82%AA%E3%83%96%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%82%92%E6%9B%B4%E6%96%B0%E3%81%99%E3%82%8B%E5%A0%B4%E5%90%88)を参照ください。 カスタムオブジェクト HubSpot上で作成したカスタムオブジェクトにデータを転送できます。 **カスタムオブジェクトを読み込む**をクリックすると、選択した接続情報に紐づくカスタムオブジェクトが選択できるようになります。 ### STEP1 詳細設定 **詳細設定**をクリックすると、設定項目が表示されます。 オブジェクトタイプが`subscription`の場合、設定は利用できません。 | 項目名 | 必須 | デフォルト値 | 内容 | | --- | --- | --- | --- | | 転送の並列数 | Yes | 1 | HubSpot API呼び出しの並列実行数を入力します。 1以上10以下の整数を入力できます。 | | 削除されたカラムをSTEP2のカラム定義から自動削除する | - | 無効 | 転送実行前にHubSpot APIでスキーマを取得し、HubSpot側に存在しないカラムを削除したのち、転送を実行します。以下が削除対象のカラムです。 - STEP2のカラム定義 - [転送日時カラム設定](/docs/template-etl#%E8%BB%A2%E9%80%81%E6%97%A5%E6%99%82%E3%82%AB%E3%83%A9%E3%83%A0%E8%A8%AD%E5%AE%9A)で追加したカラム [JSONカラムを展開](/docs/template-etl#json%E3%82%AB%E3%83%A9%E3%83%A0%E3%82%92%E5%B1%95%E9%96%8B)で展開したカラムは、展開後のカラム名で判定します。 [プログラミングETL](/docs/programming-etl)を利用している場合、カラムの自動削除は行われません。 削除したカラムは、ジョブの実行ログに出力されます。 | 転送の並列数に関する制約 - ワークフローで複数ジョブを並列実行する際は、HubSpot APIの[レート制限](https://developers.hubspot.jp/docs/guides/apps/api-usage/usage-details#%E3%83%AC%E3%83%BC%E3%83%88%E5%88%B6%E9%99%90)に注意してください。 - HubSpot APIには一定時間内の呼び出し回数にレート制限が設けられています。並列実行数を増やすと、一定時間にAPIを呼び出す回数が増加するため、処理時間を短縮できるかわりにレート制限にも到達しやすくなります。 - レート制限に到達した場合、一定の待ち時間を経てリトライを実行するため、処理時間が長くなる可能性があります。また、リトライ回数の上限に到達するとエラーとなります。 - 使用する転送モードによってAPI呼び出し回数が異なります。`INSERT`モードは1回の呼び出しで完了しますが、`UPSERT`モードでは最大3回の呼び出しが必要となるため、レート制限に達しやすくなります。 - [オブジェクトへの関連付け](/docs/data-destination-hubspot#%E3%82%AA%E3%83%96%E3%82%B8%E3%82%A7%E3%82%AF%E3%83%88%E3%81%B8%E3%81%AE%E9%96%A2%E9%80%A3%E4%BB%98%E3%81%91)を設定している場合は、関連付けの取得・作成・解除のためにAPI呼び出し回数がさらに増えます。 Terraform Provider for TROCCO利用時の注意事項 [Terraform Provider for TROCCO](/docs/terraform-provider-for-trocco)で管理している転送設定では、「削除されたカラムをSTEP2のカラム定義から自動削除する」を無効にしてください。 本項目によってSTEP2のカラム定義からカラムが削除されると、Terraformの適用(`terraform apply`)時に元の設定へ戻されるため、削除と復元が繰り返されるおそれがあります。 ### オブジェクトへの関連付け HubSpotでは、あるオブジェクトのレコードを他のオブジェクトのレコードに[関連付ける](https://knowledge.hubspot.com/ja/crm-setup/associate-records)ことができます。 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`を選択すると、**オブジェクトへの関連付け**が表示されます。 ![001.png](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/data-destination-hubspot-2024-08-29-18-40-0.png) - **対象オブジェクト** - 関連付けを行う対象のオブジェクトを選択します。 - **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側で設定する必要があります。 以下で、設定手順を説明します。 1. [HubSpot](https://app.hubspot.com/login)にログインし、ご利用中のHubSpotアカウントをクリック 2. 画面右上、赤枠内の設定アイコンをクリック ![image](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/data-destination-hubspot-2024-08-29-18-40-1.png) 3. **プロパティー**をクリック ![image](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/data-destination-hubspot-2024-08-29-18-40-2.png) 4. **オブジェクト**を選択し、UPSERTキーとして使用したいプロパティーをクリック ![image](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/data-destination-hubspot-2024-08-29-18-40-3.png) 5. **ルール**タブをクリック ![image](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/data-destination-hubspot-2024-08-29-18-40-4.png) 6. **このプロパティーでは、重複にならない値を必須にする**を有効化し、保存をクリック ![image](https://cdn.document360.io/3a3bae1e-f157-487f-8798-01e9d820e760/Images/Documentation/data-destination-hubspot-2024-08-29-18-40-5.png) ### subscriptionオブジェクトを更新する場合 `subscription`オブジェクトを更新するためには、TROCCO上でカラム名や型をマッピングする必要があります。 以下の表を参照し、TROCCOの転送設定STEP2「カラム定義」タブにて、マッピングを行ってください。 | カラム名 | データ型 | 必須 | 入力例 | 説明 | | --- | --- | --- | --- | --- | | `email` | `string` | ✓ | `hoge@example.com` | メールアドレス | | `subscription_id` | `long` | ✓ | `12232` | [サブスクリプションID](/docs/data-destination-hubspot#%E3%82%B5%E3%83%96%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3id%E3%81%AE%E7%A2%BA%E8%AA%8D%E6%96%B9%E6%B3%95) | | `is_subscribed` | `boolean` | ✓ | `true` | 配信登録ステータス - `true`: 配信登録する - `false`: 配信解除する | `is_subscribed`に関する制約 - `is_subscribed`(配信登録ステータス)が`false`である(解除されている)データは更新できません。 配信登録ステータスが登録されている状態に更新したい場合は、HubSpot側の画面上から更新してください。 - HubSpot側のデータに対し、配信登録ステータスを変更しない形でのデータの更新には対応していません。 したがって、HubSpot側で`is_subscribed`(配信登録ステータス)が`true`である(登録されている)状態のデータに対し、`is_subscribed`が`true`のデータで更新できません。 #### サブスクリプションIDの確認方法 1. HubSpotの画面上で**設定**>**データ管理**>**プロパティー**を選択します。 2. プロパティー画面右上の**全てのプロパティーをエクスポート**を選択し、モーダルの「エクスポート」をクリックして、エクセル/CSVファイルをダウンロードします。 3. エクセル/CSVファイルの**CONTACT**シートの中に `hs_email_optout_`で始まる項目を探します。 例:`hs_email_optout_111` の場合、サブスクリプションIDは`111`です。