快速上手：连接 Postman 到 Salesforce

设置你的组织（01 Set Up Your Org）

在连接 Postman 之前，你的 Salesforce 组织需要先准备好。本单元你将了解 Salesforce 提供的一整套 API，创建一个全新的 Trailhead Playground，获取登录凭据，并配置跨域资源共享（CORS），让 Postman 的 Web 应用能够与你的组织通信。这些都是一次性的设置步骤，却是建立连接的先决条件。

完成本项目后，你将能够：

• 把组织准备好以使用 Postman；
• 加载 Salesforce Platform APIs for Postman 集合；
• 把 Postman 连接到你的组织；
• 用 Postman 验证连接。

为什么用 Postman 访问 Salesforce Platform API（一）：API 与 Postman（Why Use Postman... (1): APIs & Postman）

Salesforce 暴露了一整套丰富的应用程序编程接口（API），用于与第三方系统集成，而且都经过了详尽的文档化。但问题在于：你如何能快速地在某个组织上试用它们，或者更好——在多个组织上试用？Postman 正是帮助你发现、探索和测试 Salesforce Platform API 集成方案的工具。

Salesforce 提供的 API 包括：

• REST API——轻量、基于 JSON，最适合 Web 和移动应用；
• SOAP API——企业级、基于 XML，类型强、有正式契约；
• Bulk API——处理海量记录；
• Streaming API——实时事件推送；
• Metadata API——程序化配置组织；
• Connect API——社交动态与 Chatter。

Postman 是什么？它是一个用来配置和调用基于 HTTP 的 API（如 REST 或 SOAP）的应用，在易用的图形界面中完成配置。它支持环境变量、团队工作区和 JavaScript 自动化。有了它，你无需写代码就能可视化地配置请求，还能用环境变量在不同组织之间切换。如果你是 Postman 新手，可以先去它的 Learning Center 看看。

为什么用 Postman 访问 Salesforce Platform API（二）：集合与准备说明（Why Use Postman... (2): Collection & Setup Notes）

Salesforce Platform APIs for Postman 集合是你的"超能力"：它是一个把 200 多个请求模板打包在一起的资源，覆盖 REST、SOAP、Bulk、Metadata、Streaming 等几乎所有 Salesforce API。这个开源集合（在 GitHub 上由 Salesforce Developer Relations 团队维护）使用可配置的 Postman 环境与变量，让你只需认证一次，就能在所有请求上复用同一个令牌，轻松地在多个组织上试用这些请求。

开始前有几条重要说明：

• Postman 界面经常更新——你看到的界面可能与截图略有差异，按钮和标签的位置、命名可能略有不同，这没关系；
• 本项目使用 Postman 的 Web 版（postman.com），因为它无需下载安装软件；
• 务必创建一个全新的 Trailhead Playground——使用已有的组织或 Playground 会导致认证失败等问题，难以排查。

一个集合，200+ 个 API 模板，无穷的集成可能性。

创建新的 Trailhead Playground（Create a New Trailhead Playground）

这一步比看起来更重要。创建一个全新的 Trailhead Playground，能确保一个干净、无冲突的环境。操作如下：

1. 滚动到本页底部，点击 Playground 名称；
2. 点击 Create Playground；
3. 等待大约 3–4 分钟完成创建。

为什么要用全新的 Playground？

• 干净的环境，没有权限冲突；
• 所需的权限已预先配置好；
• 避免现有自定义或数据造成的干扰；
• 避免认证问题。

是的，我们真的指的是全新的 Trailhead Playground！这个项目就是针对全新的 Playground 设计和测试的。如果你使用已有的组织（哪怕是另一个 Playground），几乎一定会遇到问题。等待创建的这几分钟里，你可以先预览一下接下来的步骤。

获取 Trailhead Playground 用户名与密码（一）：查找凭据（Get Credentials (1): Find Credentials）

你需要这些凭据，才能在 Unit 2 中用 OAuth 把 Postman 连接到组织。开始获取：

1. 滚动到本页底部，点击 Launch 打开你的 Playground；
2. 如果看到 Get Your Login Credentials 标签——点击它并记下你的用户名，然后点击 Reset My Password；
3. 如果没有，从 App Launcher 中找到并打开 Playground Starter，按步骤操作；
4. 查收邮件中的重置链接；
5. 设置一个新密码并确认，点击 Change Password。

为什么需要重置密码？Playground 的密码是自动生成、不会直接显示给你的。重置后你才得到一个自己知道的密码——这正是后续 OAuth 登录所必需的。把用户名和密码保存好，本项目稍后会用到。

