精通 Salesforce 与 Heroku Connect 集成：工程师指南

十一月 29, 2025

背景与应用场景

作为一名 Salesforce 集成工程师，我的核心职责是确保 Salesforce 与外部系统之间数据流畅、可靠地交换。在众多集成工具和平台中，Heroku 作为一个强大的 PaaS (Platform as a Service, 平台即服务)，为我们提供了无与伦比的灵活性和扩展性。Heroku 由 Salesforce 公司拥有，这使得它与 Salesforce 生态系统的集成尤为紧密和高效，其中最核心的工具便是 Heroku Connect。

为什么我们需要在 Salesforce 之外使用 Heroku？应用场景多种多样：

1. 构建高性能客户体验应用

假设我们需要开发一个面向数百万用户的客户门户网站或移动应用。直接将高并发流量引向 Salesforce 可能会迅速耗尽 API 调用限制，并可能影响 Salesforce 核心 CRM 业务的性能。通过 Heroku Connect，我们可以将相关的 Salesforce 数据（如客户、订单、产品信息）近乎实时地同步到 Heroku 平台上的高性能 Heroku Postgres (Heroku PostgreSQL 数据库) 中。然后，我们可以在 Heroku 上使用任何现代技术栈（如 Node.js, Python, Java）构建应用，直接读写 Postgres 数据库，从而为用户提供低延迟、高可用的体验，同时将对 Salesforce API 的冲击降至最低。

2. 数据密集型计算与处理

Salesforce 的 Apex 和其他计算资源在处理大规模数据和复杂算法时存在治理限制 (Governor Limits)。对于需要进行复杂数据分析、机器学习模型训练、或长时间运行的批量处理任务，我们可以将数据从 Salesforce 同步到 Heroku。在 Heroku 强大的计算实例（称为 Dynos, 动态容器）上，我们可以利用丰富的开源库和框架自由地处理数据，并将计算结果通过 Heroku Connect 写回到 Salesforce 的相应字段中。

3. 数据仓库与备份

虽然 Salesforce 提供了数据备份方案，但 Heroku Connect 提供了一种更灵活、可查询的数据归档和备份方式。通过设置单向同步，我们可以持续地将 Salesforce 的关键业务数据复制到 Heroku Postgres 数据库中。这不仅创建了一个实时的数据备份，还为数据分析师和 BI 工具提供了一个可以直接访问和查询的数据源，而无需直接连接到生产环境的 Salesforce 组织。

4. 多系统集成枢纽

当 Salesforce 需要与多个遗留系统或第三方服务集成时，Heroku 可以扮演一个强大的集成中间件角色。Heroku Connect 负责处理与 Salesforce 的数据同步，而在 Heroku 上运行的应用程序则可以处理与其他系统 API 的连接、数据转换和业务流程编排。这种架构模式将复杂的集成逻辑从 Salesforce 中解耦，使其更易于维护和扩展。

原理说明

Heroku Connect 的核心是一个数据同步服务，它在 Salesforce 对象和 Heroku Postgres 数据库表之间建立了一座双向的桥梁。其工作原理可以分解为以下几个关键步骤：

1. 认证与连接

首先，你需要通过 OAuth 2.0 协议授权 Heroku Connect 访问你的 Salesforce 组织。这一步至关重要，因为 Heroku Connect 将使用一个指定的 Salesforce 用户账户来执行所有的 API 操作。因此，该用户的权限（对象权限、字段级安全、共享规则）直接决定了 Heroku Connect 能够读写哪些数据。

2. 映射 (Mapping)

连接建立后，核心工作就是创建映射。一个映射定义了 Salesforce 中的一个标准对象或自定义对象与 Heroku Postgres 数据库中的一张表之间的对应关系。在这个过程中，你需要选择：

同步方向：可以是双向 (bi-directional)，从 Salesforce 到 Postgres，或者从 Postgres 到 Salesforce。
要同步的字段：你可以精确选择需要同步的字段，避免不必要的数据传输。Salesforce 对象的字段会自动映射为 Postgres 表的列。
轮询频率 (Polling Frequency)：Heroku Connect 通过轮询机制来检查 Salesforce 中的数据变更。你可以根据业务需求设置轮询频率，最短可达2分钟。

