ベータHubSpotのデータをMicrosoft Fabricにエクスポートする

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

「Data Out」を使用して、選択した HubSpot CRM データを、ご自身が所有する Microsoft Fabric ウェアハウスのネイティブテーブルにエクスポートします。オブジェクト、関連付け、およびイベントのデータをウェアハウス内のテーブルに同期させ、そのデータをSQLでクエリしたり、ビジネスインテリジェンスやアナリティクスツールで活用したりすることができます。

同期が行われるたびに、選択されたデータの完全なスナップショットが作成されます。同期が成功すると、宛先テーブル内の以前のスナップショットが置き換えられます。

始める前に

要件を理解する

データを Microsoft Fabric にエクスポートするには、以下のものが必要です：

• Fabric Warehouse を含む Microsoft Fabric ワークスペース
• 「Contributor」ロールを持つ Microsoft Entra ID サービスプリンシパルが Fabric ワークスペースに追加されました
• サービスプリンシパルのテナント ID、クライアント ID、およびクライアントシークレット
• Fabric WarehouseのSQL接続文字列（サーバーアドレス、ポート番号を除く）およびウェアハウス名

Microsoft Entra ID のサービスプリンシパルは、宛先の Fabric Warehouse 内で HubSpot が所有するオブジェクトを作成および管理する権限を持っている必要があります。接続の検証および同期の過程で、HubSpot はスキーマとテーブルを作成し、データを挿入し、ステージングテーブルの名前を変更し、一時オブジェクトを削除します。Fabric ワークスペースにおいて、サービスプリンシパルに「Contributor」ロールを付与し、HubSpot が以下の操作を行えるようにします：

• スキーマを作成する
• テーブルを作成する
• 行を挿入する
• HubSpotが所有するテーブルの名前変更または変更
• HubSpotが所有するテーブルとスキーマを削除する

Fabric WarehouseのSQLエンドポイントは、TCPポート1433経由でHubSpotからアクセス可能である必要があります。HubSpotでは、すべての接続にTLSを使用し、サーバー証明書の検証を行っています。

Fabric ワークスペースでネットワークアクセスが制限されている場合は、アカウントのリージョンに対応する HubSpot の送信元 IP アドレスを許可リストに追加してください。

制限事項と考慮事項を理解する

• Microsoft Fabric Data Out は、Fabric ウェアハウスでのみサポートされています。Lakehouses はサポートされていません。
• 同期処理が実行されるたびに、選択されたデータの完全なスナップショットが作成されます。同期が正常に完了すると、宛先テーブル内の以前のスナップショットが置き換えられます。HubSpotでは、以前のスナップショットは保持されません。同期中にテーブルでエラーが発生した場合、そのテーブルの以前のデータは、次に同期が正常に完了するまで引き続き利用可能です。
• 各オブジェクトタイプ、イベントタイプ、または関連付けのペアは、アカウントごとに1つの定期的なMicrosoft Fabric同期に含めることができます。
• 同期が行われるたびに、宛先テーブルの内容が上書きされます。Fabric Warehouse に追加されたテーブルレベルのグラントや設定は、同期のたびに保持されません。
• 別のサービスプリンシパルと再接続するには、接続テストや同期を成功させる前に、そのサービスプリンシパルを「Contributor」ロールでFabricワークスペースに追加する必要があります。

HubSpot を Microsoft Fabric に連携する

HubSpotアカウントとMicrosoft Fabricコンソールは、それぞれ別のタブで開いておくことをお勧めします。

1. HubSpotアカウントで、［その他］をクリックし、［データ管理］＞［データスタジオ］に移動します。アカウントに［その他］が表示されない場合は、［データ管理］＞［データスタジオ］に直接移動します。
2. 右上の「外部データソースを接続」をクリックします。
3. [ データソースの追加 ] パネルで、Microsoft Fabricを検索するか、参照して選択します。
4. [インストール ] をクリックし、次に [ 次へ ] をクリックします。
5. サービスプリンシパルのテナント ID、クライアント ID、およびクライアントシークレットを入力してください。
6. 以下の宛先情報を入力してください：
   • SQL接続文字列： Fabric Warehouseのサーバーアドレス（ポート番号を除く）。
   • 倉庫名：エクスポート先のファブリック倉庫の名前。
7. [ 接続テスト ] をクリックします。接続テストが成功した場合は、「次へ」をクリックしてください。

ご注意： Fabric ワークスペースで、接続テストを実行する前に、HubSpot サービスプリンシパルに「Contributor」ロールが割り当てられていることを確認してください。アクセス設定を行うためにSQLスクリプトは必要ありません。

同期を設定

1. エクスポートするデータソースを選択してください：
   • オブジェクト
   • 関連付け
   • イベント
2. 含めるオブジェクト、プロパティー、関連付け、またはイベントを選択してください。
3. 同期を実行する頻度と開始時刻を選択してください。
4. 「同期を開始」をクリックしてください。

ベータ版期間中は、利用可能な同期周波数が変動する場合があります。選択肢としては、「1回」、「6時間ごと」、「12時間ごと」、「毎日」、「毎週」、「毎月」などがあります。

エクスポートしたデータにアクセスする

HubSpotは、各宛先に対してHubSpotが管理するスキーマを作成します。表は次の形式で作成されています：

<database>.hubspot_data_out_<destination-id>.<table-name>

例えば、次のような使い方が考えられます。

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

正確なスキーマ名は、同期設定ページで確認できます。

テーブル名と列名

HubSpotでは、エクスポートされたテーブル名および列名を、大文字、数字、およびアンダースコアに正規化します：

