HubSpot: 技術リファレンス#

#目的

これは、主なHubSpotコネクタのドキュメントの技術的な補助資料です。認証の内部構造、完全なエンドポイントリファレンス、スコープ、ページネーション、出力形式、制限など、データパイプラインにコネクタを統合するために必要なすべての内容をカバーしています。

#認証

#サポートされている方法

すべての方法は同じBearerヘッダーを使用します。

Authorization: Bearer {token}

#非推奨の認証方法

#資格情報の形式

{
  "token": "pat-eu1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

#アーキテクチャ

コネクタはHubSpot APIから生のJSONを返します。プラットフォームはそこから引き継ぎます。JSONペイロードから自動的にスキーマを発見し、入れ子になったオブジェクトをドット表記の列（スラグ化して小文字でアンダースコア）にフラット化し、結果をLakehouseに保存します。Trinoを介してクエリ可能です。HubSpotがオブジェクトに追加した新しいフィールドは、次の抽出時に自動的に表示されます。スキーマを定義したり、列をリストしたり、変換コードを書いたりする必要はありません。

コネクタ自体は認証（Bearerトークン）、エンドポイントルーティング、ページネーション（エンドポイントによってカーソルまたはオフセット）、レート制限のリトライを担当します。

#CRMオブジェクトタイプ

#27の標準オブジェクト

コネクタは27の標準的なHubSpot CRMオブジェクトタイプを公開します。各オブジェクトは/crm/v3/objects/{object_type}でアクセス可能です（所有者については後述）。

#コアCRM

#エンゲージメント

#Eコマース＆セールス

#コマース

#コマースハブ

#セールスハブ

#サービス＆スケジューリング

#特殊：所有者

所有者は/crm/v3/objects/ownersの代わりに専用のエンドポイント(GET /crm/v3/owners)を使用します。コネクタはobject_type=ownersが選択されたときにこれを自動的に処理します。

#エンドポイントリファレンス

#crm_objects

CRMオブジェクトタイプからレコードを抽出します。

API: GET /crm/v3/objects/{object_type}?properties={props}&limit=100&after={cursor}

ページネーション: カーソルベース (paging.next.after)

出力: 生JSON。各レコードにはid、createdAt、updatedAt、archived、およびすべての要求されたプロパティ値を含むネストされたpropertiesディクショナリが含まれます。

プロパティの動作:

• フィルタが空の場合: GET /crm/v3/properties/{type}を最初に使用してすべてのプロパティをフェッチし、その後すべてを要求します
• フィルタ付き: 指定されたプロパティのみを要求します
• HubSpotはすべてのプロパティ値を文字列として返します（数値や日付でも）

#associations

CRMオブジェクト間の関係を抽出します。

API: POST /crm/v4/associations/{from_type}/{to_type}/batch/read

ページネーション: ソースオブジェクトに基づくカーソルベース、アソシエーションのルックアップにはバッチPOST（リクエストあたり最大1000のID）

出力: 生JSON。各結果にはfromとtoオブジェクトが含まれ、IDとアソシエーションメタデータが含まれます。

#association_definitions

2つのオブジェクトタイプ間で利用可能なアソシエーションタイプを取得します。

API: GET /crm/v4/associations/{from_type}/{to_type}/labels

ページネーション: なし（単一GET）

出力: 生JSON、カテゴリ、タイプID、およびラベルを含むアソシエーションタイプ定義。

#pipelines

パイプライン定義とそのステージを抽出します。

API: GET /crm/v3/pipelines/{pipeline_object_type}

ページネーション: なし（単一GET、すべてのパイプラインを返す）

出力: 生JSON。各パイプラインにはid、label、displayOrder、createdAt、updatedAt、およびネストされたstages配列が含まれます。プラットフォームはステージを自動的に個別の行にフラット化します。

#pipeline_audit

特定のパイプラインの監査ログです。

API: GET /crm/v3/pipelines/{object_type}/{pipeline_id}/audit

ページネーション: なし（単一GET）

出力: 生JSON、APIから返される監査エントリ。

#properties_meta

オブジェクトタイプのデータ辞書（プロパティスキーマ）を抽出します。

API: GET /crm/v3/properties/{property_object_type}

ページネーション: なし（単一GET）

出力: 生JSON。各プロパティにはname、label、type、fieldType、groupName、descriptionなどが含まれます。

#property_groups

オブジェクトタイプのプロパティグループを抽出します。

API: GET /crm/v3/properties/{property_object_type}/groups

ページネーション: なし（単一GET）

出力: 生JSON、APIから返されるグループ定義。

#lists

リストとセグメント定義を抽出します。

API: GET /crm/v3/lists

ページネーション: カーソルベース

出力: 生JSON、APIから返されるリスト定義。

#list_memberships

特定のリストからメンバーレコードIDを取得します。

API: GET /crm/v3/lists/{list_id}/memberships

ページネーション: カーソルベース

出力: 生JSON、APIから返されるメンバーシップレコード。

#marketing_emails

統計情報を含むマーケティングメール定義を抽出します。

API: GET /marketing/v3/emails

ページネーション: カーソルベース

出力: 生JSON、ネストされた統計情報を含むメールキャンペーンデータ、プラットフォームによってフラット化されます。

#forms

フォーム定義を抽出します。

API: GET /marketing/v3/forms

ページネーション: カーソルベース

出力: 生JSON、APIから返されるフォーム定義。

#form_submissions

特定のフォームの送信を抽出します。

API: GET /form-integrations/v1/submissions/forms/{form_id}

ページネーション: オフセットベース（v1 API、offset + hasMoreを使用、カーソルベースではありません）

出力: 生JSON、APIから返される送信データ。

#conversations

会話スレッド（チャット、メール、ボット）を抽出します。

API: GET /conversations/v3/conversations/threads

ページネーション: カーソルベース

出力: 生JSON、APIから返されるスレッドデータ。

必要: Conversationsスコープ + 適切なHubSpotプラン

#campaigns

マーケティングキャンペーン定義を抽出します。

API: GET /marketing/v3/campaigns

ページネーション: カーソルベース

出力: 生JSON、APIから返されるキャンペーンデータ。

#blog_posts

CMSブログ記事を抽出します。

API: GET /cms/v3/blogs/posts

ページネーション: カーソルベース

出力: 生JSON、ブログ投稿データ（タイトル、内容、著者、公開日など）。

#site_pages

CMSウェブサイトページを抽出します。

API: GET /cms/v3/pages/site-pages

ページネーション: カーソルベース

出力: 生JSON、APIから返されるページデータ。

#landing_pages

CMSランディングページを抽出します。

API: GET /cms/v3/pages/landing-pages

ページネーション: カーソルベース

出力: 生JSON、APIから返されるページデータ。

#workflows

自動化ワークフロー定義を抽出します。

API: GET /automation/v3/workflows

ページネーション: なし（単一GET、データキーはworkflows、resultsではありません）

出力: 生JSON、APIから返されるワークフロー定義。

#sequences

セールスシーケンス定義を抽出します。

API: GET /automation/v4/sequences

ページネーション: カーソルベース

出力: 生JSON、APIから返されるシーケンスデータ。

必要: Sales Hub Pro+

#users

アカウントユーザーを抽出します。

API: GET /settings/v3/users

ページネーション: カーソルベース

出力: 生JSON、APIから返されるユーザーデータ。

#imports

CRMインポート履歴を抽出します。

API: GET /crm/v3/imports

ページネーション: カーソルベース

出力: 生JSON、APIから返されるインポートレコード。

#crm_schemas

カスタムオブジェクトスキーマ定義を抽出します。

API: GET /crm/v3/schemas

ページネーション: なし（単一GET）

出力: 生JSON、APIから返されるスキーマ定義。

#custom_events

特定のCRMレコードの行動イベントを抽出します。

API: GET /events/v3/events?objectType={type}&objectId={id}

ページネーション: カーソルベース（extra_params付き）

出力: 生JSON、APIから返されるイベントデータ。

必要: Marketing Hub Enterprise

#timeline_events

統合アプリのタイムラインイベントテンプレートを抽出します。

API: GET /crm/v3/timeline/{app_id}/event-templates

ページネーション: なし（単一GET）

出力: 生JSON、APIから返されるイベントテンプレートデータ。

#hubdb_tables

HubDBテーブル定義を抽出します。

API: GET /cms/v3/hubdb/tables

ページネーション: カーソルベース

出力: 生JSON、APIから返されるテーブル定義。

#エンドポイントごとのスコープ

#CRM オブジェクト

#その他のエンドポイント

上記に記載されていないエンドポイント（workflows、sequences、users、imports、crm_schemas、conversations、custom_events、hubdb_tables、timeline_events）については、HubSpotのスコープリファレンスを参照してください。

#ページネーション

コネクタはエンドポイントによって3つのページネーション戦略を使用します：

#カーソルベース（ほとんどのエンドポイント）

GET /crm/v3/objects/contacts?limit=100&after=NTI1Cg==

レスポンス：

{
  "results": [...],
  "paging": {
    "next": { "after": "NTI1Cg==" }
  }
}

paging.next.after が存在しない場合、すべてのデータが取得されました。

#オフセットベース（フォーム送信のみ）

GET /form-integrations/v1/submissions/forms/{id}?limit=50&offset=0

レスポンス：

{
  "results": [...],
  "hasMore": true,
  "offset": 50
}

hasMore が false の場合、すべてのデータが取得されました。

#ページネーションなし（単一のGET）

一部のエンドポイントは単一のレスポンスですべてのデータを返します：pipelines, pipeline_audit, properties_meta, property_groups, association_definitions, workflows, timeline_events, crm_schemas。

#レート制限

#プランごとの制限

現在の制限については、HubSpotの公式レート制限ドキュメントを参照してください。制限はプランとAPIエンドポイントによって異なります。

#レート制限の処理

コネクタは自動的に 429 Too Many Requests レスポンスを処理します：

1. Retry-After ヘッダー（待機する秒数）を読み取ります
2. ヘッダーが存在しない場合は10秒にフォールバックします
3. 待機した後、リクエストを再試行します

#出力形式

#生のJSON（コネクタ出力）

コネクタは handle_api_extraction(data, limit, return_type) を介して HubSpot API から 生のJSON を返します。データはAPIから返されるリストの辞書です。

例：CRMオブジェクト（contacts）：

{
  "id": "123",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-03-20T14:22:00.000Z",
  "archived": false,
  "properties": {
    "email": "john@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "createdate": "2024-01-15T10:30:00.000Z"
  }
}

#フラット化された出力（Lakehouse）

プラットフォームは自動的に生のJSONをフラットなテーブルにフラット化します。ネストされたキーはアンダースコアで結合された列名になります：

列名は スラグ化 されます：小文字、ドット/特殊文字はアンダースコアに置き換えられ、文字またはアンダースコアで始まる必要があります。

#制限事項

• プロパティ値は常に文字列 です。数値や日付はダウンストリーム処理でキャストしてください。
• カスタムオブジェクトはサポートされていません：object_type パラメータは27種類の標準CRMタイプ + オーナーズの固定選択リストです。カスタムオブジェクトタイプはこのコネクタで抽出できません。
• 一部のオブジェクトタイプは有料プランが必要 です：請求書、サブスクリプション、目標はSales HubまたはCommerce Hubが必要です。リードにはSales Hub Professional+が必要です。コマースオブジェクト（カート、割引、手数料、税金）にはCommerce Hubが必要です。APIは利用不可の場合に403を返します。
• フォーム送信はv1 APIを使用 します：レガシーのv1 APIを使用している唯一のエンドポイントです。カーソルベースの代わりにオフセットページネーションを使用します。
• 行動イベント：Marketing Hub Enterpriseおよび特定のレコードIDが必要です（すべてのイベントを一括抽出できません）。
• Lakehouseの列名はスラグ化 されます：properties.email は properties_email になります。これはプラットフォームによって処理され、コネクタではありません。

#さらに詳しく

トレーニングや技術的なサポートが必要な場合は、営業担当者にお問い合わせください、またはこのリンクをクリックして、プロフェッショナルサービスの専門家にプロジェクトのカスタム分析を依頼し、見積もりを受け取ってください。

質問をする、フィードバックを送信する、およびData Platformを構築しているチームと直接やり取りするには、専用のDiscordチャネルにアクセスしてください。

OVHcloudサービスについてサポートが必要な場合は、ヘルプセンターでリクエストを作成してください。

ユーザーコミュニティに参加してください。