REST API 允许您以编程方式访问 Salesforce 中的数据。这 REST API 的灵活性和可扩展性使其成为集成 Salesforce 的绝佳选择到您的应用程序中，并用于大规模执行复杂的操作。

使用本指南设置部署环境并了解有关以下方面的高级详细信息数据访问。但是，理解和使用 REST API 需要对软件有基本的了解开发、Web 服务和 Salesforce 用户界面。

如果您想立即采取行动，快速入门指南涵盖了帮助您入门的基础知识和运行。

如果您正在寻找有关 Salesforce API 的更多上下文，请查看链接列表。

提示

Salesforce REST API 旨在与 Salesforce 对象一起使用。请参阅 Salesforce 的对象参考有关 Salesforce 对象的介绍和更多信息的平台。

关于 REST API

REST API 是可用于访问 Salesforce 的多个 Web 界面之一数据，而不使用 Salesforce 用户界面。通过 API 访问，您可以执行操作和根据需要将 Salesforce 集成到您的应用程序中。

您可以使用 REST API 工具通过发送 HTTP 在 Salesforce 中创建、操作和搜索数据对 Salesforce 中端点的请求。根据您发送请求的位置，您可以访问和操作在不同的信息上，称为资源。资源包括记录、查询结果、元数据等。

REST API 使用 RESTful 架构来提供简单且一致的接口。一个 REST API 的主要优点是它不需要太多工具即可访问您的数据。它比 SOAP API 更易于使用，但仍然提供了大量功能。

尽管 REST API 非常适合访问和查询记录，但其他 Salesforce API，例如 Bulk 2.0 API、元数据 API 和 Connect REST API 为特定任务。

REST API 发行说明

使用 Salesforce 发行说明了解 REST API。

有关影响 Salesforce Platform（包括 REST API）的更新和更改，请参阅 API 发行说明。

为新的、已更改的和已弃用的调用以及特定于 REST API 的其他更改，请参阅 Salesforce 发行说明中的 REST API。

支持的版本和所需的权限

要使用 Salesforce API 访问您的 Salesforce 组织和数据，您需要一个组织以及启用了 API 访问权限的用户。有多个支持 API 的 Salesforce 版本访问权限和向用户授予 API 权限的多种方式。

API 访问支持的版本

默认情况下，API 访问在 Enterprise、Performance、Unlimited 和 Developer 中处于启用状态版本组织。Professional Edition 组织可以将 API 访问权限添加为附加组件。查看更多信息，请访问 Salesforce 帮助：使用“您的”添加产品和许可证帐户应用程序或联系 Salesforce 客户经理。

如果您向没有 API 访问权限的组织发送 API 请求，Salesforce 将返回错误。API_DISABLED_FOR_ORG

为了保护生产组织中的配置和实时数据，我们建议使用用于主动开发和测试的隔离环境，例如 aDeveloper Edition org、沙盒或 Scratch 组织。准备就绪后，您可以将成功的更改转移到生产中组织。

API 用户权限

若要进行任何 API 调用，用户必须在用户中启用“已启用 API”权限他们分配的配置文件。默认情况下，某些配置文件上启用此权限，包括 Developer Edition 组织中提供的许多配置文件。在受支持的版本中，您还可以使用 Salesforce 集成用户许可证，用于授予系统到系统集成用户完整的组织权限访问，同时将它们限制为仅限 API 的操作。有关详细信息，请参阅 Salesforce 帮助：仅授予集成用户 API 访问权限

REST 资源和请求

REST API 基于资源的使用情况 – 片段 Salesforce 中的数据，例如记录、记录集合、查询结果、元数据、或 API 信息。每个资源都由统一资源标识符（URI）公开，并且通过向相应的 URI 发送 HTTP 请求来访问。取决于您要访问的资源以及访问方式构造 HTTP 请求时，可以执行多种类型的操作，包括：

确定可用的 API 版本
Salesforce 组织的访问限制
检索对象元数据
创建、读取、更新和删除记录
查询和搜索数据

您可以使用各种软件工具发送 HTTP 请求，这意味着确切的请求的外观可能与本指南中的 cURL 示例不同。但是，无论您如何提交请求，元素都不会更改。典型请求由这些元素组成。

URI
HTTP 方法
头
请求正文（GET 请求不需要）

URI

URI 是 Salesforce 中资源的路径。尽管 URI 从资源到资源，基本结构保持不变。

https://MyDomainName.my.salesforce.com/services/data/vXX.X/resource/

用于安全访问资源。https://

替换为 Salesforce 组织的子域。Salesforce 在多个服务器实例上运行，因此本指南中的示例用于代替特定的实例。MyDomainNameMyDomainName

