測試版透過 Microsoft Azure Synapse Analytics 存取您的 HubSpot 資料

使用「Azure Synapse 資料輸出」功能，將選定的 HubSpot CRM 資料匯出至您所擁有的 Azure Synapse 專用 SQL 儲存池中的資料表。HubSpot 會透過完整匯出選定的資料來更新每個輸出資料表。同步完成後，您可以使用 SQL 或您偏好的 BI 與分析工具查詢這些資料表，將 HubSpot 資料與其他業務資料結合。

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

了解限制與注意事項

在開始使用此功能之前，請務必充分了解應事先採取的步驟，以及該功能的限制與使用時可能產生的後果。

• HubSpot 會分別更新各張資料表。若在同步執行期間跨多張資料表進行查詢，部分資料表可能會比其他資料表更早完成更新。
• Data Out 不提供歷史快照保留功能。成功刷新後，目標資料表將包含最新的快照。
• 每個 HubSpot 帳戶中，每個物件、事件類型或關聯對僅能包含於一次 Azure Synapse 定期同步中。此限制與其他 Data Out 提供者無關。
• 目前尚不支援物件專用資料表，例如OBJECTS_CONTACTS。
• 若 HubSpot 將兩個表名稱正規化後發生名稱衝突，受影響的匯出作業將會失敗。如需更多資訊，請參閱表與欄位名稱規則。

了解可匯出的資料

您可以將以下資料從 HubSpot 同步至 Azure Synapse Analytics：

• 物件與記錄：選定的標準及自訂物件及其記錄，例如聯絡人、公司、交易、服務單和產品。
• 屬性：記錄上的選定屬性值及屬性歷史紀錄。
• 關聯：記錄之間的選定關聯關係，包括關聯定義。
• 事件：選定的標準 HubSpot 事件和自訂行為事件，包括選定的事件屬性。

不同物件的資料會整合在物件資料表中。當您讀取物件資料表時，請使用OBJECTTYPEID篩選特定物件。例如，聯絡人的 ID 為0-1。自訂物件在建立時會被指派一個 ID，並以2-{unique_id} 的形式標示，例如2-12345。

了解匯出格式

在設定過程中，您需選擇：

• 目標 Azure Synapse 專用 SQL 端點與資料庫。
• 要同步的資料來源：物件、事件、關聯，或這些來源的組合。
• 同步排程。

HubSpot 會在 HubSpot 管理的儲存空間中建立一個暫時的 Parquet 匯出檔，並將結果寫入您 Azure Synapse 專用 SQL 儲存池中的資料表。您無需提供或管理暫存儲存桶。

在 Azure Synapse 中查找您的資料

HubSpot 會根據您的目標位置，在 HubSpot 管理的資料結構中建立輸出資料表。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 個字元的名稱將被縮短。
• 若欄位名稱發生衝突，系統會為其添加後綴。
• 若表名稱發生衝突，將導致受影響的匯出作業失敗。

查詢識別符時請使用方括號，特別是在動態建構查詢時。識別符是否區分大小寫取決於您的 Synapse 資料庫排序規則。例如：

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

欄位類型

欄位類型遵循匯出資料的格式，並依下列方式對應至 Azure Synapse 類型：

請注意： PROPERTIES中的OBJECT_WITH_OBJECT_PROPERTIES欄位會以 JSON 格式的字串形式匯出。其儲存類型為NVARCHAR(MAX)，而非 JSON 欄位類型。有關查詢範例，請參閱常見問題解答。

檢視物件資料表

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

OBJECT_PROPERTIES

此資料表中，每個屬性值對應一行。若要讀取特定物件，請依OBJECTTYPEID 進行篩選。

OBJECT_WITH_OBJECT_PROPERTIES

此資料表中每筆記錄對應一行，所選屬性值會彙整至單一的PROPERTIES欄位中。若要讀取特定物件，請依OBJECTTYPEID 進行篩選。

OBJECT_PROPERTIES_HISTORY

此資料表包含屬性變更歷史紀錄。與僅儲存當前值的OBJECT_PROPERTIES 不同，此資料表針對每個屬性的歷史值各有一筆記錄。若要檢視單一記錄與屬性的完整時間軸，請依UPDATEDAT 排序。

檢視關聯表

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

ASSOCIATIONS

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

ASSOCIATION_DEFINITIONS

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

ASSOCIATIONS_<來源物件>_TO_<目標物件>

針對選定的關聯對，HubSpot 亦可匯出特定於該對的關聯資料表，例如ASSOCIATIONS_CONTACTS_TO_COMPANIES。這些資料表包含關聯記錄以及關聯定義的元資料。

檢視事件資料表

若您選取事件資料，HubSpot 會針對每種事件類型匯出一個資料表。資料表名稱採用EVENTS_<EVENT_NAME> 的格式，例如EVENTS_VISITED_PAGE。

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

管理同步排程

您可在 HubSpot 的設定過程中配置同步排程。您也可以從 HubSpot 手動觸發重新同步。每次同步執行都會產生所選資料的完整快照。為控制資料量，請選擇要包含的物件、事件、關聯及屬性。

請注意：在測試版期間，可用的同步頻率可能會受到限制。未來版本可能會新增其他頻率選項。

監控同步並處理錯誤

您可以在 HubSpot 中監控 Azure Synapse 的同步作業。同步作業可能處於以下任一狀態：

當同步失敗時：

• HubSpot 會顯示「失敗」狀態，並提供哪些資料表成功或失敗的詳細資訊。
• 若某個資料表無法更新，先前成功匯入的資料通常仍可使用。
• 對於定期同步，下次排定的同步會自動重新嘗試執行完整同步。
• 您可隨時在 HubSpot 中手動觸發重新同步。

常見問題

如何查詢資料？

請使用 SQL 查詢目標資料結構中的資料表。例如，讀取所有聯絡人記錄：

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

從PROPERTIESJSON 字串中讀取特定屬性：

SELECT
  [OBJECTID],
  JSON_VALUE([PROPERTIES], '$.email') AS [email]
FROM [your_database].[hubspot_data_out_456].[OBJECT_WITH_OBJECT_PROPERTIES]
WHERE [OBJECTTYPEID] = '0-1';

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

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

例如，若聯絡人已匯出至一個週期性的 Azure Synapse 目標，您必須先將第一個同步作業歸檔，才能將聯絡人新增至另一個週期性的 Azure Synapse 同步作業。您仍可同時將聯絡人匯出至其他受支援的「資料輸出」提供者。

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

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

HubSpot 會保留先前的快照嗎？

不會。Data Out 不提供歷史快照保留功能。成功刷新後，目標資料表將包含最新的快照。若資料表無法更新，先前成功傳輸的資料通常仍可取得。