測試版將 HubSpot 資料匯出至 Microsoft Fabric

請注意：若您是超級管理員，請將您的帳戶加入Data Studio 測試版，才能使用此功能。

使用「Data Out」將選定的 HubSpot CRM 資料匯出至您所擁有的 Microsoft Fabric 資料倉儲中的原生資料表。您可以將物件、關聯及事件資料同步至資料倉儲中的資料表，隨後透過 SQL 查詢該資料，或將其用於您的商業智慧與分析工具。

每次同步都會建立所選資料的完整快照。當同步成功時，系統會將目標資料表中的先前快照替換為新快照。

開始之前

了解需求

若要將資料匯出至 Microsoft Fabric，您需要：

• 包含 Fabric 資料倉儲的 Microsoft Fabric 工作區
• 已將具備「貢獻者」角色的 Microsoft Entra ID 服務主體新增至 Fabric 工作區
• 該服務主體的租戶 ID、客戶端 ID 及客戶端密鑰
• 您的 Fabric 資料倉儲 SQL 連線字串（伺服器位址，不含連接埠號碼）及資料倉儲名稱

Microsoft Entra ID 服務主體必須具備在目標 Fabric 資料倉儲中建立及管理 HubSpot 所擁有物件的權限。在連線驗證及同步過程中，HubSpot 會建立資料結構與資料表、插入資料、重新命名暫存資料表，並移除臨時物件。請在 Fabric 工作區中授予該服務主體「貢獻者 (Contributor)」角色，以允許 HubSpot：

• 建立資料結構
• 建立資料表
• 插入資料列
• 重新命名或變更 HubSpot 擁有的資料表
• 刪除 HubSpot 擁有的資料表和資料庫架構

您的 Fabric Warehouse SQL 端點必須可讓 HubSpot 透過 TCP 埠 1433 存取。HubSpot 會對所有連線使用 TLS 並驗證伺服器憑證。

若您的 Fabric 工作區限制網路存取，請將您帳戶區域的 HubSpot 出站 IP 位址加入允許清單。

了解限制與注意事項

• Microsoft Fabric Data Out 僅支援 Fabric 資料倉儲，不支援 Lakehouse。
• 每次同步執行都會建立所選資料的完整快照。同步成功後，將以新快照取代目標資料表中的先前快照。HubSpot 不會保留先前快照。若資料表在同步過程中發生失敗，其先前資料將持續可用，直至下次同步成功為止。
• 每個物件類型、事件類型或關聯對，每個帳戶僅能包含於一次 Microsoft Fabric 定期同步中。
• 每次同步都會覆寫目標資料表。您在 Fabric 資料倉儲中新增的資料表層級授權或設定，在同步之間不會被保留。
• 若要重新連線至不同的服務主體，必須在進行連線測試或同步之前，將該服務主體以「貢獻者」角色新增至 Fabric 工作區，連線測試或同步才能成功。

將 HubSpot 連接到 Microsoft Fabric

建議在不同的分頁中分別開啟您的 HubSpot 帳戶和 Microsoft Fabric 控制台。

1. 在你的 HubSpot 帳戶中，點擊「更多」，然後前往「資料管理」 > 「Data Studio」。如果你的帳戶中沒有顯示「更多」，請直接前往「資料管理」 > 「Data Studio」。
2. 在右上角，按一下「連線至外部資料來源」。
3. 在「新增資料來源」面板中，搜尋或瀏覽至Microsoft Fabric。
4. 按一下「安裝」，然後按一下「下一步」。
5. 輸入您的服務主體的租戶 ID、客戶端 ID 及客戶端密鑰。
6. 輸入以下目標詳細資訊：
   • SQL 連線字串：您的 Fabric Warehouse 伺服器位址，不包含連接埠號碼。
   • 資料倉儲名稱：要匯出至的 Fabric 資料倉儲名稱。
7. 按一下「測試連線」。若連線測試成功，請按一下「下一步」。

請注意：在您的 Fabric 工作區中，執行連線測試前，請確認 HubSpot 服務主體已具備「貢獻者」角色。配置存取權限無需任何 SQL 指令碼。

設定同步

1. 選取要匯出的資料來源：
   • 物件
   • 關聯
   • 事件
2. 請選擇要包含的物件、屬性、關聯或事件。
3. 選擇同步的執行頻率以及開始時間。
4. 點擊「開始同步」。