替换为版本要使用的 API。您可以通过以下方式找到可用版本列表访问 Versions 资源。XX.X

替换为资源路径的其余部分。根据资源的不同，路径可以包含参数，例如用于标识特定记录的 ID。您可以找到的 URI 本指南的“参考”部分中的不同资源。resource

sObject 资源访问 Salesforce 中的标准和自定义对象。有关的信息对象，请参阅对象参考 Salesforce平台。

注意

URI 的某些部分区分大小写，例如 ID。URI 的其他部分不是区分大小写，例如对象和字段名称。如果您的请求不成功，通过将 URI 与示例进行比较，检查 URI 是否具有正确的字母大小写在本指南中。

HTTP 方法

REST API 支持标准 HTTP 请求方法（HEAD、GET、POST、PATCH、PUT 和 DELETE），它们遵循 https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html 中的规范。

每种方法的用途因资源而异。有关如何操作的信息以及何时使用每种方法，请在参考中查看该资源的页面部分。

头

使用标头传递参数并自定义 HTTP 请求的选项。REST API 支持多个标准 HTTP 标头，以及特定于到 Salesforce。

示例中使用的常见标头包括：

HTTP Accept – 指示客户端接受的格式响应正文。可能的值为和。缺省值为。application/jsonapplication/xmlapplication/json
HTTP Content-type – 指示您的请求正文的格式附加到请求。可能的值为和。application/jsonapplication/xml
HTTP 授权 – 提供 OAuth 2.0 访问令牌以授权您的客户。REST API 支持持有者身份验证类型。
压缩标头 – 压缩请求或响应。查看更多信息，请参阅压缩标头。
条件请求标头 – 验证您访问所依据的记录一个前提条件。有关详细信息，请参阅条件请求标头。

请求机构

请求正文是一个丰富的输入，可以包含在请求中以提供其他信息，例如用于创建或更新记录的字段值。一个请求正文可以是 JSON 或 XML 格式。

注意

使用 GET 方法访问的资源不需要附加请求身体。

使用 HTTP Content-type 标头指示请求正文的文件格式。如果使用 cURL 发送请求，使用或选项。—data-binary-d

REST API 体系结构

REST API 遵循标准的 RESTful 原则和特征。
客户端-服务器
客户端应用程序独立于 Salesforce REST API，这意味着每个应用程序都是托管的并独立更新。
无国籍
从客户端到服务器的每个请求都必须包含所有必要的信息了解请求，并且不要在服务器上使用任何存储的上下文。但是，资源的表示形式使用 URI 相互连接，允许客户端在各州之间取得进展。
缓存行为
响应被标记为可缓存或不可缓存。
统一界面
所有资源都通过 HTTPS 的通用接口进行访问。
命名资源
所有资源都使用遵循 Lightning 平台的基本 URI 进行命名端点。有关详细信息和示例，请参阅 REST 资源和请求。
分层组件
允许在客户端和资源。
除了标准的 RESTful 原则外，REST API 还包括其他关键特性在其架构中，在开发应用。

认证
REST API 支持 OAuth 2.0（一种允许安全 API 授权的开放协议）。有关更多详细信息，请参阅 Salesforce 帮助中的使用 OAuth 授权应用程序。
支持 JSON 和 XML
JSON 请求在 UTF-8 中受支持，并且是默认请求。支持 XML 请求采用 UTF-8 和 UTF-16 格式。XML 响应以 UTF-8 格式提供。使用标头指定 JSON 或 XML。HTTP ACCEPT
在版本 57.0 及更早版本中，可以追加 URI 或向 URI 添加。例如。我们建议使用用于指定 JSON 或 XML 的标头相反。jsonxml/Account/001D000000INjVe.jsonHTTP ACCEPT
在版本 58.0 及更高版本中，不支持将 JSON 或 XML 追加到 URI。
压缩
压缩通过压缩 REST API 之间发送的消息来减少带宽负载和你的客户。REST API 支持使用 gzip 和 deflate 进行压缩，定义如下 HTTP 1.1 规范。请参阅压缩标头。
条件请求
响应缓存由遵循标准的条件请求标头支持由 HTTP 1.1 规范定义，但有一些例外。请参阅条件请求头。
跨域资源共享
跨域资源共享（CORS）使 Web 浏览器能够从出身以外的其他来源。例如，使用 CORS，JavaScript 代码位于 https://www.example.com 可以向 https://www.salesforce.com 请求资源。自从 JavaScript 访问受支持的 Salesforce API、Apex REST 资源和 Lightning Out 代码，将提供代码的来源添加到 Salesforce CORS 允许列表。请参阅从 Web 浏览器执行跨域请求。
Salesforce ID 长度
响应正文中的 Salesforce ID 始终为 18 个字符的 ID。在请求正文中，您可以使用 15 个字符的 ID 或 18 个字符的 ID。
方法重写
如果使用不允许重写或设置任意HTTP方法名称，请使用request参数。_HttpMethod
POST https://instance_name/services/data/v59.0/chatter/
/chatter/users/me/conversations/03MD0000000008KMAQ
?_HttpMethod=PATCH&read=true
注意

