Знакомство со службой REST в SharePointGet to know the SharePoint REST service

В SharePoint реализована служба передачи репрезентативного состояния (REST), сравнимая с уже имеющимися клиентскими объектными моделями.SharePoint introduces a Representational State Transfer (REST) service that is comparable to the existing SharePoint client object models. Теперь разработчики могут удаленно работать с данными SharePoint при помощи любой технологии, поддерживающей веб-запросы REST.Now, developers can interact remotely with SharePoint data by using any technology that supports REST web requests. Это означает, что разработчики могут выполнять операции создания, чтения, обновления и удаления (CRUD) из надстроек, решений и клиентских приложений для SharePoint, используя веб-технологии REST и стандартный синтаксис протокола OData (Open Data Protocol).</span>This means that developers can perform Create, Read, Update, and Delete (CRUD) operations from their SharePoint Add-ins, solutions, and client applications, using REST web technologies and standard Open Data Protocol (OData) syntax.

Необходимые условияPrerequisites

В этой статье предполагается, что у вас есть базовое представление о службе REST и создании запросов REST.This topic assumes you have a basic familiarity with REST and how to construct REST requests.

Принцип работы службы REST в SharePointHow the SharePoint REST service works

В SharePoint появилась возможность удаленной работы с сайтами SharePoint с помощью REST.SharePoint adds the ability for you to remotely interact with SharePoint sites by using REST. Теперь вы можете работать с объектами SharePoint напрямую, используя любую технологию, поддерживающую стандартные возможности REST.Now you can interact directly with SharePoint objects by using any technology that supports standard REST capabilities.

Для доступа к ресурсам SharePoint с помощью REST необходимо создать HTTP-запрос RESTful, используя стандарт OData, который соответствует нужному API клиентской объектной модели.To access SharePoint resources using REST, construct a RESTful HTTP request by using the OData standard, which corresponds to the desired client object model API. Примеры:For example:

Метод клиентской объектной модели:Client object model method:

List.GetByTitle(listname)

Конечная точка REST:REST endpoint:

http://server/site/_api/lists/getbytitle('listname')

Веб-служба client.svc в SharePoint обрабатывает HTTP-запрос и возвращает ответ в формате Atom или нотации объектов JavaScript (JSON).The client.svc web service in SharePoint handles the HTTP request, and serves the appropriate response in either Atom or JavaScript Object Notation (JSON) format. Затем клиентское приложение должно проанализировать этот ответ.Your client application must then parse that response. Ниже показано высокоуровневое представление архитектуры REST в SharePoint.The following figure shows a high-level view of the SharePoint REST architecture.

Архитектура службы REST в SharePointSharePoint REST service architecture

Архитектура службы REST в SharePoint

Благодаря функциональности и простоте использования этих клиентских объектных моделей разработчики чаще всего применяют их для обмена данными с сайтами SharePoint, используя управляемый код для .NET Framework, Silverlight или JavaScript.Because of the functionality and ease of use that client object models provide, they remain the primary development option for communicating with SharePoint sites by using .NET Framework managed code, Silverlight, or JavaScript.

Использование команд HTTP со службой REST в SharePointUse HTTP commands with the SharePoint REST service

Чтобы использовать возможности REST, встроенные в SharePoint, необходимо создать HTTP-запрос RESTful, используя стандарт OData, соответствующий нужному API клиентской объектной модели.To use the REST capabilities that are built into SharePoint, you construct a RESTful HTTP request by using the OData standard, which corresponds to the client object model API you want to use. Веб-служба client.svc обрабатывает HTTP-запрос и возвращает ответ в формате Atom или JSON.The client.svc web service handles the HTTP request and serves the appropriate response in either Atom or JSON format. Затем клиентское приложение должно проанализировать этот ответ.The client application must then parse that response.

Конечные точки в службе REST SharePoint соответствуют типам и элементам клиентских объектных моделей SharePoint. С помощью HTTP-запросов вы можете использовать эти конечные точки REST для выполнения типичных операций CRUD с сущностями SharePoint, такими как списки и сайты.The endpoints in the SharePoint REST service correspond to the types and members in the SharePoint client object models. By using HTTP requests, you can use these REST endpoints to perform typical CRUD operations against SharePoint entities, such as lists and sites.

