ベータPostgreSQL または MySQL から HubSpot データにアクセスする

PostgreSQL および MySQL 用の「Data Out」機能を使用して、選択した HubSpot CRM データを、ご自身が所有するデータベース内のテーブルにエクスポートします。同期処理が実行されるたびに、選択されたデータの完全なスナップショットが書き込まれ、以前のスナップショットが上書きされます。同期が完了したら、SQL またはお好みの BI ツールやアナリティクスツールを使用してテーブルをクエリし、HubSpot のデータを他のビジネスデータと統合することができます。

注: スーパー管理者である場合は、この機能を使用するには、アカウントをデータポータルベータ版 にオプトインしてください。

制限事項と考慮事項について

この機能を使い始める前に、あらかじめ必要となる手順と、この機能の使用に伴う制限事項と潜在的な結果について十分に理解しておいてください。

• 同期が行われるたびに、宛先テーブルは最新のスナップショットで上書きされます。HubSpotでは、以前のスナップショットは保存されません。
• 各オブジェクト、イベントタイプ、または関連付けのペアは、HubSpotアカウントごとに、PostgreSQLとの定期同期1回およびMySQLとの定期同期1回に含めることができます。これらの同期は、互いに独立しているほか、他のData Outプロバイダーとも独立しています。
• センシティブデータについては、現時点では対応していません。機密性の高いプロパティーは、エクスポートの対象から除外される場合があります。
• 次のようなオブジェクト固有のテーブルOBJECTS_CONTACTS、といったオブジェクト固有のテーブルは、現時点ではサポートされていません。
• PostgreSQL ではテーブル名やカラム名は大文字と小文字が区別されますが、MySQL でも大文字と小文字が区別される場合があります。クエリを作成する前に、クエリの構文を確認してください。

エクスポート可能なデータについて理解する

HubSpot から PostgreSQL または MySQL へ、以下のデータを同期することができます：

• オブジェクト：連絡先、企業、商談、チケット、製品など、標準およびカスタムオブジェクト。
• レコード：選択したオブジェクトごとの個別のレコード。
• プロパティー：レコードの選択されたプロパティー値およびプロパティーの履歴。
• 関連付け：レコード間の特定の関係。これには、関連付けの定義も含まれます。
• イベント：特定の標準HubSpotイベントおよびカスタム行動イベント。これには、特定のイベントプロパティーも含まれます。

各オブジェクトのデータは、オブジェクトテーブルにまとめられています。オブジェクトテーブルを読み込む際は、OBJECTTYPEIDを使用して、特定のオブジェクトに絞り込んでください。たとえば、連絡先では0-1を使用します。カスタムオブジェクトには、作成時にIDが割り当てられ、2-{unique_id}、例えば2-12345。

エクスポート形式について理解する

セットアップ中に、以下の項目を選択します：

• 宛先データベース。これはPostgreSQLにのみ適用されます。MySQLの場合、HubSpotがデータベースを作成します。
• 同期するデータソース：オブジェクト、イベント、関連付け、またはこれらの組み合わせ。
• 同期スケジュール。

HubSpotはデータをParquetファイルとしてエクスポートし、データベース内のテーブルに直接読み込みます。PostgreSQL と MySQL では、顧客所有のステージングバケットは使用されません。HubSpotでは、ステージングを内部で管理しています。

データベースからデータを探す

HubSpot は、データソースごとに 1 つのテーブルを作成し、そのテーブルは、宛先の名前にちなんで名付けられた HubSpot が管理するスキーマ内に配置されます。正確なスキーマ名は、同期の設定ページで確認できます。

• PostgreSQL：<database>.hubspot_data_out_<destination-id>.<table-name>
• MySQL:hubspot_data_out_<destination-id>.<table-name> .MySQLでは、スキーマとデータベースは同じ概念であり、HubSpotがこれを作成します。データベースレベルを個別に選択するオプションはありません。

たとえば、PostgreSQLでは：

• your_database.hubspot_data_out_456.OBJECT_WITH_OBJECT_PROPERTIES
• your_database.hubspot_data_out_456.EVENTS_VISITED_PAGE
• your_database.hubspot_data_out_456.ASSOCIATIONS_CONTACTS_TO_COMPANIES

