Отправка пакетных запросов с использованием REST APIMake batch requests with the REST APIs

В этой статье описано выполнение пакетных запросов и операций при использовании REST API или OData API для Microsoft SharePoint Online (и локальной среды SharePoint 2016 и более поздних версий), а также при использовании подмножества файлов и папок REST API для Office 365.This article describes how you can batch queries and operations against the REST/OData API of Microsoft SharePoint Online (and on-premises SharePoint 2016 and later) and the Files and folders subset of the Office 365 REST APIs. С помощью этой методики вы можете повысить производительность надстройки, совместив множество операций в одном запросе к серверу и одном отклике.With this technique, you can improve the performance of your add-in by combining many operations into a single request to the server and a single response back.

Краткий обзор параметра $batchExecutive summary of the $batch option

В SharePoint Online (и локальной среде SharePoint 2016 и более поздних версий), а также API Office 365 реализован параметр запроса OData $batch, поэтому вы можете следовать указаниям по его использованию из официальной документации.SharePoint Online (and on-premises SharePoint 2016 and later) and the Office 365 APIs implement the OData $batch query option, so you can rely on the official documentation for details about how to use it. Кроме того, вы можете ознакомиться с этой темой в блоге Andrew Connell. Начните с записи Часть 1. Пакетные запросы REST API в SharePoint.(Another option is to see Andrew Connell's blog posts on the subject beginning at Part 1 - SharePoint REST API Batching.)

Напомним о некоторых важных факторах:The following is a reminder of the major points:

  • URL-адрес запроса состоит из URL-адреса корневой службы и параметра $batch (например, https://fabrikam.sharepoint.com/_api/$batch или https://fabrikam.office365.com/api/v1.0/me/$batch).The request URL consists of the root service URL and the $batch option; for example, https://fabrikam.sharepoint.com/_api/$batch or https://fabrikam.office365.com/api/v1.0/me/$batch.
  • Тело HTTP-запроса относится к типу MIME multipart/mixed.The HTTP request body is MIME type multipart/mixed.
  • Текст запроса делится на части, отделенные друг от друга граничной строкой, которая указывается в заголовке запроса.The body of the request is divided into parts that are separated from each other by a boundary string that is specified in the header of the request.
  • У каждой части этого тела запроса есть команда HTTP и URL-адрес REST, а также внутреннее тело, если это применимо.Each part of the body has its own HTTP verb and REST URL, and its own internal body when applicable.
  • Такая часть может представлять собой операцию чтения (либо вызов функции) или объект ChangeSet из одной или нескольких операций записи (либо вызовов функций).A part can be a read operation (or function invocation), or a ChangeSet of one or more write operations (or function invocations). Объект ChangeSet относится к типу MIME multipart/mixed с дочерними частями, содержащими операции вставки, обновления или удаления.A ChangeSet is itself a MIME type multipart/mixed with subparts that contain insert, update, or delete operations.

Важно!

Интерфейсы API для SharePoint и Office 365 не являются транзакционными и не поддерживают функции "все или ничего" объектов ChangeSet, содержащих несколько операций.SharePoint and Office 365 APIs aren't transactional and don't support "all or nothing" functionality for ChangeSets that have more than one operation within them. В случае сбоя какой-либо из дочерних операций остальные операции выполняются без отката.If any of the child operations fails, the others still complete and aren't rolled back.

Примеры кодаCode samples

Примеры кода, в котором используется параметр запроса $batch для интерфейсов REST API или OData API SharePoint:Samples of code that uses the $batch query option against the SharePoint REST/OData APIs:

Примеры запросов и откликовExample requests and responses

Ниже приведен пример необработанного HTTP-запроса, который пакетно обрабатывает две операции GET, которые извлекают названия всех элементов в двух разных списках.The following is an example of a raw HTTP request that batches two GET operations that retrieve the titles of all the items in two different lists.

POST https://fabrikam.sharepoint.com/_api/$batch HTTP/1.1
Authorization: Bearer <access token omitted>
Content-Type: multipart/mixed; boundary=batch_e3b6819b-13c3-43bb-85b2-24b14122fed1
Host: fabrikam.sharepoint.com
Content-Length: 527
Expect: 100-continue

--batch_e3b6819b-13c3-43bb-85b2-24b14122fed1
Content-Type: application/http
Content-Transfer-Encoding: binary

GET https://fabrikam.sharepoint.com/_api/Web/lists/getbytitle('Composed%20Looks')/items?$select=Title HTTP/1.1

--batch_e3b6819b-13c3-43bb-85b2-24b14122fed1
Content-Type: application/http
Content-Transfer-Encoding: binary

GET https://fabrikam.sharepoint.com/_api/Web/lists/getbytitle('User%20Information%20List')/items?$select=Title HTTP/1.1

--batch_e3b6819b-13c3-43bb-85b2-24b14122fed1--

Ниже приведен пример текста необработанного HTTP-запроса, который пакетно обрабатывает операцию DELETE для списка и операцию GET для списка списков SharePoint.The following is an example of the body of a raw HTTP request that batches a DELETE of a list and a GET of the SharePoint list-of-lists.

POST https://fabrikam.sharepoint.com/_api/$batch HTTP/1.1
Authorization: Bearer <access token omitted>
Content-Type: multipart/mixed; boundary=batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e
Host: fabrikam.sharepoint.com
Content-Length: 647
Expect: 100-continue

--batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e
Content-Type: multipart/mixed; boundary=changeset_efb6b37c-a5cd-45cb-8f5f-4d648006e65d

--changeset_efb6b37c-a5cd-45cb-8f5f-4d648006e65d
Content-Type: application/http
Content-Transfer-Encoding: binary

DELETE https://fabrikam.sharepoint.com/_api/Web/lists/getbytitle('OldList') HTTP/1.1
If-Match: "1"

--changeset_efb6b37c-a5cd-45cb-8f5f-4d648006e65d--
--batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e
Content-Type: application/http
Content-Transfer-Encoding: binary

GET https://fabrikam.sharepoint.com/_api/Web/lists HTTP/1.1

--batch_7ba8d60b-efce-4a2f-b719-60c27cc0e70e--

Библиотеки ODataOData libraries

Библиотеки OData, поддерживающие пакетные запросы OData для множества языков.OData libraries support OData batching for many languages. Ниже приведены два примера.Following are two examples. Более полный список см. на странице Библиотеки OData.For a more complete list, see OData Libraries.

См. такжеSee also