在測試版期間，可用的同步頻率可能會有所不同。選項包括「一次」、「每 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欄位，是以 JSON 格式的字串儲存於VARCHAR(MAX) 中，而非原生 JSON 欄位類型。請參閱下方常見問題中的查詢範例。

物件資料表

若您選取物件資料，HubSpot 會匯出以下資料表。

OBJECT_PROPERTIES

此資料表針對每個物件屬性值各包含一行。

OBJECT_WITH_OBJECT_PROPERTIES

此資料表針對每個物件記錄各包含一行。選取的屬性值會彙整在「PROPERTIES」欄位中。

此資料表會將不同物件類型的物件資料合併在一起。請透過OBJECTTYPEID進行篩選，以讀取特定物件類型的記錄：

• 聯絡人：0-1
• 自訂物件：2-{unique_id}，例如 2-12345

OBJECT_PROPERTIES_HISTORY

此資料表包含屬性變更歷史紀錄。其中每項屬性的歷史值皆對應一筆資料。

若要檢視特定記錄與屬性的完整歷史紀錄，請依UPDATEDAT 排序結果。

關聯表

若您選取關聯資料，HubSpot 將匯出關聯記錄及關聯定義。

ASSOCIATIONS

此資料表針對兩個記錄之間每項已選取的關聯，各佔一行。

ASSOCIATION_DEFINITIONS

此表格針對每個已選取的關聯定義各包含一行。

特定配對的關聯關係資料表

針對已選取的關聯對，HubSpot 亦可匯出符合以下格式的表格：

ASSOCIATIONS_<FROM_OBJECT_TYPE>_TO_<TO_OBJECT_TYPE>

例如：ASSOCIATIONS_CONTACTS_TO_COMPANIES

這些表格包含關聯記錄及關聯定義的元資料。

事件資料表

若您選取事件資料，HubSpot 會針對每種事件類型匯出一個資料表。事件資料表名稱採用以下格式：

EVENTS_<EVENT_NAME>

例如：EVENTS_VISITED_PAGE

每個事件資料表包含標準事件欄位，以及針對每個已選取事件屬性所對應的一欄。

監控同步狀況

1. 在你的 HubSpot 帳戶中，點擊「更多」，然後前往「資料管理」 > 「Data Studio」。如果你的帳戶中沒有顯示「更多」，請直接前往「資料管理」 > 「Data Studio」。
2. 在左側，點選「應用程式同步」。
3. 搜尋或選取Microsoft Fabric同步。

在同步詳細資訊頁面中，您可以查看同步狀態、上次同步時間、錯誤、同步活動以及同步記錄。您也可以暫停、歸檔或手動執行同步。

同步狀態

解決同步失敗問題

當同步失敗時：

• HubSpot 使用者介面會顯示「失敗」狀態，並提供表格層級的詳細資訊，說明哪些表格同步成功或失敗。
• 只有在 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';

我可以在多個同步作業中匯出同一种資料類型嗎？

每個物件類型、事件類型或關聯對，每個 HubSpot 帳戶僅能包含於一個 Microsoft Fabric 定期同步中。此限制與其他 Data Out 提供者無關。

例如，若聯絡人已匯出至某個定期 Fabric 目標，您必須先將該設定歸檔，才能將聯絡人新增至另一個定期 Fabric 設定。您仍可同時將聯絡人匯出至其他受支援的 Data Out 供應商。

是否支援特定物件的資料表？

目前不支援物件專屬資料表（例如OBJECTS_CONTACTS）。請使用OBJECT_WITH_OBJECT_PROPERTIES並透過OBJECTTYPEID進行篩選，以擷取特定物件類型的記錄。

是否支援敏感資料？

Data Out 目前不支援敏感資料。您可將敏感屬性從匯出內容中排除。

HubSpot 會保留先前的快照嗎？

不會。每次同步成功後，系統都會以最新的快照取代目標資料表。HubSpot 不會保留先前的快照。若資料表在同步過程中發生失敗，其先前資料將保留原位，直至該資料表成功更新為止。

HubSpot 會使用我管理的暫存儲存桶嗎？

不會。HubSpot 會在 HubSpot 管理的儲存空間中建立一個暫時的 Parquet 匯出檔案，並將結果寫入您的 Fabric Warehouse。您無需提供或管理任何暫存儲存桶。

如果我使用不同的服務主體重新連線，會發生什麼情況？

若您使用不同的服務主體重新連線，必須在進行連線測試或同步之前，將該服務主體以「貢獻者」角色新增至 Fabric 工作區，連線測試或同步才能成功。