使用 Web API 执行批处理操作

项目
10/31/2017

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

使用批处理操，可以将多个操作组合到一个 HTTP 请求中。

在本主题中

何时使用批处理请求

批处理请求

变更集

示例

何时使用批处理请求

批处理请求提供的值可以包括变更集，其提供将多个成功或失败操作绑定为组的方法。在事务中与其他可以使用 Web API 执行的操作相比较，在没有某个对象模型来包括对象的序列化或更深入理解 HTTP 协议的情况下，它们更难以撰写，因为请求正文基本上是必须与极为特定的要求匹配的文本文档。

请记住，比起使用批处理请求，在单个操作中可以更轻松地创建关联的实体。在彼此不关联的实体上执行操作时，以及必须在单个事务操作中执行所有操作时，使用批处理请求的效果最好。

另外，返回的响应基本上是文本文档，而不是可以轻松解析为 JSON 的对象。您需要解析响应中的文本或找到帮助程序库来访问响应中的数据。

批处理请求

使用 POST 请求可提交包含多个请求的批处理操作。批处理请求可以包括 GET 请求和变更集。若要使用批处理请求的事务功能，仅将更改数据的操作可包括在变更集内。GET 请求不得包括在变更集内。

包含批处理的 POST 请求必须具有 Content-Type 标头，其中一个值设置为 multipart/mixed，一个边界设置为使用此模式包括批处理的标识符：

--batch_<unique identifier>

唯一标识符不必是 GUID，但应该是唯一的。批处理中的每个项目都必须在前面带有批处理标识符，包含类似以下内容的 Content-Type 和 Content-Transfer-Encoding 标头：

--batch_WKQS9Yui9r
Content-Type: application/http
Content-Transfer-Encoding:binary

批处理的末尾必须包含类似以下内容的终止指示符：

--batch_WKQS9Yui9r--

备注

Web API 不支持 odata.continue-on-error 首选项。批处理中发生的任何错误都将停止批处理其余部分的处理。

变更集

当多个操作包含在变更集内时，所有操作将被视为原子，这意味着，如果其中某个操作失败，任何已完成的操作都将回滚。与批处理请求类似，变更集必须具有 Content-Type 标头，其中一个值设置为 multipart/mixed，一个边界设置为使用此模式包括变更集的标识符：

--changeset_<unique identifier>

唯一标识符不必是 GUID，但应该是唯一的。变更集中的每个项目都必须在前面带有变更集标识符，包含类似以下内容的 Content-Type 和 Content-Transfer-Encoding 标头：

--changeset_BBB456
Content-Type: application/http
Content-Transfer-Encoding:binary

变更集还可以包括具有唯一值的 Content-ID 标头。此值在前面带有 $ 时表示一个包含该操作中创建的所有实体的 Uri 的变量。例如，当您设置值 1 时，可以在变更集的后面部分使用 $1 来引用该实体。

变更集的末尾必须包含类似以下内容的终止指示符：

--changeset_BBB456--

示例

以下示例包含具有唯一标识符 AAA123 的批处理，以及具有唯一标识符 BBB456 的变更集。

在变更集内，使用 POST 创建了两个任务并使其与 accountid = 00000000-0000-0000-000000000001 的现有客户相关联。

最后，GET 请求包括在变更集之外，以返回全部六个与该客户关联的任务，包括两个在批处理请求中创建的任务。

请求

POST cc_WebAPI_ServiceURI/$batch HTTP/1.1
Content-Type: multipart/mixed;boundary=batch_AAA123
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

--batch_AAA123
Content-Type: multipart/mixed;boundary=changeset_BBB456

--changeset_BBB456
Content-Type: application/http
Content-Transfer-Encoding:binary
Content-ID: 1

POST cc_WebAPI_ServiceURI/tasks HTTP/1.1
Content-Type: application/json;type=entry

{"subject":"Task 1 in batch","regardingobjectid_account_task@odata.bind":"cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)"}
--changeset_BBB456
Content-Type: application/http
Content-Transfer-Encoding:binary
Content-ID: 2

POST cc_WebAPI_ServiceURI/tasks HTTP/1.1
Content-Type: application/json;type=entry

{"subject":"Task 2 in batch","regardingobjectid_account_task@odata.bind":"cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)"}
--changeset_BBB456--

--batch_AAA123
Content-Type: application/http
Content-Transfer-Encoding:binary

GET cc_WebAPI_ServiceURI/accounts(00000000-0000-0000-000000000001)/Account_Tasks?$select=subject HTTP/1.1
Accept: application/json

--batch_AAA123--

响应

--batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f
Content-Type: multipart/mixed; boundary=changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc

--changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 1

HTTP/1.1 204 No Content
OData-Version: 4.0
Location: cc_WebAPI_ServiceURI/tasks(a59c24f3-fafc-e411-80dd-00155d2a68cb)
OData-EntityId: cc_WebAPI_ServiceURI/tasks(a59c24f3-fafc-e411-80dd-00155d2a68cb)


--changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 2

HTTP/1.1 204 No Content
OData-Version: 4.0
Location: cc_WebAPI_ServiceURI/tasks(a69c24f3-fafc-e411-80dd-00155d2a68cb)
OData-EntityId: cc_WebAPI_ServiceURI/tasks(a69c24f3-fafc-e411-80dd-00155d2a68cb)


--changesetresponse_ff83b4f1-ab48-430c-b81c-926a2c596abc--
--batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#tasks(subject)","value":[
    {
      "@odata.etag":"W/\"474122\"","subject":"Task Created with Test Account","activityid":"919c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474125\"","subject":"Task 1","activityid":"a29c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474128\"","subject":"Task 2","activityid":"a39c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474131\"","subject":"Task 3","activityid":"a49c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474134\"","subject":"Task 1 in batch","activityid":"a59c24f3-fafc-e411-80dd-00155d2a68cb"
    },{
      "@odata.etag":"W/\"474137\"","subject":"Task 2 in batch","activityid":"a69c24f3-fafc-e411-80dd-00155d2a68cb"
    }
  ]
}
--batchresponse_c1bd45c1-dd81-470d-b897-e965846aad2f--

另请参阅

使用 Web API 执行操作
 撰写 HTTP 请求并处理错误
 使用 Web API 查询数据
 使用 Web API 创建实体
 使用 Web API 检索实体
 使用 Web API 更新和删除实体
 使用 Web API 关联和解除关联实体
 使用 Web API 功能
 使用 Web API 操作
 使用 Web API 模拟其他用户
 使用 Web API 执行条件操作

Microsoft Dynamics 365

通过

使用 Web API 执行批处理操作

在本主题中

何时使用批处理请求

批处理请求

变更集

示例

另请参阅

其他资源