该参数区分大小写。用所有值的正确大小写。_HttpMethod

HTTPS协议
客户端和服务器之间的所有通信都通过 HTTPS 进行。

通过连接的应用程序和 OAuth 2.0 进行授权

要使客户端应用程序访问 REST API 资源，必须将其授权为保险箱游客。若要实现此授权，请使用连接的应用程序和 OAuth 2.0 授权流。

配置连接的应用程序

连接的应用代表客户端应用程序请求访问 REST API 资源。为连接的应用程序要请求访问权限，则必须使用 OAuth 2.0 协议。OAuth 2.0 是一种开放协议，它授权在通过代币交换进行申请。

有关配置连接的应用程序的说明，请参阅在 Salesforce 中创建连接的应用程序帮助。具体而言，请按照启用 API 的 OAuth 设置中的步骤操作集成。

应用 OAuth 授权流程

OAuth 授权流授予客户端应用对 REST API 资源的受限访问权限资源服务器。每个 OAuth 流都提供不同的流程来批准对客户端的访问应用程序，但通常流程由三个主要步骤组成。

若要启动授权流，代表客户端应用请求的已连接应用访问 REST API 资源。
作为响应，授权服务器将访问令牌授予连接的应用程序。
资源服务器验证这些访问令牌并批准对受保护令牌的访问 REST API 资源。

查看并选择 OAuth 授权流后，将其应用于连接的应用。为有关每个受支持的流程的详细信息，请参阅 Salesforce 中的 OAuth 授权流程帮助。

头

REST API 支持多个标准和自定义 HTTP 标头，包括两个请求标头和响应标头。

分配规则标头 分配规则标头是在创建或更新客户、案例或潜在顾客时应用的请求标头
。如果启用，则使用活动分配规则。如果禁用，则不应用活动分配规则。如果提供了有效的 AssignmentRule ID，则应用 AssignmentRule。如果未随请求一起提供标头，则 REST API 默认使用活动分配规则。
调用选项标头
指定用于访问 REST API 资源的客户端的选项。例如，可以提供默认命名空间前缀，这样就不需要在代码中指定前缀。
压缩标头
使用压缩标头压缩 REST API 请求或响应。压缩会降低请求所需的带宽，尽管它需要客户端的更多处理能力。在大多数情况下，这种权衡有利于应用程序的整体性能。
条件请求标头
在访问资源之前，使用条件请求标头来验证资源。通过在标头中设置前提条件，可以确保仅当满足该前提条件时，请求才会成功。此功能可帮助您在更新 Salesforce 数据时防止错误并拒绝过时的请求。您可以使用条件请求标头实现各种技术，例如响应缓存。
重复规则标头
配置重复规则的选项。Salesforce 使用重复规则来查看正在创建、更新或更新插入的记录是否与现有记录重复。重复规则是重复管理的一部分。
限制信息标头此响应标头
在对 REST API 的每个请求中返回（对版本 URI 的调用除外，这些调用不计入组织的限制）。您可以使用这些信息来监控 API 限制。/
包版本标头
指定客户端引用的每个包的版本。包版本是一个数字，用于标识包中包含的组件和行为集。此标头还可用于在调用 Apex REST Web 服务时指定包版本。
查询选项标头
指定查询中使用的选项，例如查询结果批大小。将此请求标头与查询资源一起使用。
警告标头
如果存在警告，例如使用已弃用的 API 版本，则返回此标头。

分配规则标头

分配规则标头是在创建或更新时应用的请求标头客户、案例或潜在顾客。如果启用，则使用活动分配规则。如果禁用，不应用活动分配规则。如果提供了有效的 AssignmentRule ID，则应用 AssignmentRule。如果未随请求一起提供标头，则 REST API 默认为使用活动分配规则。

标头字段名称和值

注意

在进行 REST API 调用时，也会应用此标头，这些调用间接导致创建或更新客户、案例或潜在客户。例如，如果将此标头与更新记录的调用，并且更新将执行更新 Case 的 Apex 触发器将应用分配规则。字段名称Sforce-Auto-Assign字段值

