OpenCore文档与知识连接器

Salesforce

以 Markdown 格式查看

索引内容

Salesforce 连接器会为每条已配置的父记录创建一个可搜索文档。文档以该记录的可查询字段开始，并可把直接子记录作为额外的带链接章节。

行为索引效果
默认范围在简单模式中，请求对象列表为空时默认使用 Account。否则，每个单数形式的对象名称都会被视为父类型。
简单模式OpenCore 会请求父类型的全部可查询字段，并发现受支持的直接子关系。Base64、blob、encrypted-string、黑名单及不可查询数据会被排除。
高级模式一个 JSON 对象定义父字段和直接 associations。OpenCore 仍会添加 Id、LastModifiedDate，以及该日期字段可查询时的 CreatedDate。
子记录限制附件会被跳过。标准管理后台索引在首次与后续索引都会使用增量轮询，并且每个直接子关系查询都使用 LIMIT 10。管理后台流程没有能绕过此限制的完整重建入口。

记录字段会转换为可搜索的键值文本。父记录的 Name 会作为语义标识符；没有名称时使用 Id。记录与子记录链接会指向已认证的 Salesforce 实例。

前置条件

  • 创建专用 Salesforce 集成用户，使其可以通过 API 登录，并读取范围内的全部父对象、字段与直接子关系。
  • 允许 REST describe/query 与 Bulk API 2.0 query/export 访问。
  • 获取集成用户的用户名、密码与 security token。
  • 确定凭据指向生产环境还是 Salesforce sandbox。
  • 使用高级模式时，确认父对象、字段、子对象类型与关系准确且区分大小写的 API 名称。
  • 使用自动同步权限时，确保搜索用户的 OpenCore 邮箱与活动 Salesforce Username 或 Email 匹配，并允许查询 User 与 UserRecordAccess。

凭据

环境OpenCore 凭据值认证行为
生产环境sf_username: <SALESFORCE_USERNAME>、sf_password: <SALESFORCE_PASSWORD>、sf_security_token: <SALESFORCE_SECURITY_TOKEN>、is_sandbox: false使用 Salesforce 用户名、密码与 token 对默认生产登录域进行认证。
Sandboxsf_username: <SALESFORCE_USERNAME>、sf_password: <SALESFORCE_PASSWORD>、sf_security_token: <SALESFORCE_SECURITY_TOKEN>、is_sandbox: true使用相同凭据字段，但为摄取选择 Salesforce 测试登录域。

当前管理后台凭据不接收 Salesforce OAuth client ID、client secret、refresh token 或实例 URL。不要用这些值替代用户名、密码与 security token 字段。

在 OpenCore 中配置

  1. 在管理后台打开连接器，选择 Salesforce，并创建生产环境或 sandbox 凭据。
  2. 在配置类型中选择简单或高级。
  3. 对于简单模式，输入零个或多个单数形式的 Salesforce 对象 API 名称。仅在确实要把 Account 作为父类型时留空。
  4. 对于高级模式，输入一个以父对象类型为顶层键的 JSON 对象。用 fields 定义父字段，用 associations 把直接子对象类型映射到其字段。这是配置 JSON，不是任意 SOQL 查询。
  5. 选择文档访问模式。仅在使用代表性用户和记录验证查询时行为后，才启用自动同步权限。
  6. 设置刷新与清理选项，创建连接器并运行首次索引。

标准管理后台流程创建轮询连接器，runner 会先选择 poll_source，不会进入 load 路径。因此首次与后续索引都会使用增量轮询；即使有效轮询起点是 Unix epoch 0，也不会调用 Salesforce 独立的完整加载实现。未设置索引开始日期时，首次有效轮询起点是 epoch 0；设置后，该日期会在共享调度器应用当前 30 分钟重叠后限制首次窗口。应把有效轮询起点视为历史覆盖边界，而不是假定存在完整导出。

权限

摄取凭据决定 OpenCore 可以读取哪些 Salesforce 记录与字段。未使用自动同步权限时，Salesforce 记录访问不会同步；搜索访问只由连接器的 OpenCore 私有群组或公开模式控制。

