Salesforce:查询对象
通过 Salesforce 的 Bulk API 2.0 将一个 Salesforce 对象(标准对象或自定义对象)读入项目表。选择 Salesforce 连接、对象和字段后,步骤会构建查询、对整个结果集分页,并将每一列加载为 Salesforce 为其声明的类型。无需编写查询。
Salesforce 通过其 REST API 直接连接云端,因此此步骤不需要 PlaidLink 代理。
| 字段 | 必填 | 说明 |
|---|---|---|
| Salesforce 连接 | 是 | 用于读取的 Salesforce 连接。连接在 Tools > Connections 中管理。 |
| 环境 | 否 | 要读取连接的哪个环境:让沙盒环境指向沙盒组织,让生产环境指向生产组织。项目环境(默认)使用项目的连接环境。固定环境始终使用您选择的环境。请参阅将步骤固定到单一环境。 |
| 对象 | 是 | 对象的 API 名称,例如 Account、Opportunity、Invoice__c。选择器列出连接的 Run As 用户可以查询的对象,也接受手动输入的名称,因此在发现功能不可用时,已保存的步骤仍可继续工作。 |
| 目标表 | 是 | 行加载到的项目表。 |
| 包含已删除和已归档的记录 | 否 | 同时读取回收站中的记录和已归档的活动,与 Salesforce 的 queryAll 相同。 |
| 字段 | 是 | 勾选要提取的字段。至少需要一个:Bulk API 2.0 会拒绝整个对象的选择,因此列列表始终是逐一枚举的。 |
| 筛选器 | 否 | 在 Salesforce 端缩小提取范围。请参阅在 Salesforce 端筛选。 |
| 窗口标记 | 否 | 为提取窗口命名。请参阅提取窗口只运行一次。 |
无论是否勾选,Id 始终会包含在内,因为它是每次重新运行时合并所依据的键。如果对象有 CurrencyIsoCode,货币字段也会一并提取它。
源选项卡上的预览最多显示步骤将读取内容的 100 行,而不运行它。筛选器中的变量与运行时的填充方式相同,但不支持 {x:>9} 之类的变量格式。在已锁定的项目中,预览不可用。如果筛选器使用了预览无法确认是只读的内容,它会提示您运行步骤。
每次运行都会读取整个对象(受您的筛选器限制),并按 Id 将每一页合并到目标表中。表中已有的行会被原位替换,因此中断后恢复的运行不会重复加载任何内容。
加载的列使用 Salesforce 在其自身字段元数据中声明的类型,而绝不是根据第一页数据猜测的类型。字段选择器中的落入列就是该声明的类型,因此您在表单中确认的形态就是表最终得到的形态。
各类型加载为什么
Section titled “各类型加载为什么”| Salesforce 字段类型 | 加载为 |
|---|---|
id、reference、string、textarea、phone、url、email、picklist、multipicklist、combobox |
文本 |
boolean |
布尔 |
date |
日期 |
datetime |
时间戳 |
time |
时间 |
int |
整数;当字段声明为 10 位或更多位数时为 64 位整数 |
double、currency、percent |
数值:宽十进制,38 位数字,其中 10 位小数 |
该表带来三条约定,在基于输出构建内容之前值得了解:
- 货币加载为数字,而不是货币类型。 实际的组织声明的货币字段小数位数为 0、2、3 和 4,因此每种数值类型都加载为一种足够宽、能容纳所有这些情况的十进制。列上没有货币符号,也没有每个字段的小数位数约束。如果对象带有
CurrencyIsoCode,该列会与货币字段一起提取,使金额保留其币种;单一货币的组织在对象上没有这样的字段,也不会凭空创建。 - 百分比就是 Salesforce 报告的整数。
20表示 20%,而不是0.2。导入过程中不会做任何缩放。 - 空值加载为 NULL。 Bulk 结果无法区分真正的 null 和显式的空字符串,因此两者都加载为
NULL,每一列都是如此,包括文本列。必须保留空字符串语义的列,需要在 Salesforce 端使用公式字段。
步骤会拒绝的字段
Section titled “步骤会拒绝的字段”某些 Salesforce 字段类型无法如实加载,因此字段选择器会将它们标记为不可用并指明原因,而不是让您保存一个在运行时失败的步骤。每次拒绝都会指明字段及其 Salesforce 类型。
| Salesforce 字段类型 | 原因 | 替代做法 |
|---|---|---|
address、location(复合字段) |
复合字段在 Bulk 查询中没有可直接读取的值。 | 勾选其组成字段:BillingStreet、BillingCity、BillingState、BillingPostalCode、BillingCountry,以及地理位置的纬度和经度。选择器会为您面前的字段指明其组成字段。 |
base64 |
文件和 blob 内容绝不会内联返回;它需要单独的二进制下载,而此步骤不执行该操作。 | 读取记录的其他字段,并单独处理附件。 |
encryptedstring |
当 Run As 用户缺少 View Encrypted Data 权限时,Salesforce 返回的是被遮蔽的值而不是错误,没有任何迹象能区分被遮蔽的数据和真实数据。悄悄加载一行行星号比拒绝更糟。 | 请审慎决定该数据是否应该离开 Salesforce;通过此步骤提取它没有受支持的方式。 |
anyType |
实际类型可能逐行不同,而表列只能有一种类型。 | 提取一个有类型的字段,或将值呈现为文本的公式字段。 |
| 步骤无法识别的任何类型 | 会被拒绝,而不是作为文本加载,因为那会悄悄改变值的含义。 | 请联系支持团队,以便为该类型添加映射。 |
提取窗口只运行一次
Section titled “提取窗口只运行一次”窗口标记为某次运行加载的数据窗口命名,例如期间或批次标签,如 2026-09。它接受工作流变量:标记 {period} 在每次运行步骤时都会解析为该变量的值。
提取窗口只运行一次。重新运行已完成的窗口不会再访问 Salesforce:步骤会明确报告它没有重新读取,并说明所显示的行数属于较早的运行。这是明确的空操作,而不是静默的空操作,也是避免重新运行时对已经加载过的结果集再次分页获取第二份副本的机制。
使用该步骤有三种方式:
- 将标记留空,把步骤当作一次性加载。第一次运行会读取;同一步骤的第二次运行会重放并报告它没有重新读取。用它来构建和验证提取,以及用于只加载一次的表。
- 输入一个标记,并在加载下一个窗口时更改它,例如
2026-09,然后是2026-10。编辑标记会开启新窗口,因此由人工逐步推进的每月加载,其工作方式与字面意思完全一致。 - 用工作流变量构建标记,用于无人值守的周期性提取,例如
{period},由工作流中较早的步骤设置为正在加载的期间。每次计划运行都会命名自己的窗口,同一期间内的重新运行会恢复或重放该窗口,而不是开启另一个窗口。
REST API 或 MCP 调用方直接传入 extract_tag,并自行为每个窗口提供不同的值。
被中断的运行会恢复同一个窗口,因此在该窗口可能仍需完成期间,请保持标记不变。更改标记会开启新窗口,并在 Salesforce 发起新的查询。更改筛选器或字段时请同时更改标记:在已运行过的标记下编辑配置,会被作为冲突拒绝。
在 Salesforce 端筛选
Section titled “在 Salesforce 端筛选”请在 Salesforce 端缩小提取范围,而不是拉取整个对象再事后筛选。每个筛选条件由字段、运算符和值组成;各条件以 AND 组合。值可以使用工作流变量,例如 {region}。
| 运算符 | 说明 |
|---|---|
=、!=、<、<=、>、>= |
与输入的值进行比较。 |
LIKE |
使用 % 作为通配符,例如 Acme%。 |
IN、NOT IN |
给出以逗号分隔的值列表。 |
在构建查询之前,字段和运算符都会与您所选的字段进行核对,并且没有可编写的自由文本 WHERE 子句,因此筛选器无法超出提取的范围。请对您也已勾选的字段进行筛选;指定了提取未选择的字段的筛选器会被拒绝。
该步骤不提供行数限制和排序。当查询带有其中任何一项时,Bulk API 2.0 会关闭其内部分块,这会使大型提取更慢,也更容易超时。选择性强的筛选条件是 Salesforce 自己对查询过大或过慢的补救办法。
数据量和变动量的适配性
Section titled “数据量和变动量的适配性”这种形态(按计划完整读取对象)适合数据量适中、变动适中的对象:客户、商机、潜在客户、营销活动,以及规模相近的自定义对象。
对于高数据量、高变动的对象,例如 Task、EmailMessage,或每天有数百万行发生变化的大型自定义对象,它并不合适。对这些对象每晚完整提取一次,会消耗增量同步不会消耗的实际耗时和 API 容量。如果对象很大但只有一部分值得关注,通过日期范围、记录类型或所有者等条件限定提取范围的筛选器,可以将其变回适中数据量的提取。
运行未完成时
Section titled “运行未完成时”| 您看到的现象 | 发生了什么 | 怎么做 |
|---|---|---|
| 错误:作业在 15 分钟后仍在运行 | 步骤在前台等待 Salesforce 完成查询,且等待有上限。后台没有任何机制推进作业。步骤会失败,因此后续步骤不会在此次提取尚未写入的表上运行。 | 恢复工作流或重新运行步骤。它会在同一个 Salesforce 作业上继续等待,绝不会提交第二个作业。如果它持续超出上限,请使用筛选条件缩小提取范围。 |
| 警告:窗口已完成,未重新读取 | 该窗口以前运行过。显示的行数是较早那次运行的。 | 使用不同的窗口标记运行提取,或推进构建标记所依据的变量,请参阅提取窗口只运行一次。 |
| 指明作业失败或已中止的错误 | 失败的 Bulk 查询作业不会产生部分结果,也无法恢复。该窗口现已用尽。 | 使用不同的窗口标记重新运行。重新运行同一个窗口会重放失败且不提交任何内容,在同一标记下编辑步骤的配置会被作为冲突拒绝。 |
| 指明 Salesforce 请求限制的拒绝 | 组织滚动 24 小时的 API 请求额度已耗尽。Salesforce 没有为此提供文档化的重试等待时间。 | 等待窗口清空后再重新运行,提取仍然可以恢复,没有任何丢失。 |
| 指明某个字段及其 Salesforce 类型的拒绝 | 该字段类型无法加载,或者 Run As 用户无法读取该字段。 | 请参阅步骤会拒绝的字段以及 Run As 用户的字段级安全性。 |
Salesforce 会将已完成的查询作业的结果保留 7 天以供检索,这正是中断的提取可以恢复的原因,同时也限定了在结果消失之前恢复最多可以等待多久。可以在 Salesforce 的 Setup > Environments > Jobs > Bulk Data Load Jobs 下查看作业。
- Salesforce 步骤
- 连接到 Salesforce:从头到尾的组织端设置
- Salesforce REST 连接器:连接字段参考
- 在工作流中运行单个步骤