Salesforce API（2）REST

学习目标

完成本单元后，您将能够：

登录到Workbench并导航到REST Explorer。
使用描述资源。
使用REST API创建一个帐户。
使用REST API执行查询。

REST资源和方法

登陆！队长之前，我们已经看到了REST岛。在我们停靠并开始使用API之前，让我们来谈谈REST资源和方法。 REST资源是一条信息或某个操作（如单个数据记录，一组记录或一个查询）的抽象。 REST API中的每个资源都由一个已命名的统一资源标识符（URI）标识，并使用标准的HTTP方法（HEAD，GET，POST，PATCH，DELETE）进行访问。 REST API基于资源的使用情况，它们的URI以及它们之间的链接。

您使用资源与您的Salesforce组织进行交互。例如，您可以：

检索有关可用的API版本的摘要信息。
获取有关Salesforce对象的详细信息，例如帐户，用户或自定义对象。
执行查询或搜索。
更新或删除记录。

REST请求包含四个组件：资源URI，HTTP方法，请求标头和请求主体。请求标头指定请求的元数据。请求主体在需要时指定请求的数据。如果没有要指定的数据，则请求中将省略正文。

描述客户对象

现在是时候弄湿我们的脚了。我们将使用Workbench进行一些API调用。 Workbench是一套通过API与您的Salesforce组织进行交互的工具。因为您可以从任何HTTP发件人发出REST请求，所以还有其他许多工具可供您使用（例如，检出cURL或Postman）。但是，由于Workbench为Salesforce API提供了一个友好的框架，因此在您准备开始全面集成之前，这是一个完美的方式。

第一步是登录Workbench。

登录到您的Trailhead DE组织并导航到Workbench。
对于环境，请选择 Production.
对于API版本，请选择可用的最高编号。
确保您选择 I agree to the terms of service.
点击 Login with Salesforce.

您已经到达Workbench主页。对于这个模块，我们只使用Workbench的许多工具之一，即REST资源管理器。

在顶部菜单中，选择 utilities | REST Explorer.

您可以从REST资源管理器调用REST API调用，就像从任何其他HTTP接口调用一样。文本框中的文本表示资源URI。为了方便起见，显示的URI中省略了顶级域名。例如，预填充到URI文本框中的资源的完整URI是https://foo.my.salesforce.com/services/data/v36.0。 URI上方的单选按钮表示标准的HTTP方法。要进行API调用，请输入资源URI，选择适当的方法，根据需要添加标题，然后单击 Execute. 我们来试试SObject Describe资源。此资源与GET方法结合使用时，将返回有关对象及其字段的元数据。我们将尝试描述Account对象。将URI文本框中的现有文本替换为/services/data/vXX.0/sobjects/account/describe，其中XX映射到您正在使用的API版本。

让我们花一分钟来分解这个资源的URI。

/services/data—指定我们正在发出一个REST API请求
/v36.0—API版本号
/sobjects—指定我们正在访问sObject分组下的资源
/account—sObject被执行;在这种情况下，客户
/describe—Action; 在这种情况下，描述请求

现在确保选择GET方法，然后单击 Execute.

Response after we describe the account object

好的工作，队长。客户元数据出现在屏幕上。 Workbench已经很好地格式化了响应。要查看原始JSON响应，请单击 Show Raw Response.

JSON response after we describe the account object

帐户元数据以JSON形式显示在某些HTTP响应标头下方。因为REST API同时支持JSON和XML，所以让我们更改请求头以指定XML响应。在HTTP方法旁边，单击标题。对于Accept头值，将application / json替换为application / xml。您的请求标题看起来像这样。

点击 Execute。原始的XML响应被返回。欢呼！

创建一个客户

现在让我们使用SObject资源和POST方法创建一个帐户。在URI文本框中，将现有文本替换为/services/data/vXX.0/sobjects/account，其中XX映射到您正在使用的API版本。选择POST。请注意，出现了请求正文文本区域，这是我们为新帐户指定字段值的位置。首先，让我们把Accept头改回JSON。