获取 Trailhead Playground 用户名与密码（二）：保存备用（Get Credentials (2): Save for Later）

重置密码后，把用户名和密码都保存在一个方便的地方——你在 Unit 2 中会被 Postman 的 OAuth 流程重定向到 Salesforce 登录页，届时需要输入它们。

这里有一个重要的安全要点：你要把这些凭据直接输入到 Salesforce 自己的登录页，而不是输入到 Postman 里。这正是 OAuth 的核心安全优势——第三方应用（Postman）永远看不到你的密码，它只在你认证后收到 Salesforce 生成的访问令牌。

如果弄丢了密码也没关系——重复 Reset My Password 步骤即可（会收到新邮件、设置新密码）。这些凭据是你访问组织的钥匙，请妥善保存，同时也要理解 OAuth 让它们保持安全。

在 Salesforce 中设置 CORS（一）：是什么与为什么（CORS (1): What & Why）

CORS（Cross-Origin Resource Sharing，跨域资源共享）是一种浏览器安全机制，它控制哪些网站可以调用你的 Salesforce 组织。核心问题在于：Postman 在你的浏览器里运行于 postman.com 或 postman.co，而 Salesforce 位于 salesforce.com——当 Postman 尝试向 Salesforce 发送 API 请求时，浏览器看到两个不同的域，就会依据同源策略拦截这个请求。

而 CORS 就是让 Salesforce 声明"来自 postman.com 的请求是可信的——放行"。配置了 CORS 之后，浏览器才会允许来自这些特定来源的请求到达 Salesforce。

没有配置 CORS，会发生什么？Postman 发出的每一个 API 调用都会在到达 Salesforce 之前就被你的浏览器拦截。这是每个组织只需做一次的配置，而且任何"从浏览器调用 Salesforce API 的 Web 应用"都需要它。

在 Salesforce 中设置 CORS（二）：配置步骤（CORS (2): Configuration Steps）

在 Setup 中添加两条 CORS 条目——.com 和 .co 两个域名都需要：

1. 在 Trailhead Playground 中，进入 Setup，在 Quick Find 框搜索并选择 CORS；
2. 在 Allowed Origins List 中点击 New；
3. Origin URL Pattern 输入 https://*.postman.com；
4. 点击 Save；
5. 再次选择 CORS，点击 New；
6. Origin URL Pattern 输入 https://*.postman.co（注意是 .co 而不是 .com！）；
7. 点击 Save。

为什么要两条？因为 Postman 同时使用 postman.com 和 postman.co 两个域名，如果你只配置了 .com，来自 .co 的请求仍会被拦截。而 * 通配符则覆盖了所有子域名。保存两条条目后，你的 Playground 就为 Postman 连接做好了准备——接下来在 Unit 2 中设置 Postman 本身。

设置并连接 Postman（02 Set Up and Connect Postman）

你的 Trailhead Playground 已经准备好了。现在设置 Postman：注册或登录账号、创建工作区、fork Salesforce Platform APIs 集合、验证 clientId 变量、通过 OAuth 2.0 授权，再用一个 GET Limits 请求测试连接，最后通过 REST API 创建一条 Account 记录。这就是你真正用 Postman 以编程方式与组织交互的地方。

注册 Postman 并创建工作区（Sign Up for Postman and Create a Workspace）

让 Postman 准备就绪——全程在浏览器中完成：

1. 前往 postman.com，登录你的 Postman 账号或注册一个（如需要，免费注册只需几秒）；
2. 选择 Workspaces 菜单；
3. 点击 Create Workspace；
4. 配置：Name 输入 SalesforceCollection，Select workspace type 选 Internal；
5. 点击 Create Workspace。

工作区（Workspace）是 Postman 组织资源的容器——你可以把它想成存放 API 集合、环境等资源的项目文件夹。命名为 SalesforceCollection 能让一切清晰明了，Internal 类型默认只对你自己可见。本项目全程使用 Web 版，它零安装、在任意浏览器都能用，对我们要做的事情来说与桌面版功能完全一致。

Fork Salesforce 集合（一）：创建你的 Fork（Fork the Salesforce Collection (1): Create Your Fork）

把 200+ 个预置的 Salesforce API 请求模板引入你的工作区：