ЗадачаIf you want to do this to an endpoint HTTP-запросUse this HTTP request ПримечанияKeep in mind
Чтение ресурсаRead a resource GETGET
Создание или обновление ресурсаCreate or update a resource POSTPOST
  • Для создания сущностей, например списков и сайтов, используйте POST.Use POST to create entities such as lists and sites.
  • Служба REST SharePoint поддерживает отправку команд POST, включающих определения объектов, к конечным точкам, представляющим коллекции.The SharePoint REST service supports sending POST commands that include object definitions to endpoints that represent collections.
  • При операциях POST для всех свойств, которые не являются необходимыми, устанавливаются их значения по умолчанию.For POST operations, any properties that are not required are set to their default values.
  • При попытке задать доступное только для чтения свойство в рамках операции POST служба возвращает исключение.If you attempt to set a read-only property as part of a POST operation, the service returns an exception.
Обновление или вставка ресурсаUpdate or insert a resource PUTPUT
  • С помощью операций PUT и MERGE можно обновлять существующие объекты SharePoint.Use PUT and MERGE operations to update existing SharePoint objects.
  • Любая конечная точка службы, представляющая операцию set для свойств объектов, поддерживает как запросы PUT, так и запросы MERGE.Any service endpoint that represents an object property set operation supports both PUT requests and MERGE requests.
  • В запросах MERGE задавать свойства необязательно. Все свойства, не заданные в явном виде, сохраняют свои текущие значения.For MERGE requests, setting properties is optional; any properties that you do not explicitly set retain their current property.
  • В запросах PUT, если не указать все обязательные свойства в обновлениях объекта, служба REST возвращает исключение.For PUT requests, if you do not specify all required properties in object updates, the REST service returns an exception.
  • Кроме того, всем необязательным свойствам, не заданным в явном виде, присваиваются значения по умолчанию.In addition, any optional properties you do not explicitly set are set to their default properties.
Удаление ресурсаDelete a resource DELETEDELETE
  • Используйте команду HTTP DELETE для определенного URL-адреса конечной точки, чтобы удалить объект SharePoint, представленный этой конечной точкой.Use the HTTP DELETE command against the specific endpoint URL to delete the SharePoint object represented by that endpoint.
  • В случае с объектами, пригодными для повторного использования, такими как списки, файлы и элементы списков, используется операция Recycle.In the case of recyclable objects, such as lists, files, and list items, this results in a Recycle operation.

Составление URL-адресов REST для доступа к ресурсам SharePointConstruct REST URLs to access SharePoint resources

Когда возможно, URI для этих конечных точек REST близко имитирует подпись API ресурса в клиентской объектной модели SharePoint. Главные точки входа для службы REST представляют семейство веб-сайтов и сайт указанного контекста.Whenever possible, the URI for these REST endpoints closely mimics the API signature of the resource in the SharePoint client object model. The main entry points for the REST service represent the site collection and site of the specified context.

Для доступа к определенному семейству веб-сайтов используйте следующую конструкцию:To access a specific site collection, use the following construction:

http://server/site/_api/site

Для доступа к определенному сайту используйте следующую конструкцию:To access a specific site, use the following construction:

http://server/site/_api/web

В обоих случаях server представляет имя сервера, а site — имя определенного сайта или путь к нему.In each case, server represents the name of the server, and site represents the name of, or path to, the specific site.

Начиная с этой отправной точки, вы можете составлять более конкретные URI REST, ''обходя" объектную модель с использованием имен API клиентской объектной модели, разделенных знаком косой черты (/).From this starting point, you can then construct more specific REST URIs by "walking" the object model, using the names of the APIs from the client object model separated by a forward slash (/).

Этот синтаксис неприменим к REST API SocialFeedManager и SocialFollowingManager.This syntax doesn't apply to the SocialFeedManager or SocialFollowingManager REST APIs. Дополнительные сведения см. в следующих статьях:For more information, see:

Дополнительные рекомендации по определению URI конечных точек REST в SharePoint на основе подписи соответствующих API клиентской объектной модели см. в этой статье.For more guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs, see Determine SharePoint REST service endpoint URIs.

Примеры конечных точек REST в SharePointSharePoint REST endpoint examples

