測試版從 PostgreSQL 或 MySQL 存取您的 HubSpot 資料

使用 PostgreSQL 和 MySQL 的「資料匯出」功能，將選定的 HubSpot CRM 資料匯出至您所擁有的資料庫中的資料表。每次同步執行時，系統會寫入選定資料的完整快照，並覆寫先前的快照。同步完成後，您可以透過 SQL 或您偏好的 BI 及分析工具查詢這些資料表，將 HubSpot 資料與其他業務資料整合。

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

了解限制與注意事項

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

• 每次同步都會將目標資料表替換為最新的快照。HubSpot 不會保留先前的快照。
• 每個 HubSpot 帳戶中，每個物件、事件類型或關聯對，可包含於一次定期的 PostgreSQL 同步及一次定期的 MySQL 同步中。這些同步作業彼此獨立，且與其他 Data Out 提供者互不干涉。
• 目前尚不支援敏感資料。可將敏感屬性從匯出內容中排除。
• 目前尚不支援物件專屬資料表，例如OBJECTS_CONTACTS。
• 在 PostgreSQL 中，資料表和欄位名稱區分大小寫；在 MySQL 中，資料表和欄位名稱也可能區分大小寫。撰寫查詢前，請先檢視查詢語法。

了解可匯出的資料

您可以將以下資料從 HubSpot 同步至 PostgreSQL 或 MySQL：

• 物件：標準與自訂物件，例如聯絡人、公司、商機、服務單及產品。
• 記錄：所選物件的個別記錄。
• 屬性：記錄中的選取屬性值及屬性歷史紀錄。
• 關聯：記錄之間的選定關係，包括關聯定義。
• 事件：選定的標準 HubSpot 事件及自訂行為事件，包括選定的事件屬性。

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

了解匯出格式

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

• 目標資料庫。此設定僅適用於 PostgreSQL。若使用 MySQL，則由 HubSpot 建立資料庫。
• 要同步的資料來源：物件、事件、關聯，或這些來源的組合。
• 同步排程。

HubSpot 會將資料匯出為 Parquet 檔案，並直接載入至您的資料庫表中。PostgreSQL 和 MySQL 不會使用客戶自有的暫存桶。HubSpot 會內部管理暫存流程。

在資料庫中查找您的資料

HubSpot 會針對每個資料來源，在一個由 HubSpot 管理的、以您的目標名稱命名的資料結構中建立一個資料表。您可以在同步的設定頁面上找到確切的資料結構名稱。

• PostgreSQL： <database>.hubspot_data_out_<destination-id>.<table-name>
• MySQL： hubspot_data_out_<destination-id>.<table-name>。在 MySQL 中，模式（schema）與資料庫是同一概念，且由 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，在 MySQL 中儲存為LONGTEXT，而非 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 手動觸發重新同步。每次同步執行都會產生所選資料的完整快照。為控制資料量，請選擇要包含的物件、事件、關聯及屬性。

請注意：在測試版期間，可能僅提供有限的同步頻率選項，例如「一次」、「每 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';

從PROPERTIESJSON 欄位讀取特定屬性。由於該欄位以文字形式儲存，請先將其轉換為 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';

從PROPERTIESJSON 欄位讀取特定屬性：

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

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

每個物件、事件類型或關聯對，在每個 HubSpot 帳戶中，可分別包含於一個定期 PostgreSQL 同步作業及一個定期 MySQL 同步作業中。這些同步作業彼此獨立，且與其他「資料輸出」供應商亦無關聯。例如，若聯絡人已匯出至一個定期 PostgreSQL 目的地，您必須先將第一個同步作業歸檔，才能將聯絡人新增至另一個定期 PostgreSQL 同步作業。同時，您仍可將聯絡人匯出至定期 MySQL 同步作業。

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

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

是否支援敏感資料？

不支援。目前「資料匯出」功能尚不支援敏感資料。您可將敏感屬性從匯出清單中排除。

HubSpot 會保留之前的快照嗎？

不。每次同步都會以最新的快照取代目標資料表，因此不會保留先前快照。