將 HubSpot 資料匯出至 PostgreSQL 或 MySQL

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

摘要

使用「Data Out」將選定的 HubSpot CRM 資料匯出至您所管理的 PostgreSQL 或 MySQL 資料庫。您可以將物件、關聯及事件資料同步至資料庫中的資料表，隨後透過 SQL 查詢這些資料，或將其用於您的商業智慧與分析工具。

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

開始之前

了解需求

• 您的 PostgreSQL 或 MySQL 資料庫必須可從您帳戶所在區域的 HubSpot IP 範圍存取。
• 您的資料庫伺服器必須支援 SSL 連線。
• 您必須擁有具備以下必要權限的資料庫使用者：
  • PostgreSQL：具備CREATE權限，並對目標模式擁有寫入權限。
  • MySQL：資料庫的CREATE權限及寫入權限。
• 請確保您的資料庫使用者能夠建立資料表並寫入資料。
• 請將您的 HubSpot 帳戶和資料庫控制台分別開啟在不同的分頁中。

允許 HubSpot IP 位址

將您帳戶所在區域的 HubSpot IP 範圍加入資料庫伺服器的允許清單中。

了解限制與注意事項

• 每次同步執行都會建立所選資料的完整快照。
• 同步成功後，將在目標資料表中覆寫先前的快照。
• HubSpot 不會保留先前的快照。
• 若某張資料表在同步過程中發生錯誤，其先前資料將持續可用，直至下次同步成功為止。
• 每個物件類型、事件類型或關聯對，每個帳戶可包含於一次定期的 PostgreSQL 同步作業及一次定期的 MySQL 同步作業中。
• 每次同步都會替換目標資料表。在您的資料庫供應商中新增的資料表層級授權或設定，在同步之間不會被保留。
• 若您使用不同的資料庫使用者重新連線，必須授予該使用者存取現有由 HubSpot 管理的資料結構、資料庫或資料表的權限。

將 HubSpot 連接到 PostgreSQL 或 MySQL

1. 在你的 HubSpot 帳戶中，點擊「更多」，然後前往「資料管理」 > 「Data Studio」。如果你的帳戶中沒有顯示「更多」，請直接前往「資料管理」 > 「Data Studio」。
2. 在右上角，點擊「連接外部資料來源」。
3. 在「新增資料來源」面板中，搜尋或瀏覽至資料庫供應商。
4. 點擊「PostgreSQL」或「MySQL」。
5. 輸入資料庫連線詳細資訊：
   • 主機
   • 埠
   • SSL
   • 使用者名稱
   • 密碼
6. 對於 PostgreSQL，請輸入 HubSpot 應建立資料庫結構的資料庫名稱。
7. 點擊「連線至 PostgreSQL」或「連線至 MySQL」。

HubSpot 會使用已連線的資料庫使用者來建立資料表，並將資料載入您的資料庫中。

設定同步

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

在測試版期間，可用的同步頻率可能會有所不同。選項可能包括「一次」、「每 6 小時」、「每 12 小時」、「每日」、「每週」或「每月」。

存取您的匯出資料

HubSpot 會為每個目標位置建立一個由 HubSpot 管理的資料結構或資料庫。

PostgreSQL

PostgreSQL 資料表採用以下格式：

<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"

MySQL

MySQL 資料表採用以下格式：

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

例如：

hubspot_data_out_456.OBJECT_WITH_OBJECT_PROPERTIES
hubspot_data_out_456.EVENTS_VISITED_PAGE
hubspot_data_out_456.ASSOCIATIONS_CONTACTS_TO_COMPANIES

您可以在同步設定頁面中找到確切的資料結構或資料庫名稱。

表名與欄位名

資料表與欄位名稱是根據匯出的資料所決定。PostgreSQL 識別符最多可包含 63 個字元，MySQL 識別符最多可包含 64 個字元。若名稱超過此限制，系統會自動縮短以符合相應的限制。

HubSpot 建立的 PostgreSQL 資料表與欄位名稱會加上引號，並保留大小寫。查詢 PostgreSQL 時，請使用雙引號，並與資料表名稱及欄位名稱中顯示的大小寫一致。

對於 MySQL，請使用反引號，並與顯示的大寫小寫格式保持一致。表名是否區分大小寫可能因您的 MySQL 伺服器設定而異。

欄位類型

PROPERTIES表中的OBJECT_WITH_OBJECT_PROPERTIES欄位以 JSON 格式的字串儲存。它在 PostgreSQL 中以TEXT型別儲存，在 MySQL 中以LONGTEXT型別儲存，而非原生的 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 帳戶中，點擊「更多」，然後前往「資料管理」 > 「資料整合」。如果你的帳戶中沒有顯示「更多」，請直接前往「資料管理」 > 「資料整合」。
2. 在左側，點擊「應用程式同步」。
3. 搜尋或選取 PostgreSQL 或 MySQL 同步。

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

同步狀態

解決同步失敗問題

當同步失敗時：

• HubSpot 使用者介面會顯示「失敗」狀態，並提供資料表層級的詳細資訊，說明哪些資料表同步成功或失敗。
• 只有在 HubSpot 完成載入該資料表的所有資料後，該資料表才會被更新。
• 若某個資料表同步失敗，其先前資料將保留原位，直至下次同步成功為止。
• 下次排定的同步會自動再次嘗試進行完整同步。
• 您可以從同步詳細資訊頁面手動執行同步。

若先前執行時已同步成功的資料表，在後續執行失敗時將不會被修改。

常見問題

如何查詢已匯出的資料？

請使用 SQL 查詢目標模式或資料庫中的資料表。

PostgreSQL

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

-- Read a property from the PROPERTIES column
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

-- Read all contact records
SELECT *
FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES`
WHERE `OBJECTTYPEID` = '0-1';

-- Read a property from the PROPERTIES column
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 會保留之前的快照嗎？

不會。每次同步成功後，系統都會以最新的快照取代目標資料表。HubSpot 不會保留先前的快照。

若某張資料表在同步過程中發生錯誤，其先前資料將保留原位，直至該資料表成功更新為止。

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

不會。HubSpot 會將資料以 Parquet 格式匯出，並在內部管理暫存區。您無需為 PostgreSQL 或 MySQL 提供由客戶擁有的暫存區。

如果我變更資料庫使用者會發生什麼情況？

若您使用不同的資料庫使用者重新連線，必須授予新使用者存取 HubSpot 現有管理之模式、資料庫或資料表的權限。