3. 初始加载与持续同步

创建并激活一个映射后，Heroku Connect 会首先执行一次全量数据加载，将 Salesforce 对象中所有符合条件的记录复制到对应的 Postgres 表中。此后，它会根据设定的轮询频率，使用 Salesforce SOAP API 或 Bulk API 来增量获取变更数据（新建、更新、删除的记录），并将其应用到 Postgres 数据库中。

4. 数据写回 Salesforce

对于双向同步或从 Postgres 到 Salesforce 的单向同步，当 Postgres 表中的数据发生变化时，Heroku Connect 会检测到这些变更。它会将这些变更聚合起来，通过 Salesforce REST API 或 Bulk API 将数据写回到 Salesforce。为了确保数据的一致性和避免重复，Heroku Connect 强烈推荐使用 External ID (外部 ID) 字段进行 upsert 操作。当你在 Postgres 中插入一条新记录时，Heroku Connect 会先尝试根据 External ID 找到 Salesforce 中匹配的记录进行更新，如果找不到，则创建一条新记录。

5. 错误处理与日志

在同步过程中，任何错误（如 Salesforce 验证规则失败、触发器异常、API 调用失败等）都会被 Heroku Connect 捕获，并显示在其仪表盘上。你可以查看具体的错误信息和关联的记录 ID，从而快速定位并解决问题。

示例代码

Heroku Connect 本身是一个配置驱动的服务，其核心操作在于创建和管理映射，而非编写代码。然而，其真正的威力在于我们如何利用同步到 Heroku Postgres 的数据。以下是一个简单的 Node.js Express 应用程序示例，它运行在 Heroku 上，查询由 Heroku Connect 从 Salesforce 同步过来的 `Account` (客户) 数据。

这个示例假设你已经通过 Heroku Connect 将 Salesforce 的 `Account` 对象映射到了 Heroku Postgres 的 `salesforce.account` 表。

详细注释：

1. 项目设置

首先，确保你的 Node.js 项目中已经安装了 `express` 和 `pg` (Node.js PostgreSQL 客户端)。

2. 连接数据库

Heroku 会通过环境变量 `DATABASE_URL` 提供数据库连接字符串。我们的代码需要读取这个变量来建立连接。

3. 查询数据

我们创建一个简单的 API 端点 `/api/accounts`，当访问该端点时，它会执行一条 SQL 查询，从 `salesforce.account` 表中选择前 10 条记录的 `name` 和 `industry` 字段，并以 JSON 格式返回。

// 引入所需的库
const express = require('express');
const { Pool } = require('pg');
const app = express();
const PORT = process.env.PORT || 3000;

// Heroku Connect 会自动将 Salesforce 数据库连接信息注入到环境变量 DATABASE_URL 中。
// pg 库能够自动解析这个 URL，包括 user, password, host, port 和 database。
// 我们还为 Heroku 环境配置了 SSL，这是生产环境的最佳实践。
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: {
    rejectUnauthorized: false
  }
});

// 创建一个 API 端点来获取客户数据
app.get('/api/accounts', async (req, res) => {
  try {
    // 从连接池获取一个客户端连接
    const client = await pool.connect();
    
    // 执行 SQL 查询。
    // 'salesforce.account' 是 Heroku Connect 创建表的默认模式（schema）和表名。
    // 我们只选择 name 和 industry 两个字段，并限制返回10条记录作为示例。
    const result = await client.query('SELECT name, industry FROM salesforce.account LIMIT 10;');
    
    // 将查询结果以 JSON 格式返回给前端
    res.json(result.rows);
    
    // 将客户端连接释放回连接池
    client.release();
  } catch (err) {
    // 如果发生任何数据库错误，记录错误并返回 500 服务器错误状态码
    console.error(err);
    res.status(500).send("Error " + err);
  }
});

// 启动 Express 服务器并监听指定的端口
app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