• スペースとハイフンはアンダースコアに置き換えられます。
• その他の英数字以外の文字は削除されます。
• 128文字を超える名前は短縮されます。
• 重複する列名には接尾辞が付与されます。
• テーブル名の重複があると、該当するエクスポートが失敗します。

列のタイプ

「PROPERTIES列はOBJECT_WITH_OBJECT_PROPERTIESは、VARCHAR(MAX)にJSON形式の文字列として格納され、ネイティブなJSONカラム型として格納されるわけではありません。以下のFAQにあるクエリの例をご覧ください。

オブジェクトテーブル

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

OBJECT_PROPERTIES

この表には、オブジェクトのプロパティー値ごとに1行ずつ含まれています。

OBJECT_WITH_OBJECT_PROPERTIES

このテーブルには、各オブジェクトレコードごとに1行が含まれています。選択されたプロパティー値は、PROPERTIES列にグループ化されます。

このテーブルには、さまざまなオブジェクトタイプのオブジェクトデータがまとめられています。特定のオブジェクトタイプOBJECTTYPEID特定のオブジェクトタイプのレコードを読み取るには：

• 連絡先：0～1
• カスタムオブジェクト：2-{unique_id },（例：2-12345）

OBJECT_PROPERTIES_HISTORY

この表には、プロパティー変更履歴が記載されています。このデータには、プロパティーの過去の値ごとに1行が含まれています。

特定のレコードおよびプロパティーに関する完全な履歴をビューするには、結果をUPDATEDATで並べ替えてください。

関連付けテーブル

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

協会

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

ASSOCIATION_DEFINITIONS

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

ペアごとの関連付けテーブル

選択された関連付けのペアについて、HubSpotでは以下の形式の表をエクスポートすることもできます：

ASSOCIATIONS_<FROM_OBJECT_TYPE>_TO_<TO_OBJECT_TYPE>

例えば：ASSOCIATIONS_CONTACTS_TO_COMPANIES

これらのテーブルには、関連付けレコードおよび関連付け定義のメタデータが含まれています。

イベントテーブル

イベントデータを選択すると、HubSpotはイベントタイプごとに1つのテーブルをエクスポートします。イベントテーブル名は、以下の形式を使用します：

EVENTS_<EVENT_NAME>

例えば：EVENTS_VISITED_PAGE

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

同期状況を監視する

1. HubSpotアカウントで、［その他］をクリックし、［データ管理］＞［データスタジオ］に移動します。アカウントに［その他］が表示されない場合は、［データ管理］＞［データスタジオ］に直接移動します。
2. 左側の「アプリの同期」をクリックします。
3. 「Microsoft Fabric sync」を検索するか、選択してください。

同期の詳細ページでは、同期ステータス、最終同期日時、エラー、同期のアクティビティー状況、および同期履歴を確認できます。また、同期を一時停止したり、アーカイブしたり、手動で実行したりすることもできます。

同期ステータス

同期の失敗を解決する

同期に失敗した場合：

• HubSpotのUIには「失敗」というステータスが表示され、どのテーブルが成功し、どのテーブルが失敗したかを示すテーブルレベルの詳細情報が表示されます。
• テーブルは、HubSpotがすべてのデータの読み込みを完了してから初めて更新されます。テーブルの同期に失敗した場合、そのテーブルの以前のデータは、次に同期が正常に完了するまでそのまま残ります。
• 次回の予定された同期では、自動的に再度完全同期が試行されます。
• 同期の詳細ページから、手動で同期を実行することができます。

よくある質問

エクスポートしたデータをどのように照会すればよいですか？

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

-- Read all contact records
SELECT *
FROM [your_database].[hubspot_data_out_456].[OBJECT_WITH_OBJECT_PROPERTIES]
WHERE [OBJECTTYPEID] = '0-1'; -- Read a specific property from the PROPERTIES JSON string
SELECT
  [OBJECTID],
  JSON_VALUE([PROPERTIES], '$.email') AS [email]
FROM [your_database].[hubspot_data_out_456].[OBJECT_WITH_OBJECT_PROPERTIES]
WHERE [OBJECTTYPEID] = '0-1';

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

各オブジェクトタイプ、イベントタイプ、または関連付けのペアは、HubSpotアカウントごとに1つの定期的なMicrosoft Fabric同期に含めることができます。これは、他のデータアウトプロバイダーとは独立したものです。

たとえば、連絡先がすでに定期的なFabricの保存先にエクスポートされている場合、最初の設定をアーカイブするまでは、別の定期的なFabric設定に連絡先を追加することはできません。その際も、対応している別のData Outプロバイダーへ連絡先をエクスポートすることは可能です。

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

次のようなオブジェクト固有のテーブルOBJECTS_CONTACTS、といったオブジェクト固有のテーブルは、現時点ではサポートされていません。「OBJECT_WITH_OBJECT_PROPERTIESを使用して、OBJECTTYPEIDを使用して、特定のオブジェクトタイプのレコードを取得します。

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

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

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

いいえ。同期が正常に完了するたびに、宛先テーブルは最新のスナップショットで上書きされます。HubSpotでは、以前のスナップショットは保持されません。同期中にテーブルでエラーが発生した場合、そのテーブルが正常に更新されるまで、以前のデータはそのままで残ります。

HubSpotでは、私が管理するステージング・バケットが使われていますか？

いいえ。HubSpotは、HubSpotが管理するストレージに一時的なParquet形式のエクスポートファイルを作成し、その結果をFabric Warehouseに書き込みます。ステージング用バケットを用意したり管理したりする必要はありません。

別のサービスプリンシパルで再接続するとどうなりますか？

別のサービスプリンシパルを使用して再接続する場合は、接続テストや同期を正常に実行するために、そのサービスプリンシパルを「Contributor」ロールでFabricワークスペースに追加する必要があります。