たとえば、MySQLでは：

• hubspot_data_out_456.OBJECT_WITH_OBJECT_PROPERTIES
• hubspot_data_out_456.EVENTS_VISITED_PAGE
• hubspot_data_out_456.ASSOCIATIONS_CONTACTS_TO_COMPANIES

同期が行われるたびに、テーブルは最新のスナップショットに置き換えられます。HubSpotでは、以前のスナップショットは保存されません。同期中にテーブルでエラーが発生した場合、そのテーブルの以前のデータは、次に同期が正常に完了するまでそのまま残ります。

テーブル名と列名

テーブル名と列名は、エクスポートされたデータに基づいています。PostgreSQL の識別子は 63 文字まで、MySQL の識別子は 64 文字までです。HubSpotは、長い名前を適切な長さに短縮します。

識別子の大文字小文字

識別子の大文字小文字は区別されます。HubSpot は、この記事に記載されているテーブルに合わせて、引用符で囲まれ、大文字小文字を区別した大文字の名称を持つすべてのテーブルと列を作成します。

• PostgreSQL：表示されている通り、名前を二重引用符で囲んでください。PostgreSQL では、引用符で囲まれていない名前は小文字に変換されるため、一致しません。
• MySQL：バッククォートを使用し、表示されている大文字小文字を区別して入力してください。テーブル名の大文字・小文字の区別は、サーバーの設定によって異なります。

PostgreSQL の例：

SELECT * FROM your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES" WHERE "OBJECTTYPEID" = '0-1';

MySQL の例：

