将 HubSpot 数据导出到 Microsoft Fabric
上次更新时间： 2026年10月26日
请注意：如果您是超级管理员，请将您的账户加入Data Studio 测试版，才能使用此功能。
某些功能需要 HubSpot 点数 从 Data Studio 中的单个仓库源将数据直接同步到 HubSpot CRM 不会消耗HubSpot 积分。如果您在同步前在 Data Studio 中对数据进行预处理（例如，创建计算字段或与其他数据源进行关联），这些操作会消耗 HubSpot 积分。
使用“数据导出”功能，将选定的 HubSpot CRM 数据导出到您拥有的 Microsoft Fabric 数据仓库中的原生表中。您可以将对象、关联和事件数据同步到数据仓库中的表中，然后使用 SQL 查询这些数据，或将其与您的商业智能和分析工具结合使用。
每次同步都会生成所选数据的完整快照。同步成功后，目标表中的先前快照将被替换。
开始之前
了解要求
要将数据导出到 Microsoft Fabric，您需要：
- 包含 Fabric 数据仓库的 Microsoft Fabric 工作区
- 已添加到 Fabric 工作区且具有“贡献者”角色的 Microsoft Entra ID 服务主体
- 该服务主体的租户 ID、客户端 ID 和客户端密钥
- 您的 Fabric 数据仓库 SQL 连接字符串（服务器地址，不包含端口号）和数据仓库名称
Microsoft Entra ID 服务主体必须具备在目标 Fabric 数据仓库中创建和管理 HubSpot 所属对象的权限。在连接验证和同步过程中，HubSpot 会创建架构和表、插入数据、重命名暂存表并删除临时对象。请在 Fabric 工作区中向该服务主体授予“贡献者”角色，以允许 HubSpot：
- 创建模式
- 创建表
- 插入行
- 重命名或修改 HubSpot 拥有的表
- 删除 HubSpot 拥有的表和模式
您的 Fabric Warehouse SQL 端点必须可通过 TCP 端口 1433 被 HubSpot 访问。HubSpot 针对所有连接均使用 TLS 并验证服务器证书。
如果您的 Fabric 工作区限制了网络访问，请将您账户所在区域的 HubSpot 出站 IP 地址添加到白名单中。
| 区域 | IP 范围 |
|---|---|
| NA1 | 54.174.62.128/26 |
| EU1 | 143.244.87.0/25 |
| AP1 | 216.157.42.32/27 |
| NA2 | 216.157.40.32/27 |
| NA3 | 216.157.41.32/27 |
了解限制和注意事项
- Microsoft Fabric Data Out 仅支持 Fabric 数据仓库。不支持 Lakehouse。
- 每次同步运行都会生成所选数据的完整快照。同步成功后，目标表中的先前快照将被替换。HubSpot 不保留先前的快照。如果表在同步过程中失败，其先前数据将一直可用，直到下次同步成功为止。
- 每个对象类型、事件类型或关联对，每个账户仅可包含在一次 Microsoft Fabric 定期同步中。
- 每次同步都会覆盖目标表。在 Fabric 数据仓库中添加的表级授权或设置在两次同步之间不会被保留。
- 若要重新连接到另一个服务主体，必须先将该服务主体以“贡献者”角色添加到 Fabric 工作区，连接测试或同步操作才能成功。
将 HubSpot 连接到 Microsoft Fabric
建议在不同的标签页中分别打开您的 HubSpot 账户和 Microsoft Fabric 控制台。
- 在你的 HubSpot 帐户中，单击更多，然后导航到数据管理 > Data Studio。如果你的帐户中未显示更多，请直接导航到数据管理 > Data Studio。
- 在右上角，单击“连接外部数据源”。
- 在“添加数据源”面板中，搜索或浏览至Microsoft Fabric。
- 单击“安装”，然后单击“下一步”。
- 输入您的服务主体的租户 ID、客户端 ID 和客户端密钥。
- 输入以下目标详细信息：
- SQL 连接字符串：您的 Fabric Warehouse 的服务器地址，不包含端口号。
- 仓库名称：要导出的 Fabric 仓库的名称。
- 单击“测试连接”。如果连接测试成功，请单击“下一步”。
请注意：在您的 Fabric 工作区中，请在运行连接测试前确认 HubSpot 服务主体具有“贡献者”角色。配置访问权限无需任何 SQL 脚本。
配置同步
- 选择要导出的数据源：
- 对象
- 关联
- 事件
- 选择要包含的对象、属性、关联或事件。
- 选择同步的频率以及开始时间。
- 点击“开始同步”。
在测试版期间，可用的同步频率可能会有所不同。选项包括：一次、每 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 个字符的名称将被缩短。
- 发生冲突的列名会添加后缀。
- 发生冲突的表名会导致受影响的导出失败。
列类型
| 导出类型 | 结构类型 |
|---|---|
| 字符串 | VARCHAR(MAX) |
| 数字（32 位） | INT |
| 数字（64 位） | BIGINT |
| 时间戳 | DATETIME2(6) |
| 布尔值 | BIT |
| 十进制 | DECIMAL(精度, 小数位数) |
| 浮点数 | REAL |
| 双精度 | FLOAT |
| 日期 | DATE |
| 时间 | TIME(6) |
在PROPERTIES表中，OBJECT_WITH_OBJECT_PROPERTIES列以 JSON 格式的字符串存储在VARCHAR(MAX) 字段中，而非原生 JSON 列类型。请参阅下文常见问题解答中的查询示例。
对象表
如果您选择了对象数据，HubSpot 将导出以下表。
OBJECT_PROPERTIES
该表中，每个对象属性值对应一行。
| 列 | 类型 | 描述 |
|---|---|---|
OBJECTTYPEID |
字符串 | 对象类型的ID。例如，联系人使用0-1。 |
OBJECTID |
数字 | 记录的 ID。 |
NAME |
字符串 | 属性名称。 |
VALUE |
字符串 | 属性值。 |
UPDATEDAT |
时间戳 | 该属性值在 HubSpot 中最后一次更新的日期和时间。 |
INGESTEDAT |
时间戳 | 数据最后一次导入到导出源的日期和时间。 |
OBJECT_WITH_OBJECT_PROPERTIES
该表中，每个对象记录对应一行。所选属性值在PROPERTIES”列中进行分组。
| 专栏 | 类型 | 描述 |
|---|---|---|
OBJECTTYPEID |
字符串 | 对象类型的ID。例如，联系人使用0-1。 |
OBJECTID |
数字 | 记录的ID。 |
PROPERTIES |
文本（JSON） | 该记录的选定属性值，以 JSON 格式的字符串形式存储。 |
UPDATEDAT |
时间戳 | 该记录中选定属性在 HubSpot 中最后一次更新的日期和时间。 |
INGESTEDAT |
时间戳 | 数据最后一次导入到导出源的日期和时间。 |
不同对象类型的对象数据在此表中合并。请按OBJECTTYPEID筛选，以读取特定对象类型的记录：
- 联系人：0-1
- 自定义对象：2-{unique_id}，例如 2-12345
OBJECT_PROPERTIES_HISTORY
该表包含属性变更历史记录。其中，每个属性的历史值对应一行。
| 列 | 类型 | 描述 |
|---|---|---|
OBJECTTYPEID |
字符串 | 对象类型的 ID。 |
OBJECTID |
数字 | 记录的 ID。 |
NAME |
字符串 | 属性名称。 |
VALUE |
字符串 | 该时间点上的属性值。 |
UPDATEDAT |
时间戳 | 该值在 HubSpot 中被设置的日期和时间。 |
INGESTEDAT |
时间戳 | 数据最后一次导入到导出源的日期和时间。 |
要查看特定记录和属性的完整历史记录，请按UPDATEDAT 对结果进行排序。
关联表
若选择关联数据，HubSpot 将导出关联记录和关联定义。
ASSOCIATIONS
此表中，两个记录之间的每条已选关联对应一行。
| 列 | 类型 | 描述 |
|---|---|---|
COMBINEDASSOCIATIONTYPEID |
字符串 | 关联定义的唯一标识符。 |
ASSOCIATIONCATEGORY |
字符串 | 关联类型的来源。取值可包括HUBSPOT_DEFINED、USER_DEFINED 或INTEGRATOR_DEFINED。 |
ASSOCIATIONTYPEID |
数字 | 该关联定义在其所属类别中的标识符。 |
FROMOBJECTID |
数字 | 源记录的 ID。 |
TOOBJECTID |
数字 | 目标记录的 ID。 |
INGESTEDAT |
时间戳 | 数据最后一次导入到导出源的日期和时间。 |
ASSOCIATION_DEFINITIONS
此表中，每条选定的关联定义对应一行。
| 列 | 类型 | 描述 |
|---|---|---|
COMBINEDASSOCIATIONTYPEID |
字符串 | 关联定义的唯一标识符。 |
CATEGORY |
字符串 | 关联类型的来源。取值包括HUBSPOT_DEFINED、USER_DEFINED 或INTEGRATOR_DEFINED。 |
ID |
数字 | 该关联定义在其所属类别中的标识符。 |
FROMOBJECTTYPEID |
字符串 | 源对象类型的ID。 |
TOOBJECTTYPEID |
字符串 | 目标对象类型的 ID。 |
NAME |
字符串 | 关联定义的名称。 |
LABEL |
字符串 | 关联定义的标签。 |
INGESTEDAT |
时间戳 | 数据最后一次导入到导出源的日期和时间。 |
ISMAINASSOCIATIONDEFINITION |
布尔值 | HubSpot 是否将此关联定义显示为关联记录上的主关联。 |
特定关联对的关联表
对于选定的关联对，HubSpot 还可以导出以下格式的表格：
ASSOCIATIONS_<FROM_OBJECT_TYPE>_TO_<TO_OBJECT_TYPE>例如：ASSOCIATIONS_CONTACTS_TO_COMPANIES
这些表格包含关联记录和关联定义元数据。
| 列 | 类型 | 描述 |
|---|---|---|
COMBINEDASSOCIATIONTYPEID |
字符串 | 关联定义的唯一标识符。 |
ASSOCIATIONCATEGORY |
字符串 | 关联类型的来源。取值可包括HUBSPOT_DEFINED、USER_DEFINED 或INTEGRATOR_DEFINED。 |
ASSOCIATIONTYPEID |
数字 | 该关联定义在其所属类别中的标识符。 |
[FROMOBJECTTYPE]_OBJECTID |
数字 | 源记录的 ID。例如，CONTACT_OBJECTID。 |
[TOOBJECTTYPE]_OBJECTID |
数字 | 目标记录的 ID。例如，COMPANY_OBJECTID。 |
INGESTEDAT |
时间戳 | 数据最后一次导入到导出源的日期和时间。 |
TOOBJECTTYPEID |
字符串 | 目标对象类型的 ID。 |
FROMOBJECTTYPEID |
字符串 | 源对象类型的 ID。 |
NAME |
字符串 | 关联定义的名称。 |
LABEL |
字符串 | 关联定义的标签。 |
ISMAINASSOCIATIONDEFINITION |
布尔值 | HubSpot 是否将此关联定义显示为关联记录上的主关联。 |
事件表
如果您选择事件数据，HubSpot 会为每种事件类型导出一个表格。事件表格名称采用以下格式：
EVENTS_<EVENT_NAME>例如：EVENTS_VISITED_PAGE
每个事件表包含标准事件列以及针对每个所选事件属性的一个列。
| 列 | 类型 | 描述 |
|---|---|---|
EVENTTYPEID |
字符串 | 事件类型的 ID。 |
ID |
字符串 | 唯一的事件 ID。 |
OBJECTTYPEID |
字符串 | 与该事件关联的对象类型的 ID。 |
OBJECTID |
数字 | 与该事件关联的记录的 ID。 |
INGESTEDAT |
时间戳 | 事件被导入到导出源的日期和时间。 |
OCCURREDATDATEINT |
数字 | 事件日期，以 YYYYMMDD 格式的整数表示。 |
OCCURREDAT |
时间戳 | 事件发生的日期和时间。 |
PROPERTY_<PROPERTY_NAME> |
字符串 | 所选的事件属性。例如，名为 page_title 的属性将导出为 PROPERTY_PAGE_TITLE。 |
监控同步情况
- 在你的 HubSpot 帐户中，单击更多，然后导航到数据管理 > Data Studio。如果你的帐户中未显示更多，请直接导航到数据管理 > Data Studio。
- 在左侧，点击“应用同步”。
- 搜索或选择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 工作区中。
