Salesforce API（4）Bulk

学习目标

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

描述异步请求与同步请求的不同之处。
在Workbench中使用REST Explorer创建批量作业。
通过向作业添加数据将数据导入到您的Salesforce组织。
监控工作的进展。
得到一份工作的结果。

批量API和异步请求

批量API基于REST原则，并针对大量数据集进行了优化。您可以使用它来异步插入，更新，插入或删除多个记录，这意味着您提交一个请求并稍后返回结果。 Salesforce在后台处理请求。相反，SOAP和REST API使用同步请求，并针对一次更新几条记录的实时客户端应用程序进行了优化。您可以使用这两个API来处理许多记录，但是当数据集包含数十万条记录时，它们不太实用。批量API的异步框架旨在使处理从数千条到数百万条记录的数据变得简单高效。使用Bulk API最简单的方法是使用CSV文件在Data Loader中处理记录。使用Data Loader，您不必编写自己的客户端应用程序。有时候，独特的需求需要编写一个自定义的应用程序。 Bulk API可以让您将自己的轮子放在您自己的手中，并引导课程走向适合您的解决方案。对于本机，您使用称为批量API 2.0的较新版本的批量API。如果您想将本单元中学到的东西应用于之前支持的批量API版本，则需要使用不同的资源URI，并创建和管理批次以及作业。有关以前版本的Bulk API的更多信息，请参阅批量API开发人员指南。

将数据导入您的组织

要探索Bulk API，我们将使用Workbench创建一些帐户记录。

创建一个批量作业

批量API是基于REST的，因此我们可以使用Workbench的REST Explorer来制作批量API请求。

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

现在我们准备上传我们的数据了。第一步是创造一个工作。作业指定我们正在使用的操作和数据对象的类型。它起着一个桶的作用，我们添加数据进行处理。我们将使用/ jobs / ingest资源来创建一个工作。此资源也可用于获取当前作业的列表。为了创建一个工作，我们提交一个POST请求到/ jobs / ingest请求体内的作业属性。因为批量API是基于REST的，所以请求采用熟悉的REST请求形式，包含四个组件：URI，HTTP方法，头文件和正文。正如我们刚刚提到的，方法是POST。

对于URI，请将URI文本框中的文本替换为以下内容：/services/data/XX.0/jobs/ingest，其中XX.0对应于您正在使用的API版本。让我们注意一下这个URI的一些事情。

我们正在使用/ services / data，这是与REST API相同的端点。批量API使用与REST API使用的框架相同的框架，这意味着批量API支持许多相同的功能，例如OAuth认证。
与SOAP API类似，API版本号不包含v前缀。
/jobs/ingest 表示我们正在访问创建批量API作业的资源。

对于请求正文，请复制并粘贴以下文本。

{
  "operation" : "insert",
  "object" : "Account",
  "contentType" : "CSV",
  "lineEnding" : "CRLF"
}

您的REST资源管理器看起来像这样。

点击 Execute 并签出响应。

答复包括各种有关工作的属性，其中大部分现在对我们没有用处，因为我们还没有添加数据。虽然我们要注意一些属性。查看作业ID（id）并将其复制到文本文件中。我们用它来将数据添加到作业中，并检查作业的状态。还要检查州属性。创建作业时，立即将其设置为打开状态。这意味着它已经准备好开始接收数据。最后，看看contentUrl属性。该属性显示我们用来加载作业数据的URL。

将数据添加到作业

现在我们可以将帐户数据插入我们的工作。作业的数据作为PUT请求中的一组记录发送到服务器。服务器处理记录集，确定将数据加载到Salesforce中的最佳方式。你所要做的就是上传数据。

在Workbench中创建一个新的请求。将URI文本框中的文本替换为以下内容: /services/data/XX.0/jobs/ingest/jobID/batches. 用您复制的作业ID替换jobID。对于HTTP方法，请选择PUT。

对于这个例子，我们添加一组只有四个客户的记录。通常情况下，您使用Bulk API来添加数千或数百万条记录，但原理是一样的。将以下CSV文本复制到请求正文中。

"Name"
"Sample Bulk API Account 1"
"Sample Bulk API Account 2"
"Sample Bulk API Account 3"
"Sample Bulk API Account 4"

单击 Headers 并将Content-Type更改为 text/csv. 你的请求看起来像这样。

点击 Execute.

响应仅包含状态码201（已创建），表示Salesforce已成功接收作业数据。

关闭工作

现在我们已经提交了数据，我们需要让Salesforce知道是时候处理数据了。通过将作业状态从“打开”更改为“上传完成”来完成此操作。将URI文本框中的文本替换为以下内容： /services/data/XX.0/jobs/ingest/jobID. 同样，将XX替换为您正在使用的API版本，并使用作业ID替换jobID。对于HTTP方法，选择PATCH。点击Headers并将Content-Type设置为application / json。在请求正文中，将文本替换为以下JSON文本。

{
   "state" : "UploadComplete"
}

检查作业的状态

我们已经提交了数据。我们让Salesforce知道我们已经完成上传数据。现在由服务器来处理请求。我们可以通过API或通过Salesforce UI检查作业的状态来监视服务器的进度。在Salesforce中，从“设置”中，在“快速查找”框中输入 Bulk Data Load Jobs. 然后选择批量数据加载作业。您可以在此页面上检查作业的状态。或者，您可以单击工作ID来检查状态并获得该工作的详细结果。

在API中，我们使用 /jobs/ingest/jobID 资源来监视作业。将URI文本框中的文本替换为以下内容： /services/data/XX.0/jobs/ingest/jobID, 并使用通常的替换。对于HTTP方法，请选择GET。

点击 Execute. 你看到这样的东西。

如果您的状态仍然是UploadComplete而不是JobComplete，则Salesforce仍在处理该作业。别担心，它会在几分钟内处理完毕。同时，当你回来的时候，去对待一杯美酒，再次尝试同样的要求。如果你很幸运，你的工作已经完成，继续取回工作结果，或者随时都可以休息一下。

获得工作结果

一旦作业处于JobComplete状态（或失败状态），我们就可以以成功和失败的处理记录的形式获取结果信息。我们先看看成功处理的记录。在Workbench的REST资源管理器中，将URI文本框中的文本替换为以下内容：/services/data/XX.0/jobs/ingest/jobID/successfulResults, 并使用通常的替换。对于HTTP方法，请选择GET。

点击 Execute. 你看到这样的东西。

Salesforce将返回一个CSV，其中包含已成功处理的作业中的所有记录的列表。在这个模块中，我们创建了多个Account记录。 CSV数据包含创建的记录的记录标识，sf__Created列的值为true。偶尔有些记录不能被处理。也许这个工作试图创建已经存在的账户记录。也许工作数据缺少一些必填字段。在这些情况下，我们可以向Salesforce询问处理过程中出现错误的记录列表，以及有关错误的更多信息。返回到REST资源管理器，将URI文本框中的文本替换为以下内容：

/services/data/XX.0/jobs/ingest/jobID/failedResults, 并使用通常的替换。对于HTTP方法，请选择GET。

点击 Execute. 结果看起来像这样。

Salesforce提供一个CSV，其中包含处理期间遇到错误的记录列表以及记录标识和错误消息。在这种情况下，所有记录都成功插入，所以记录列表是空的。整齐的工作，队长！