TRUE.应用活动分配规则创建或更新了客户、案例或潜在顾客。
FALSE.活动分配规则不是适用于已创建或更新的客户、案例或潜在客户。
有效的 AssignmentRule ID。给定的 AssignmentRule 应用于创建的帐户，案例或线索。

TRUE并且不区分大小写。FALSE

如果请求中未提供标头，则默认值为。TRUE例Sforce-Auto-Assign: FALSE

看涨期权标题

指定用于访问 REST 的客户端的选项 API 资源。例如，您可以提供默认的命名空间前缀，以便您不需要在代码中指定前缀。

“调用选项”标头可以与 sObject 基本信息、sObject 行、按外部 ID 划分的 sObject 行、Query、QueryAll、和搜索。批量 API 和批量 API 2.0 也支持它。

标头字段名称和值

字段名称Sforce-Call-Options字段值

client– 用作发送请求的客户端的标识符。此字符串显示在日志文件中，帮助您跟踪哪个客户端发送了请求。
defaultNamespace——答开发人员命名空间前缀用作请求。使用此标头字段，请求将解析没有指定命名空间的托管包。（不支持批量 API。

例

如果 developer 命名空间前缀为，并且您在包中有一个名为 botId 的自定义字段，请将带有调用选项的默认命名空间页眉：

battle

Sforce-Call-Options: client=caseSensitiveToken; defaultNamespace=battle

然后如下所示的查询成功：

/services/data/vXX.X/query/?q=SELECT+Id+botID__c+FROM+Account

在本例中，实际查询的字段是battle__botId__c字段。

使用此标头可以编写客户端代码，而无需指定命名空间前缀。在前面的示例中，如果没有标头，则必须编写 battle__botId__c。

如果设置了此字段，并且查询还指定了命名空间，则响应不包含前缀。例如，如果将此标头设置为，并发出类似的查询，则 response 使用元素，而不是元素。battleSELECT+Id+battle__botID__c+FROM+AccountbotId__cbattle_botId__c

当出现以下情况时，该字段将被忽略检索描述信息，避免命名空间前缀之间的歧义和同名的客户字段。defaultNamespace

压缩标头

使用压缩标头压缩 REST API 请求或响应。压缩减少请求所需的带宽，尽管它需要客户端的更多处理能力。在大多数情况下，这种权衡有利于应用程序的整体性能。

REST API 支持 HTTP 1.1 定义的 gzip 和 deflate 压缩算法规范。如果您不确定使用哪一个，gzip 比 deflate 更常见。

提示

为了获得更好的性能，我们建议客户端接受并支持压缩由 HTTP 1.1 规范定义。

请求压缩

包括 or 标头以压缩请求。REST API 在处理之前解压缩任何请求。Content-Encoding: gzipContent-Encoding: deflate

此示例请求使用 gzip 压缩。

curl https://MyDomainName.my.salesforce.com/services/data/v59.0/sobjects/Account/ -H "Authorization: Bearer access-token" -H "Content-Type: application/json" -H "Content-Encoding: gzip" —data-binary @new-account.json -X POST

响应压缩

仅当请求包含 or 标头时，Salesforce 才会压缩响应。即使有指定了 Accept-Encoding，但它通常会这样做。如果压缩，则响应包含带有压缩算法的 Content-Encoding 标头，以便客户端知道解压缩它。Accept-Encoding: gzipAccept-Encoding: deflate

此示例请求请求压缩响应。

curl https://MyDomainName.my.salesforce.com/services/data/v59.0/sobjects/Account/0015e000009sS0DAAU -H "Authorization: Bearer access-token" -H "Content-Type: application/json" -H "Accept-Encoding: gzip" -X GET

条件请求标头

在访问资源之前，使用条件请求标头来验证资源。由在标头中设置一个前提条件，确保只有在满足前提条件。此功能可帮助您防止错误并拒绝过时的请求更新 Salesforce 数据时。您可以使用条件实现各种技术请求标头，例如响应缓存。

条件请求标头提供两种类型的验证：强验证和弱验证。强验证检查前提条件是否与 Salesforce 中的资源完全匹配。强验证标头包括和，它们使用实体标记（ETag）来比较 Salesforce 中记录的前提条件。If-MatchIf-None-Match

弱验证会根据 Salesforce 中的资源检查前提条件，但事实并非如此保证两者相同。弱验证标头包括或，它将前提条件与 Salesforce 中的记录。If-Modified-SinceIf-Unmodified-SinceREST API 条件标头遵循 HTTP 1.1 规范，但存在以下例外情况。

