将 HubSpot 数据导出到 PostgreSQL 或 MySQL

请注意：如果您是超级管理员，请将您的账户加入Data Studio 测试版，以便使用此功能。

概述

使用“数据导出”功能，将选定的 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进行筛选，以检索特定对象类型的记录。

是否支持敏感数据？

Data Out 目前不支持敏感数据。导出时可将敏感属性排除在外。

HubSpot 会保留之前的快照吗？

不。每次同步成功后，目标表都会被最新的快照替换。HubSpot 不保留之前的快照。

如果某张表在同步过程中失败，其先前数据将保留原位，直到该表成功更新为止。

HubSpot 是否使用我管理的暂存存储桶？

不会。HubSpot 会将数据导出为 Parquet 格式，并在内部管理暂存桶。您无需为 PostgreSQL 或 MySQL 提供客户自有的暂存桶。

如果我更改了数据库用户会怎样？

如果您使用其他数据库用户重新连接，必须授予新用户访问现有 HubSpot 管理的模式、数据库或表的权限。