SELECT * FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES` WHERE `OBJECTTYPEID` = '0-1';

列のタイプ

列の型はエクスポートされたデータに準拠しており、PostgreSQL および MySQL の型とは次のように対応しています：

ご注意：PROPERTIESの列はOBJECT_WITH_OBJECT_PROPERTIESの列は、JSON形式の文字列としてエクスポートされます。PostgreSQLではTEXT PostgreSQL内ではLONGTEXT MySQLでは、JSON列型としてではなく、この形式で格納されます。クエリの例については、FAQをご覧ください。

オブジェクトテーブルの確認

オブジェクトデータを選択すると、HubSpot は以下のテーブルをエクスポートします。

OBJECT_PROPERTIES

この表には、プロパティー値ごとに1行ずつ含まれています。特定のオブジェクトを読み取るには、OBJECTTYPEIDでフィルタリングします。

OBJECT_WITH_OBJECT_PROPERTIES

このテーブルにはレコードごとに1行が含まれており、選択されたプロパティーの値は1つのPROPERTIES列にまとめられています。特定のオブジェクトを読み取るには、OBJECTTYPEIDでフィルタリングします。

OBJECT_PROPERTIES_HISTORY

この表には、プロパティー変更履歴が記載されています。これとは異なりOBJECT_PROPERTIESとは異なり、このテーブルにはプロパティーの過去の値ごとに1行が格納されています。個々のレコードおよびプロパティーのタイムライン全体を表示するには、UPDATEDATで並べ替えてください。

関連付けテーブルを確認

関連付けデータを選択すると、HubSpotは関連付けレコードと関連付け定義をエクスポートします。

協会

このテーブルには、2つのレコード間の選択された関連付けごとに1行が含まれています。

ASSOCIATION_DEFINITIONS

この表には、選択された関連付けの定義ごとに1行が格納されています。

ASSOCIATIONS_ <FROM_OBJECT>_TO_ <TO_OBJECT>

選択された関連付けのペアについては、HubSpotでは、次のようなペア固有の関連付けテーブルをエクスポートすることも可能です。ASSOCIATIONS_CONTACTS_TO_COMPANIES。これらのテーブルには、関連付けレコードと、関連付けの定義に関するメタデータが含まれています。

イベントテーブルを確認する

イベントデータを選択すると、HubSpotはイベントタイプごとに1つのテーブルをエクスポートします。テーブル名は、EVENTS_<EVENT_NAME>の形式で指定され、例えばEVENTS_VISITED_PAGEといった形式です。

各イベントテーブルには、標準のイベント列と、選択されたイベントプロパティーごとに1つの列が含まれています。

同期スケジュールの管理

HubSpotでのセットアップ中に、同期スケジュールを設定します。HubSpotから手動で再同期のトリガーを実行することもできます。同期処理が実行されるたびに、選択されたデータの完全なスナップショットが生成されます。データ量を制御するには、含めるオブジェクト、イベント、関連付け、およびプロパティーを選択してください。

ご注意：ベータ版期間中は、同期頻度が「1回」「6時間ごと」「12時間ごと」「毎日」「毎週」「毎月」など、限られた選択肢のみ利用可能となる場合があります。今後のリリースで、さらに周波数オプションが追加される可能性があります。

同期の監視とエラー処理

HubSpotでは、PostgreSQLおよびMySQLの同期状況を監視できます。同期には、以下のいずれかの状態があります：

同期に失敗した場合：

• HubSpot では「失敗」というステータスが表示され、テーブルごとの詳細には、どのテーブルが成功し、どのテーブルが失敗したかが示されます。
• テーブルは、HubSpotがすべてのデータの読み込みを完了してから初めて更新されるため、読み込みが途中段階のテーブルが表示されることはありません。
• テーブルの同期に失敗した場合、そのテーブルの以前のデータは、次に同期が正常に完了するまでそのまま残ります。
• 次に予定されている同期では、フル同期が自動的に再試行されます。
• HubSpotでは、いつでも手動で再同期のトリガーを実行できます。

前回の実行で正常に処理されたテーブルは、その後の実行で失敗しても変更されません。

よくある質問

データの照会方法は？

SQL を使用して、宛先スキーマ内のテーブルをクエリします。

PostgreSQL

すべてのコンタクトレコードを読み込む：

SELECT * FROM your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES" WHERE "OBJECTTYPEID" = '0-1';

特定のプロパティーをPROPERTIES JSON列から特定のプロパティを読み取ります。その列はテキストとして格納されているため、まずJSON型に変換してください：

SELECT "OBJECTID", json_extract_path_text("PROPERTIES"::json, 'email') AS email FROM your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES" WHERE "OBJECTTYPEID" = '0-1';

MySQL

すべてのコンタクトレコードを読み込む：

SELECT * FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES` WHERE `OBJECTTYPEID` = '0-1';

特定のプロパティーをPROPERTIES JSON列から特定のプロパティを読み取るには：

SELECT `OBJECTID`, JSON_EXTRACT(`PROPERTIES`, '$.email') AS email FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES` WHERE `OBJECTTYPEID` = '0-1';

1つのデータ型を複数の同期でエクスポートすることはできますか？

各オブジェクト、イベントタイプ、または関連付けのペアは、HubSpotアカウントごとに、PostgreSQLとの定期同期1回およびMySQLとの定期同期1回に含めることができます。これらの同期は、互いに独立しているほか、他のData Outプロバイダーとも独立しています。たとえば、連絡先がすでに定期的なPostgreSQLへの同期先にエクスポートされている場合、最初の同期をアーカイブするまでは、別の定期的なPostgreSQL同期先に連絡先を追加することはできません。それでも、連絡先を定期的なMySQL同期に同時にエクスポートすることは可能です。

オブジェクト固有のテーブルはサポートされていますか？

いいえ。OBJECTS_CONTACTSのようなオブジェクト固有のテーブルは、現時点ではサポートされていません。「使用」OBJECT_WITH_OBJECT_PROPERTIESを使用し、OBJECTTYPEIDでフィルタリングして、特定のオブジェクトのレコードを取得します。

センシティブデータは対応していますか？

いいえ。現時点では、Data Out ではセンシティブデータはサポートされていません。機密性の高いプロパティーは、エクスポートの対象から除外される場合があります。

HubSpotは以前のスナップショットを保存していますか？

いいえ。同期を行うたびに、宛先テーブルは最新のスナップショットで上書きされるため、以前のスナップショットは保持されません。