1. 打开 Postman 上的公共 Salesforce Developers 工作区；
2. 在 Collections 中展开 Salesforce Platform APIs；
3. 点击 Fork 图标，创建该集合的一个 fork；
4. 配置：Fork label 输入 MySalesforceAPIFork，Workspace 保持 SalesforceCollection；
5. 点击 Fork Collection。

发生了什么？你在自己的工作区里创建了官方 Salesforce APIs 集合的一个私有副本。Postman 里的 fork 和 GitHub 里的 fork 是一个道理——你得到了别人的成果的一份拷贝，可以自由修改而不影响原版。现在，全部 200+ 个请求模板（REST、SOAP、Bulk、Metadata、Streaming……）都已在你的工作区中可用。

Fork Salesforce 集合（二）：你得到了什么（Fork the Salesforce Collection (2): What You Got）

这个 fork 是你的沙盒——原集合始终保持原样，需要时随时可以重新 fork。而你的副本才是你可以实验的地方：修改请求体、添加新端点、配置针对不同组织的环境。

Postman 的环境（Environment）尤其强大：为每个组织创建一个环境，各自拥有自己的 instance_url 和令牌，然后在生产、沙盒、Dev1、Dev2 之间切换——都用同一个集合，只是变量取值不同。

所有请求模板都已预先配置好正确的请求头、认证方式和端点 URL，你只需填入变量即可。今天你只会用到其中几个请求，但整个 200+ 的目录在你需要时随时可用。

验证 clientId 变量（一）：检查取值（Verify the clientId Variable (1): Check the Value）

这是一个小但关键的步骤。当集合被 fork 时，Postman 有时会覆盖它认为是敏感的变量——而 clientId 正是其中之一。检查并确认：

1. 在新的 SalesforceCollection 工作区中，选中 Salesforce Platform APIs 集合，点击 Variables 标签；
2. 查看 clientId 的 Value；
3. 确认其取值等于：

3MVG98_Psg5cppyYCmk1gZNC25o00SXpgpodlS29IZ6pXiHkt3xuPa5qIjBTtEgdsiMuIWVN_8F0jnwEtbDh4

1. 如果不一致，立即手动更新它。

clientId 是什么？它是 Connected App 的 consumer key，在 OAuth 认证期间用来向 Salesforce 标识"是 Postman 集合在请求访问"。没有正确的 clientId，OAuth 会失败 → 没有令牌 → 无法访问 API。花 30 秒现在核对，能省下之后 30 分钟的排错。

验证 clientId 变量（二）：为什么重要（Verify the clientId Variable (2): Why It Matters）

理解为什么这个变量如此重要。OAuth 2.0 需要三样东西才能工作：

• clientId——标识是哪个应用在请求访问（也就是我们的 Postman 集合）；
• clientSecret——证明该应用是合法的（由 Salesforce 自动处理）；
• Redirect URI——用户批准后要跳转到的地址（也自动处理）。

这三者中任何一个错了，认证都会在还没开始时就失败。而 clientId 是最可能在 fork 过程中被覆盖的那个，因为 Postman 出于安全考虑，有时会清空或替换它认为是敏感的变量——这正是需要手动核对的原因。一个正确的取值、一个变量，就是后续一切的基础。核对无误后，就可以进入授权流程了。

授权你的组织（一）：OAuth 设置（Authorize Your Org (1): OAuth Setup）

通过 OAuth 2.0 认证 Postman，让它能访问你的 Salesforce 组织。开始前先确认：

• 浏览器中只登录了一个 Trailhead Playground（把其它的都登出！多个会话会干扰 OAuth 流程，把令牌发到错误的组织）；
• Salesforce Platform APIs 集合处于选中状态；
• No Environment 处于选中状态。

然后：

1. 打开 Authorization 标签；
2. Auth Type 应为 OAuth 2.0（通常是默认）；
3. 点击 Get New Access Token。

接下来会发生：浏览器打开 Salesforce 登录页 → 输入你在 Unit 1 保存的用户名和密码 → Salesforce 询问是否"允许 Salesforce Platform APIs Collection for Postman 访问你的数据" → 点击 Allow。

这就是 OAuth——你授予的是有限、可撤销的权限，而不是把密码交给 Postman。Postman 永远看不到你的密码，它只收到一个 Salesforce 生成的访问令牌。

授权你的组织（二）：令牌与实例 URL（Authorize Your Org (2): Token & Instance URL）

点击 Allow 后，你会被重定向到 Manage Access Tokens 对话框：