点击 Headers. 将Accept：application / xml改为Accept：application / json。你的请求看起来像这样。

在请求正文中，输入以下文本。

{
  "Name" : "NewAccount1",
  "ShippingCity" : "San Francisco"
}

Successful account creation response in REST API

如果 success: true,则使用返回的ID创建帐户。展开错误文件夹以检查错误。

只是开球，让我们创建第二个帐户，而不指定帐户名称。将请求正文中的文本替换为以下文本。

{
  "ShippingCity" : "San Francisco"
}

哦，哦。您是否收到REQUIRED_FIELD_MISSING个响应？展开REQUIRED_FIELD_MISSING文件夹，然后展开字段文件夹。您的扩展响应如下所示。

We get an error when we don't provide an account name

由于名称是创建帐户的必填字段，因此服务器不处理请求，并且收到错误。谢天谢地，我们需要修复请求的所有信息都在错误响应中。让我们指定名称NewAccount2，然后在请求正文中更改运输城市。将请求正文中的文本替换为以下文本。

{
  "Name" : "NewAccount2",
  "ShippingCity" : "New York"
}

执行查询

现在让我们想象一下，您或其他用户创建了数百个帐户。您想要查找航运城市是旧金山的所有帐户的名称。您可以使用查询资源执行SOQL查询，并根据需要输入确切的记录，就像定制的宝藏地图一样。/services/data/vXX.0/query/?q=SELECT+Name+From+Account+WHERE+ShippingCity='San+Francisco', 其中XX映射到：用以下文字替换URI文本框中的文本您正在使用的API版本。

我们用查询字符串中的+字符替换空格，以正确编码URI。您可以从参考资料部分的链接阅读HTML URL编码。确保选择了GET方法，然后单击 Execute.

展开记录文件夹。您是否看到一个名为我们创建的第一个帐户NewAccount1的文件夹？大。点击它。现在点击属性文件夹。 url旁边是返回的帐户的资源URI。你的回应看起来像这样。

Query response returns one account record

当您编写集成时，您可以从响应中获取该URI以访问有关该帐户的更多详细信息。

Node.js和Ruby示例

现在，您对REST API的可能性有了一个甜头。当然，当您从Workbench转到编写代码时，您将使用您选择的编程语言与REST API进行交互。幸运的是，专业的Salesforce开发人员已经为几种语言编写了包装器，简化了使用REST API的过程。以下是分别使用包装器Nforce和Restforce在Node.js和Ruby中编写的两个示例查询。

使用Nforce的Node.js示例

var nforce = require('nforce');

// 创建与Salesforce连接的应用程序的连接
var org = nforce.createConnection({
  clientId: process.env.CLIENT_ID,
  clientSecret: process.env.CLIENT_SECRET,
  redirectUri: process.env.CALLBACK_URL,
  mode: 'single'
});

// 认证并返回OAuth令牌
org.authenticate({
  username: process.env.USERNAME,
  password: process.env.PASSWORD+process.env.SECURITY_TOKEN
}, function(err, resp){
  if (!err) {
    console.log('Successfully logged in! Cached Token: ' + org.oauth.access_token);
    // 执行查询
    org.query({ query: 'select id, name from account limit 5' }, function(err, resp){
      if(!err && resp.records) {
        // 输出帐户名称
        for (i=0; i<resp.records.length;i++) {
          console.log(resp.records[i].get('name'));
        }
      }
    });
  }
  if (err) console.log(err);
});

使用Restforce的Ruby示例

require 'restforce'

// 创建与Salesforce连接的应用程序的连接
client = Restforce.new :username => ENV['USERNAME'],
  :password       => ENV['PASSWORD'],
  :security_token => ENV['SECURITY_TOKEN'],
  :client_id      => ENV['CLIENT_ID'],
  :client_secret  => ENV['CLIENT_SECRET']

// 执行查询
accounts = client.query("select id, name from account limit 5")

// 输出帐户名称
accounts.each do |account|
  p account.Name
end