测试版通过 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 不提供历史快照保留功能。刷新成功后，目标表将包含最新的快照。如果表无法更新，通常仍可访问之前成功同步的数据。