如果为、或 PATCH 或 POST 请求包含无效的标头值，则返回状态代码。If-MatchIf-None-MatchIf-Unmodified-Since400 Bad Request
不支持标头。If-Range
不支持 DELETE 请求

ETag （英语）

标头是返回的响应标头访问 sObject Rows 资源时。它是后续请求中和请求标头使用的内容的哈希值，用于确定内容是否已更改。ETagIf-MatchIf-None-Match

sObject 行（仅限客户记录）资源支持此标头。

此示例显示了 REST API 返回的。ETag

ETag: "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"

您可以在 www.w1.org/Protocols/rfc1/rfc3-sec2616.html#sec2616.14 中找到标头的 HTTP 14.19 规范。ETag

如果匹配

标头是 sObject 的请求标头包含 ETag 列表的行。如果请求的记录的 ETag 匹配在标头中指定为前提条件的 ETag，则处理请求。否则，一个 412 返回前提条件失败状态代码，并且不处理请求。If-Match

此标头支持 sObject 行（仅限客户记录）资源。

在此示例中，标头包含在请求。If-Match

If-Match: "Jbjuzw7dbhaEG3fd90kJbx6A0ow=-gzip", "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"

您可以在 www.w1.org/Protocols/rfc1/rfc3-sec2616.html#sec2616.14 中找到标头的 HTTP 14.24 规范。If-Match

如果-无匹配

标头是 sObject 行，与相反。如果您请求的记录的 ETag 与标头中指定的 ETag 匹配，即请求未得到处理。为 GET 或 HEAD 返回 304 未修改状态代码请求，并且 PATCH 请求返回 412 前提条件失败状态代码。If-None-MatchIf-Match

此标头支持 sObject 行（仅限客户记录）资源。

在此示例中，包含一个标头有请求。If-None-Match

If-None-Match: "Jbjuzw7dbhaEG3fd90kJbx6A0ow=-gzip", "U5iWijwWbQD18jeiXwsqxeGpZQk=-gzip"

您可以在 www.w1.org/Protocols/rfc1/rfc3-sec2616.html#sec2616.14 中找到标头的 HTTP 14.26 规范。If-None-Match

如果修改后

标头是基于时间的请求页眉。仅当数据自日期和时间以来发生更改时，才会处理请求在标头中指定。否则，将返回 304 Not Modified 状态代码，并且请求未得到处理。If-Modified-Since

此标头支持 sObject Rows、sObject 描述、描述全局和可调用操作资源。

在此示例中，标头是包含在请求中。If-Modified-Since

If-Modified-Since: Tue, 10 Aug 2015 00:00:00 GMT

您可以在 www.w1.org/Protocols/rfc1/rfc3-sec2616.html#sec2616.14 中找到标头的 HTTP 14.25 规范。If-Modified-Since

如果未修改，则自

标头是请求标头这是的反面。如果你做一个 request 并包含 If-Unmodified-Since 标头，则 REST API 仅在以下情况下处理请求自指定日期以来，数据未发生更改。否则，412 前提条件将失败返回状态代码，并且不处理请求。If-Unmodified-SinceIf-Modified-Since

此标头支持 sObject Rows、sObject 描述、描述全局和可调用操作资源。

在此示例中，标头为包含在请求中。If-Unmodified-Since

If-Unmodified-Since: Tue, 10 Aug 2015 00:00:00 GMT

您可以在 www.w1.org/Protocols/rfc1/rfc3-sec2616.html#sec2616.14 中找到标头的 HTTP 14.28 规范。If-Unmodified-Since

重复的规则标头

配置重复规则的选项。Salesforce 使用复制规则，用于查看正在创建、更新或更新插入的记录是否为重复记录现有记录。重复规则是重复管理的一部分。

此标头在 API 版本 52.0 及更高版本中可用。

标头字段名称和值

所有字段的默认值均为。false字段名称allowSave字段值

true– 允许用户确认警报并保存重复的记录。如果为操作启用了警报，则适用。
false– 不允许用户确认警报或保存重复的记录。如果为操作启用了警报，则适用。

字段名称includeRecordDetails字段值

true– 返回重复项中的所有字段记录。
false– 返回重复的记录 ID，但不返回字段。

字段名称runAsCurrentUser字段值

true– 运行重复规则时，使用当前用户的共享规则。
false– 运行重复规则时，使用系统共享规则，而不是当前用户的共享规则。

例

允许用户确认警报并保存重复记录。指示将返回重复字段的记录，并强制执行当前用户的共享规则。现在，在创建记录时应用这些重复的管理配置选项。更新和更新插入。