选择自动同步权限且权限功能可用时，OpenCore 会在查询时裁剪内容，而不是存储静态记录 ACL。它先用搜索者邮箱匹配活动 Salesforce Username，再匹配 Email，然后针对每个结果来源链接表示的记录 ID 查询 UserRecordAccess.HasReadAccess。用户不可读的 Salesforce 记录对应内容章节会被移除；无法映射用户或权限检查失败时，该检查不会返回任何 Salesforce chunk。

当前行为还有额外范围约束。如果租户内任意 Salesforce 连接器启用了自动同步，则该租户的所有 Salesforce 结果 chunk 都会进入裁剪流程，包括另一个未选择自动同步的 Salesforce 连接器所产生的 chunk。权限 client 会按租户从一个关联连接器凭据建立并缓存，且不会传递摄取凭据的 sandbox-domain 设置。每个记录访问查询最多只检查前 200 个记录 ID；省略的 ID 会失败关闭。使用 sandbox、多个 Salesforce 组织或多个凭据的部署必须显式验证每种组合。

验证

  1. 验证连接器，并确认 Salesforce 全局 describe 请求成功。
  2. 运行首次同步，搜索一个已配置父记录和一个预期直接子记录值。设置索引开始日期时，还要检查有效窗口内的一条记录，以及明显早于配置日期和 30 分钟重叠范围的一条记录；未设置时，检查一条预期的较早记录。
  3. 确认未请求的父类型不存在。在高级模式中，还要确认已省略字段与关联不存在。
  4. 在首次运行和之后一次刷新中都检查一个拥有十条以上直接子记录的父记录。两个版本中每个直接关系都不应出现超过十条子记录。
  5. 使用已获 Salesforce 授权的浏览器会话打开父记录与子记录引用链接。
  6. 使用自动同步权限时，测试已映射活动用户、无记录读取权限的用户、无法匹配活动 Salesforce 用户的邮箱、每个 Salesforce 组织/凭据，以及自身未启用自动同步的连接器。

故障排除

症状检查项
登录失败检查用户名、密码、security token 与是否为 Sandbox 环境设置。连接器不使用 OAuth 凭据。
验证成功但索引失败验证只检查已认证的全局 describe 与 JSON 结构。确认每个已配置对象、字段与子关联真实存在且可查询。
空的简单配置索引了非预期数据空的简单范围表示 Account。需要其他范围时，请输入明确的单数形式对象 API 名称。
高级配置被拒绝确保每个顶层值都是对象，fields 是字符串列表，且 associations 把子对象名称映射到字符串列表。
子类型被拒绝确认它是该父对象的直接、可查询、未列入黑名单的关系，并确认父子方向正确。
附件或二进制文本缺失这是预期行为。附件、base64、blob 与 encrypted-string 字段会被排除。
父记录只包含部分子记录标准管理后台流程始终使用增量子查询，因此首次运行与后续刷新中，每个直接关系都最多返回十条记录。如果每条子记录都必须可搜索，请在简单或高级模式中把该子对象类型配置为顶层父对象，让每条子记录形成独立文档，再验证代表性子记录。这不会让父文档包含十条以上子记录。
轮询重新处理的数据超出预期OpenCore 使用 LastModifiedDate，再回退到 CreatedDate；两者都不可查询时不会按时间过滤该类型。时间边界由 OpenCore 添加。
自动同步隐藏了所有 Salesforce 结果确认 OpenCore 邮箱能映射到活动 Salesforce 用户名或邮箱，并且权限凭据可以查询 UserRecordAccess。权限错误会对 Salesforce chunk 失败关闭。
Sandbox 或多连接器下自动同步行为异常查询时 client 不会携带摄取凭据的 sandbox-domain 设置。一个已启用的 Salesforce 自动同步源会触发租户内全部 Salesforce chunk 的裁剪，每个租户只缓存一个凭据支持的 client，且每次访问查询最多检查 200 个记录 ID。请测试每个环境、组织与凭据，或改用明确的 OpenCore 私有群组。

相关页面