В приведенной ниже таблице представлены типичные примеры URL-адресов конечных точек REST, которые помогут вам приступить к работе с данными SharePoint.The following table contains typical REST endpoint URL examples to get you started working with SharePoint data. Чтобы составить полный URL-адрес REST, добавьте строку http://server/site/_api/ в начале фрагментов URL-адресов, представленных в таблице.Prepend http://server/site/_api/ to the URL fragments shown in the table to construct a fully qualified REST URL. При необходимости для команд POST в таблице приводятся примеры данных, которые необходимо передать в тексте HTTP-запроса для создания указанного элемента SharePoint.Where necessary for POST commands, the table contains sample data you must pass in the HTTP request body to create the specified SharePoint item. Элементы в кавычках представляют переменные, вместо которых следует подставить свои значения.Items in quotes represent variables that you must replace with your values.

ОписаниеDescription Конечная точка URL-адресаURL endpoint Метод HTTPHTTP method Содержимое текстаBody content
Получает заголовок спискаRetrieves the title of a list web/title GETGET Не применимоNot applicable
Получает все списки на сайтеRetrieves all lists on a site lists GETGET НеприменимоNot applicable
Получает метаданные одного спискаRetrieves a single list's metadata lists/getbytitle('listname') GETGET Не применимоNot applicable
Получает элементы спискаRetrieves items within a list lists/getbytitle('listname')/items GETGET НеприменимоNot applicable
Получает определенное свойство документаRetrieves a specific property of a document
(в данном случае это заголовок документа)(in this case, the document title)
lists/getbytitle('listname')?select=Title GETGET Не применимоNot applicable
Создает списокCreates a list lists POSTPOST См. примерSee sample
Добавляет элемент в списокAdds an item to a list lists/getbytitle('listname')/items POSTPOST См. примерSee sample

Пример данных для создания списка: Creates a list sample data

{
  '__metadata': {
    'type': 'SP.List'
  },
  'AllowContentTypes': true,
  'BaseTemplate': 104 ,
  'ContentTypesEnabled': true,
  'Description': 'My list description ',
  'Title': 'RestTest '
}

Пример данных для добавления элемента в список: Adds an item to a list sample data

{
  '__metadata': {
    'type': 'SP.Data.listname.ListItem'
  },
  'Title': 'MyItem'
}

В приведенном выше фрагменте JSON замените строку listname на имя своего списка SharePoint, пропустив пробелы.In the above JSON, replace listname with the name of your SharePoint list by omitting the spaces.

Поддержка пакетных заданийBatch job support

Служба REST в SharePoint Online (а также локальной среде SharePoint 2016 или более поздней версии) поддерживает объединение нескольких запросов в один вызов службы с помощью параметра запроса OData $batch.The SharePoint Online (and on-premises SharePoint 2016 or later) REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. Подробные сведения и ссылки на примеры кода см. в этой статье.For details and links to code samples, see Make batch requests with the REST APIs.

Материалы по ODataOData resources

Статьи, посвященные службе REST в SharePointSharePoint REST service topics

Дополнительные сведения об использовании службы REST в SharePoint см. в перечисленных ниже ресурсах.To learn more about using the SharePoint REST service, use the following resources.