Sforce-Duplicate-Rule-Header: allowSave=true, includeRecordDetails=true, runAsCurrentUser=true

限制信息标题

在对 REST API 的每个请求中都会返回此响应标头（对版本 URI 的调用除外，这些调用不计入组织的限制）。您可以使用这些信息来监控 API 限制。/

标头字段名称和值

字段名称Sforce-Limit-Info字段值

api-usage– 指定进行调用的组织的每日 API 使用情况。第一个数字是数字使用的 API 调用，第二个数字是组织的 API 限制。

标头中返回的值表示标准 REST API 限制和用法。除非使用 Salesforce Functions 进行调用。使用 Salesforce 拨打的电话函数从特定于函数的分配中获取。例Sforce-Limit-Info: api-usage=10018/100000

包版本标头

指定客户。包版本是标识组件和行为集的数字包含在包中。此标头还可用于指定包版本调用 Apex REST Web 服务时。

Package Version 标头可与以下资源一起使用：Describe Global、sObject Describe、 sObject 基本信息、sObject 行、按外部 ID 划分的 sObject 布局、Query、QueryAll、Search 和 sObject 行。

标头字段名称和值

字段名称和值x-sfdc-packageversion-[namespace]: xx.x，其中是托管包的唯一命名空间，是包版本。[namespace]xx.x例x-sfdc-packageversion-clientPackage: 1.0

查询选项标头

指定查询中使用的选项，例如查询结果批处理大小。将此请求标头与查询一起使用资源。

标头字段名称和值

字段名称Sforce-Query-Options字段值

batchSize– 指定为查询请求返回的记录数。子对象计入批大小的记录。例如，在关系查询中，多个子项每个返回的父行返回对象。默认值为 2,000; 最小值为 200，最大值为 2,000。不能保证请求的批处理大小是实际的批处理大小。根据需要进行更改以最大化性能。

例Sforce-Query-Options: batchSize=1000

警告标头

如果存在警告，例如使用已弃用的 API 版本，则返回此标头。

标头字段名称和值

字段名称Warning字段值warningCode warningMessage有关已弃用的 API 版本的警告，请 .warningCode299

例

Warning: 299 - "This API is deprecated and will be removed by Summer '22. Please see https://help.salesforce.com/articleView?id=000351312 for details."

使用 cURL 发送 REST 请求

本指南中的示例使用 cURL 工具发送 HTTP 请求，这些请求访问在 Salesforce 中创建和操作资源。如果您使用其他工具发送 requests，您可以使用 cURL 示例中的相同元素来发送请求。

cURL 预装在许多 Linux 和 macOS 系统上。Windows 用户可以下载版本为 curl.haxx.se/。在 Windows 上使用 HTTPS 时，请确保您的系统满足 SSL 的 cURL 要求。

注意

cURL 是一个开源工具，不受 Salesforce的。

附加请求正文

许多示例包括请求正文 – 包含请求。使用 cURL 时，请将这些文件保存到本地系统并附加它们使用 —data-binary 或 -d 选项添加到请求中。

此示例附加 new-account.json 文件。

curl https://MyDomainName.my.salesforce.com/services/data/v59.0/sobjects/Account/ -H "Authorization Bearer access-token" -H “Content-Type: application/json” —data-binary @new-account.json -X POST

处理访问令牌中的感叹号

运行 cURL 示例时，由于以下原因，在 macOS 和 Linux 系统上可能会出现错误 OAuth 访问令牌中是否存在感叹号（！）特殊字符。若要避免出现此错误，请转义感叹号或使用单个引号。

若要对访问令牌中的感叹号进行转义，请在其前插入反斜杠（\！）当访问令牌括在双引号内时。例如，访问此 cURL 命令中的令牌字符串具有感叹号（！）转义。

curl https://MyDomainName.my.salesforce.com/services/data/v59.0/ -H "Authorization: Bearer 00D50000000IehZ\!AQcAQH0dMHZfz972Szmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1E6LYUfiDUkWe6H34r1AAwOR8B8fLEz6n04NPGRrq0FM"

或者，可以将访问令牌括在单引号内。

curl https://MyDomainName.my.salesforce.com/services/data/v59.0/ -H 'Authorization: Bearer 00D50000000IehZ!AQcAQH0dMHZfz972Szmpkb58urFRkgeBGsxL_QJWwYMfAbUeeG7c1E6LYUfiDUkWe6H34r1AAwOR8B8fLEz6n04NPGRrq0FM'

配置 Salesforce CORS 允许列表