1. 确认 instance_url 指向你的 Trailhead Playground；
2. 复制 instance_url（只复制 URL，不要带多余字符）；
3. 点击 Use Token；
4. 打开 Variables 标签；
5. 在 _endpoint 行的 VALUE 列，粘贴刚才复制的 instance_url。

instance_url 是什么？它是你特定 Salesforce 组织的唯一地址（每个组织都有一个，形如 https://yourdomain.my.salesforce.com）。没有这个变量，Postman 就不知道该把请求发到哪个组织。设置好之后，集合里全部 200+ 个请求都会自动继承你的令牌和端点——这就是 Postman 变量的魅力：配置一次，处处复用。

快速连接测试（一）：发送 GET Limits（A Quick Connection Test (1): Send GET Limits）

验证一切正常——调用 REST API 获取你组织的 API 使用限制：

1. 在 Collections 中展开 Salesforce Platform APIs；
2. 展开 REST，选择 GET Limits；
3. 点击 Send；
4. 验证状态码为 200 OK。

发生了什么？Postman 向 /services/data/vXX.X/limits 发送了一个带认证的 GET 请求，Salesforce 校验你的访问令牌后，返回包含所有 API 限制信息的 JSON——每天已用的 API 调用数与上限、每个 API 的限制等等。

GET Limits 是完美的首个测试：它要求有效的认证、使用 REST API、返回有意义的数据，并确认整条链路都正常。成功的响应意味着认证有效、instance_url 正确、OAuth 令牌有效、组织接受 API 请求——这就是你的绿灯。

快速连接测试（二）：验证与排错（A Quick Connection Test (2): Verify & Troubleshoot）

如果拿到了 200 OK，说明你已经连接成功！如果没拿到，常见问题有：

• 不是 200 OK？ 检查 Settings 标签，把 Follow Authorization header 配置设为 ON——当重定向到不同主机名时，它能保留授权头；
• 连接被拒？ 确认 Setup 里的 CORS 条目已保存、instance_url 与你的 Playground 匹配、令牌未过期；
• 数据不对？ 你可能指向了另一个组织——检查 _endpoint 的取值。

一次成功就确认了：认证正常、instance_url 正确、OAuth 令牌有效、CORS 配置正确、组织接受 API 请求。全线绿灯！现在来做点比读数据更有意思的事。

创建一个 Account（一）：通过 REST API（Post an Account (1): Create via REST API）

读数据已经跑通了——现在通过 REST API 向组织写数据：

1. 在 REST 下展开 SObject，选择 POST SObject Create；
2. 打开 Params 标签；
3. 在 Path Variables 下，把 SOBJECT_API_NAME 行的 VALUE 设为 Account；
4. 打开 Body 标签；
5. 把正文替换为这段代码：

{
  "Name": "Postman",
  "BillingState": "CA"
}

1. 点击 Save，再点击 Send；
2. 验证状态码为 201 Created。

POST SObject Create 是一个通用 REST 端点，可以在任何标准或自定义对象上创建记录——你在 Path Variables 里指定是哪个对象。把 SOBJECT_API_NAME 设为 Account，就是告诉 API 我们要创建一条 Account。响应体会包含新记录的 Salesforce Id。你刚刚通过 API 调用——而不是通过界面——以编程方式创建了一条 Account 记录。这就是一切集成的基础：创建、读取、更新、删除，全都走同一套 REST API 模式。

创建一个 Account（二）：在 Salesforce 中验证（Post an Account (2): Verify in Salesforce）

最后的验证让整个闭环合拢。确认这条记录确实存在于你的组织里：

1. 打开你授权的 Playground；
2. 从 App Launcher 找到并打开 Accounts；
3. 确认新的 Account 出现在那里，BillingState 为 CA。

看到这条记录，就确认了整条链路：Postman 发送了带认证的 POST 请求 → REST API 创建了 Account → 数据现在在 UI 中和普通方式创建的记录并排可见。

如果没看到它，最常见的原因是指向了错误的组织——检查你的 _endpoint 变量；另一个要点是确认你在 Postman 和 Salesforce 里看的是同一个组织。响应体里包含了 Id，说明记录确实被创建了，只是要核实创建到了对的 org。

恭喜！你已经完整跑通了 API 集成闭环：配置、认证、读、写、验证。这套模式——POST 创建、GET 读取、PATCH 更新、DELETE 删除——对 Contact、Opportunity、Case、自定义对象，以及 Salesforce 中几乎任何东西都同样适用。

---

文章来源：Trailhead - Quick Start: Connect Postman to Salesforce