НазваниеTitle ОписаниеDescription
Выполнение базовых операций с использованием конечных точек REST SharePointComplete basic operations using SharePoint REST endpoints Узнайте, как выполнять операции CRUD (создание, чтение, обновление, удаление) с помощью интерфейса REST SharePoint.Perform basic create, read, update, and delete (CRUD) operations with the SharePoint REST interface.
Работа со списками и элементами списков в службе RESTWorking with lists and list items with REST Узнайте, как выполнять основные операции CRUD со списками и их элементами при помощи интерфейса REST SharePoint.Perform basic CRUD operations on lists and list items with the SharePoint REST interface.
Работа с папками и файлами в службе RESTWorking with folders and files with REST Узнайте, как выполнять основные операции CRUD с папками и файлами при помощи интерфейса REST SharePoint.Perform basic CRUD operations on folders and files with the SharePoint REST interface.
Навигация по структуре данных SharePoint, представленной в службе RESTNavigate the SharePoint data structure represented in the REST service Узнайте, как с помощью конечной точки REST в элементе SharePoint получить доступ к связанным элементам, например родительским сайтам или структуре библиотеки, в которой находится этот элемент.Start from a REST endpoint for a given SharePoint item, and navigate to and access related items, such as parent sites or the library structure where that item resides.
Определение URI конечных точек службы REST в SharePointDetermine SharePoint REST service endpoint URIs Общие рекомендации по определению URI конечных точек REST в SharePoint на основе подписей соответствующих API клиентской объектной модели.General guidelines for determining SharePoint REST endpoint URIs from the signature of the corresponding client object model APIs.
Использование операций запросов OData в запросах REST SharePointUse OData query operations in SharePoint REST requests Узнайте, как использовать широкий спектр операторов строки запроса OData для выбора, фильтрации и упорядочивания данных, запрашиваемых у службы REST SharePoint.Use a wide range of OData query string operators to select, filter, and order the data you request from the SharePoint REST service.
Отправка пакетных запросов с помощью интерфейсов REST APIMake batch requests with the REST APIs Узнайте, как объединить несколько запросов в один вызов службы REST.Combine multiple requests into a single call to the REST service.
Синхронизация элементов SharePoint с помощью службы RESTSynchronize SharePoint items using the REST service Узнайте, как синхронизировать элементы между SharePoint и надстройками или службами с помощью ресурса GetListItemChangesSinceToken, входящего в состав службы REST в SharePoint.Synchronize items between SharePoint and your add-ins or services by using the GetListItemChangesSinceToken resource, part of the SharePoint REST service.
Отправка файла с помощью REST API и jQueryUpload a file by using the REST API and jQuery В примерах кода в этой статье показано, как с помощью интерфейса REST и AJAX-запросов jQuery добавить локальный файл в библиотеку "Документы", а затем изменить свойства элемента списка, представляющего отправленный файл.The code examples in this article use the REST interface and jQuery AJAX requests to add a local file to the Documents library, and then change properties of the list item that represents the uploaded file.
Установка настраиваемых разрешений для списка с помощью интерфейса RESTSet custom permissions on a list by using the REST interface Сайты, списки и элементы списков SharePoint относятся к типу SecurableObject, наследующему разрешения от родительского объекта.SharePoint sites, lists, and list items are types of SecurableObject, which inherits the permissions of its parent. Чтобы задать особые разрешения для объекта, необходимо запретить ему наследовать разрешения от родительского объекта, а затем определить новые разрешения, добавив или удалив назначения ролей.To set custom permissions for an object, you need to break its inheritance so that it stops inheriting permissions from its parent, and then define new permissions by adding or removing role assignments.
Основные сведения о рабочих процессах SharePointSharePoint workflow fundamentals Узнайте, как добавлять функции поиска в клиентские и мобильные приложения с помощью службы REST поиска в SharePoint Server 2013 и любой технологии, поддерживающей веб-запросы REST.Add search functionality to client and mobile applications using the Search REST service in SharePoint Server 2013 and any technology that supports REST web requests.
Справочные материалы по REST API каналов социальных сетей для SharePointSocial feed REST API reference for SharePoint Конечные точки REST SharePoint для выполнения задач, связанных с каналами.SharePoint REST endpoints for feed-related tasks.
Справочные материалы по REST API отслеживания пользователей и контента для SharePointFollowing people and content REST API reference for SharePoint Конечные точки REST SharePoint для подписки на людей и контент.SharePoint REST endpoints for following people and content.
Разработка надстроек SharePointDevelop SharePoint Add-ins Здесь вы найдете подробные статьи и ресурсы, которые помогут вам расширить возможности своих надстроек SharePoint.Find in-depth articles and resources to help you build advanced capabilities into your SharePoint Add-ins.
Справочные материалы по REST API и примерыREST API reference and samples Полный справочник по API для работы с инструментами, службами и технологиями Майкрософт.Comprehensive API reference for working with Microsoft tools, services, and technologies. Здесь вы найдете подробный синтаксис, фрагменты кода и рекомендации по созданию приложений, разработке веб-сайтов и работе с облаком.Whether you're building apps, developing websites, or working with the cloud, you'll find detailed syntax, code snippets, and best practices.