*代码来源说明：* 此示例代码结构和数据库连接方式是基于 Salesforce 开发者文档和 Heroku Dev Center 中关于使用 Node.js 连接 Heroku Postgres 的标准实践。例如，在 "Build a Full-Stack App with LWC and Heroku" 示例项目中，可以看到类似的数据访问模式。

注意事项

作为集成工程师，部署和维护 Heroku Connect 时必须考虑以下关键点：

1. 权限与安全

专用集成用户：始终为 Heroku Connect 创建一个专用的 Salesforce 集成用户。不要使用系统管理员账户。
最小权限原则：为该集成用户分配一个专门的权限集，只授予其对需要同步的对象和字段的读/写访问权限。这可以防止意外的数据修改，并增强系统的安全性。
字段级安全 (Field-Level Security)：确保集成用户对所有需要同步的字段都具有可见性，否则同步会失败。

2. API 限制

API 调用消耗：Heroku Connect 会消耗 Salesforce 的 API 调用配额。它会智能地选择使用 SOAP API 进行小批量轮询，或使用 Bulk API 进行大规模数据加载和写入。
监控消耗：你必须在 Salesforce 的“公司信息”页面和 Heroku Connect 仪表盘中密切监控 API 调用消耗情况，确保不会影响其他关键业务集成。对于大型数据集，建议调整轮询频率以降低 API 调用频率。

3. 数据一致性与错误处理

External ID 的重要性：在进行双向同步或从 Heroku 写回 Salesforce 时，务必在 Salesforce 对象上创建一个“外部 ID”字段，并在 Heroku Connect 映射中指定它。这能确保数据更新的幂等性，避免创建重复记录。
处理同步错误：定期检查 Heroku Connect 仪表盘中的“Explorer”视图，查看是否有同步失败的记录。常见的失败原因包括触发器执行错误、验证规则失败或必填字段为空。你需要与 Salesforce 管理员或开发人员合作解决这些底层问题，然后从仪表盘上重试失败的记录。

4. 数据量与性能

同步范围：只同步业务上绝对必要的对象和字段。同步整个 Salesforce 数据库不仅会消耗大量 API 调用，还会增加 Postgres 数据库的存储成本和查询延迟。
归档数据：对于不再活跃的旧数据，考虑在 Salesforce 中使用归档策略，或在 Heroku Connect 映射中添加过滤条件，以避免将其同步到 Heroku。
数据库索引：当你在 Heroku 应用中频繁查询同步过来的数据时，记得在 Heroku Postgres 表的常用查询字段上创建索引，以提升查询性能。

总结与最佳实践

对于 Salesforce 集成工程师而言，Heroku Connect 是解决复杂集成挑战的利器。它通过提供一个托管、可靠且可扩展的数据同步服务，极大地简化了 Salesforce 与外部应用之间的数据集成。它使我们能够构建出色的客户体验应用、运行复杂的数据处理任务，并维护一个可靠的数据副本，而无需从头开始编写和维护复杂的 API 集成代码。

最佳实践总结：

明确集成目标：在开始之前，清晰地定义你的集成场景是单向数据复制、双向同步还是数据处理卸载。
使用专用集成用户和最小权限原则：这是保障系统安全和可追溯性的基石。
善用 External ID：对于任何需要写回 Salesforce 的场景，External ID 都是必选项。
分阶段同步：不要一次性同步所有数据。从核心对象开始，逐步扩展，并密切监控性能和 API 消耗。
监控、监控、再监控：定期检查 Heroku Connect 仪表盘的健康状态、API 使用情况和同步错误，主动发现并解决问题。
结合 Heroku 生态：将 Heroku Connect 与 Heroku 平台上的其他 Add-ons (附加组件)（如 Kafka, Redis）结合使用，可以构建出更加强大和复杂的实时数据处理架构。

通过遵循这些原则和实践，你可以充分利用 Heroku Connect 的强大功能，为你的企业构建出稳定、高效且可扩展的 Salesforce 集成解决方案。

Salesforce中文网