跨域资源共享（CORS）允许 Web 浏览器请求来自其他来源的资源。例如，使用 CORS，https://www.example.com Web 应用程序的 JavaScript 可以从 https://www.salesforce.com 请求资源。要允许访问受支持的 Salesforce API，请执行以下操作： Apex REST 资源和 Web 浏览器中 JavaScript 代码的 Lightning Out，添加请求源添加到您的 Salesforce CORS 允许列表。对于允许 Web 浏览器制作的 Lightning 应用程序来自其组织的请求，CORS 允许列表会阻止对 Lightning 应用程序的请求，除非请求来自已批准的 URL。

适用于：Salesforce Classic（并非在所有组织中都可用）和闪电体验

适用于：Developer、Enterprise、Performance 和 Unlimited Edition

在以下版本中启用 API 访问时可用：专业版

所需的用户权限
要创建、读取、更新和删除，请执行以下操作：	修改所有数据

这些 Salesforce 技术支持 CORS。

Apex REST的
批量 API
批量 API 2.0
连接 REST API
闪电输出
REST API
CRM 分析 REST API
用户界面 API

将提供请求代码的源添加到 CORS 允许列表。如果支持 CORS 的浏览器向允许列表中的源发出请求，Salesforce 会在 HTTP 标头中返回源以及任何其他 CORS HTTP 标头。如果源未包含在允许列表中，Salesforce 将返回 HTTP 状态代码 403。Access-Control-Allow-Origin

在“设置”的“快速查找”框中，输入 CORS，然后选择“CORS”。
选择新建。
在 Origin URL Pattern 中输入资源。提示源 URL 模式并不总是与浏览器的地址栏。
保存更改。

源 URL 模式必须包含 HTTPS 协议（除非您使用的是 localhost）和域名。它还可以包括端口。支持通配符（*），并且必须在二级域名前面。例如，https：//*.example.com 会将 example.com 的所有子域名添加到许可名单中。

源 URL 模式可以是 IP 地址。但是 IP 地址和解析为同一地址不是同一来源，您必须将它们单独添加到 CORS 允许列表中条目。

允许将 Google Chrome™ 和 Mozilla® Firefox® 浏览器扩展作为 API 中的资源版本 53 （Winter ’22）或更高版本。Chrome 扩展程序必须使用前缀和 32 个字符，不带数字或大写字母字母，例如.Firefox 扩展必须使用前缀和 8-4-4-4-12 小字母数字字符的格式，例如。chrome-extension://chrome-extension://abdkkegmcbiomijcbdaodaflgehfffedmoz-extension://moz-extension://1234ab56-78c9-1df2-3efg-4567891hi1j2

在 CORS 预检测试中请求 REST 资源时，您可以获得成功的响应。但收到对实际请求的不成功响应。当资源在印前检查测试之后和发出请求之前被删除。它也可能发生如果资源不存在。CORS 预检确认资源是否可以在服务器，但不检查特定资源是否存在。 CORS 预检请求是通常由浏览器自动发出。

注意

要使用 CORS 访问某些 OAuth 端点，需要满足其他要求。请参阅为 OAuth 端点启用 CORS。

有效的日期和日期时间格式

为和字段指定正确的格式。

dateTimedate

日期时间

使用 or 格式指定字段。yyyy-MM-ddTHH:mm:ss.SSS+/-HH:mmyyyy-MM-ddTHH:mm:ss.SSSZdateTime

yyyy 是四位数的年份
MM 是两位数的月份（01-12）
dd 是两位数的日期（01-31）
“T”是一个分隔符，表示一天中的时间紧随其后
HH 是两位数小时（00-23）
mm 是两位数的分钟（00-59）
ss 是两位数秒（00-59）
SSS 是可选的三位数毫秒（000-999）
+/-HH：mm 是祖鲁（UTC）时区偏移量
“Z”是参考 UTC 时区

将时区添加到 UTC 时， result 是该时区的日期和时间。例如，2002-10-10T12：00：00+05：00 是 2002-10-10T07：00：00Z，2002-10-10T00：00：00+05：00 是 2002-10-09T19：00：00Z。请参阅 W3C XML 架构第 2 部分：DateTime 数据类型。dateTime

日期

使用格式指定字段。yyyy-MM-dddate

注意

不支持指定偏移量。date

状态代码和错误响应

当发生错误或响应成功时，响应标头包含 HTTP 代码，响应正文通常包含：

HTTP 响应代码
HTTP 响应代码附带的消息
发生错误的字段或对象（如果响应返回信息关于错误）

HTTP 响应代码	描述
200	“OK”成功代码，用于 GET、HEAD 和一些 PATCH 请求。
201	“创建”成功代码，用于 POST 请求和一些 PATCH 请求。
204	“无内容”成功代码，用于 DELETE 请求和一些 PATCH 请求。
300	外部 ID 时返回的值存在于多个记录中。响应正文包含列表的匹配记录。
304	请求内容未更改自指定日期和时间起。提供日期和时间在标题中。请参阅获取对象 Metatdata Changes 为例。`If-Modified-Since`
400	请求无法理解，通常是因为 JSON 或 XML 正文包含错误。
401	使用的会话 ID 或 OAuth 令牌具有已过期或无效。响应正文包含和。`messageerrorCode`
403	该请求已被拒绝。验证登录用户具有适当的权限。如果错误代码已REQUEST_LIMIT_EXCEEDED，则超出了 API 请求限制在您的组织中。
404	请求的资源不能是发现。检查 URI 是否存在错误，并验证是否没有共享问题。
405	中指定的方法不允许对 URI。
409	由于原因，请求无法完成与资源的当前状态发生冲突。检查 API 版本与你的资源兼容请求。
410	请求的资源已停用或删除。删除或更新对资源的任何引用。
412	请求未执行，因为或客户端在请求标头不满意。例如，请求包括 `一个 If-Unmodified-Since` 标头，但数据在指定日期之后被修改。
414	URI 的长度超过 16,384 字节限制。
415	请求中的实体位于指定不支持的格式方法。
420	Salesforce Edge 没有可用于此的路由信息请求主机。联系 Salesforce 客户支持。
428	请求未执行，因为它不是有条件的。添加以下一项条件请求标头，例如、和重新提交。`If-Match`
431	URI 和标头超过 16,384 字节的限制。
500	闪电网络中发生错误平台，因此无法完成请求。联系 Salesforce 客户支持。
502	Salesforce Edge 无法与 Salesforce 实例。
503	服务器无法处理请求。通常，如果服务器已关闭，则会出现此问题维护或超载。

不正确的 ID 示例在使用 JSON 或 XML 的请求中使用不存在的 ID （request_body.json 或 request_body.xml)

[
{
  "fields" : [ "Id" ],
  "message" : "Account ID: id value of incorrect type: 001900K0001pPuOAAU",
  "errorCode" : "MALFORMED_ID"
}
]

资源不存在请求不存在的资源，例如，您尝试创建一个使用拼写错误的对象进行记录名字

[
{
  "message" : "The requested resource does not exist",
  "errorCode" : "NOT_FOUND"
}
]

API 生命周期终止政策

查看哪些 REST API 版本受支持、不受支持或不可用。

Salesforce 承诺支持每个 API 版本至少 3 个自首次发布之日起的年。为了提高质量和性能 API，有时不再支持超过 3 年的版本。

Salesforce 通知使用计划的 API 版本的客户为折旧至少 1 年后，对版本的支持将结束。

Salesforce API 版本	版本支持状态	版本停用信息
版本 31.0 至 59.0	支持。
版本 21.0 至 30.0	截至 22 年夏季，这些版本已被弃用，并且没有 Salesforce 支持的时间更长。从 25 年夏季开始，这些版本将停用且不可用。	Salesforce Platform API 版本 21.0 到 30.0 停用
版本 7.0 至 20.0	自 22 年夏季起，这些版本已停用，并且不能利用的。	Salesforce Platform API 版本 7.0 到 20.0 停用

如果你请求任何资源或使用已停用的 API 版本 REST API 中的操作返回错误代码。410:GONE

识别从旧的或不受支持的 API 版本发出的请求，请使用 API 总使用量事件类型。

关于 REST API

REST API 发行说明

支持的版本和所需的权限

API 访问支持的版本

API 用户权限

REST 资源和请求

URI

HTTP 方法

头

请求机构

REST API 体系结构

通过连接的应用程序和 OAuth 2.0 进行授权

配置连接的应用程序

应用 OAuth 授权流程

更多资源

头

分配规则标头

标头字段名称和值

看涨期权标题

标头字段名称和值

例

压缩标头

请求压缩

响应压缩

条件请求标头

ETag （英语）

如果匹配

如果-无匹配

如果修改后

如果未修改，则自

重复的规则标头

标头字段名称和值

限制信息标题

标头字段名称和值

包版本标头

标头字段名称和值

查询选项标头

标头字段名称和值

警告标头

标头字段名称和值

例

使用 cURL 发送 REST 请求

附加请求正文

处理访问令牌中的感叹号

配置 Salesforce CORS 允许列表

有效的日期和日期时间格式

日期时间

日期

状态代码和错误响应

API 生命周期终止政策