Знакомство со службой REST в SharePoint

В SharePoint реализована служба передачи репрезентативного состояния (REST), сравнимая с уже имеющимися клиентскими объектными моделями. Теперь разработчики могут удаленно работать с данными SharePoint при помощи любой технологии, поддерживающей веб-запросы REST. Это означает, что разработчики могут выполнять операции создания, чтения, обновления и удаления (CRUD) из надстроек, решений и клиентских приложений для SharePoint, используя веб-технологии REST и стандартный синтаксис протокола OData (Open Data Protocol).

Необходимые компоненты

В этой статье предполагается, что у вас есть базовое представление о службе REST и создании запросов REST.

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

В SharePoint появилась возможность удаленной работы с сайтами SharePoint с помощью REST. Теперь вы можете взаимодействовать непосредственно с объектами SharePoint, используя любую технологию, поддерживающую стандартные возможности REST.

Для доступа к ресурсам SharePoint с помощью REST необходимо создать HTTP-запрос RESTful, используя стандарт OData, который соответствует нужному API клиентской объектной модели. Например:

CSOM

var items = List.GetByTitle(listname).GetItems();

HTTP

GET https://{site_url}/_api/lists/getbytitle('{list_name}')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Веб-служба client.svc в SharePoint обрабатывает HTTP-запрос и возвращает отклик в формате Atom или нотации объектов JavaScript (JSON). Затем клиентское приложение должно проанализировать этот ответ. Ниже показано высокоуровневое представление архитектуры REST в SharePoint.

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

Благодаря функциональности и простоте использования этих клиентских объектных моделей разработчики чаще всего применяют их для обмена данными с сайтами SharePoint, используя .NET Framework, Silverlight (теперь не рекомендуется) или JavaScript (JSOM).

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

Чтобы использовать возможности REST, встроенные в SharePoint, необходимо создать HTTP-запрос RESTful, используя стандарт OData, соответствующий нужному API клиентской объектной модели. Веб-служба client.svc обрабатывает HTTP-запрос и возвращает ответ в формате Atom или JSON. Затем клиентское приложение должно проанализировать этот ответ.

Конечные точки в службе REST SharePoint соответствуют типам и элементам клиентских объектных моделей SharePoint. С помощью HTTP-запросов вы можете использовать эти конечные точки REST, чтобы выполнять типичные операции CRUD с объектами SharePoint, такими как списки и сайты.

Задача	HTTP-запрос	Примечания
Чтение ресурса	GET
Создание или обновление ресурса	POST	Для создания сущностей, например списков и сайтов, используйте POST. Служба REST SharePoint поддерживает отправку команд POST, включающих определения объектов, к конечным точкам, представляющим коллекции. В операциях POST для всех необязательных свойств задаются значения по умолчанию. При попытке задать доступное только для чтения свойство в рамках операции POST служба возвращает исключение.
Обновление или вставка ресурса	PUT	С помощью операций PUT и MERGE можно обновлять существующие объекты SharePoint. Любая конечная точка службы, представляющая операцию set для свойств объектов, поддерживает как запросы PUT, так и запросы MERGE. Для запросов MERGE задавать свойства необязательно. Все свойства, не заданные в явном виде, сохраняют свои текущие значения. Для запросов PUT, если все обязательные свойства в обновлениях объекта не указаны, служба REST возвращает исключение. Кроме того, всем необязательным свойствам, не заданным в явном виде, присваиваются значения по умолчанию.
Удаление ресурса	DELETE	Используйте команду HTTP DELETE для определенного URL-адреса конечной точки, чтобы удалить объект SharePoint, представленный этой конечной точкой. Для объектов, поддерживающих повторное использование (таких как списки, файлы и элементы списков), используется операция Recycle.

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

Когда возможно, URI для этих конечных точек REST близко имитирует подпись API ресурса в клиентской объектной модели SharePoint. Главные точки входа для службы REST представляют семейство веб-сайтов и сайт указанного контекста.

Для доступа к определенному семейству веб-сайтов используйте следующую конструкцию:

https://{site_url}/_api/site

Для доступа к определенному сайту используйте следующую конструкцию:

https://{site_url}/_api/web

В обоих случаях server представляет имя сервера, а site — имя определенного сайта или путь к нему.

Начиная с этой отправной точки, вы можете составлять более конкретные URI REST, ''обходя" объектную модель с использованием имен API клиентской объектной модели, разделенных знаком косой черты (/).

Этот синтаксис неприменим к REST API SocialFeedManager и SocialFollowingManager. Дополнительные сведения см. в следующих статьях:

• Справочные материалы по REST API каналов социальных сетей для SharePoint
• Справочные материалы по REST API отслеживания пользователей и контента для SharePoint

Дополнительные рекомендации по определению URI конечных точек REST в SharePoint на основе подписи соответствующих API клиентской объектной модели см. в этой статье.

Примеры конечных точек REST в SharePoint

В приведенной ниже таблице представлены типичные примеры URL-адресов конечных точек REST, которые помогут вам приступить к работе с данными SharePoint. Чтобы составить полный URL-адрес REST, добавьте строку http://server/site/_api/ в начале фрагментов URL-адресов, представленных в таблице. При необходимости для команд POST в таблице приводятся примеры данных, которые необходимо передать в тексте HTTP-запроса для создания указанного элемента SharePoint. Элементы в кавычках представляют переменные, вместо которых следует подставить свои значения.

Описание	Конечная точка URL-адреса	Метод HTTP	Основное содержимое
Получает заголовок сайта	web/title	GET	Не применимо
Получает все списки на сайте	lists	GET	Неприменимо
Получает метаданные одного списка	lists/getbytitle('listname')	GET	Не применимо
Получает элементы списка	lists/getbytitle('listname')/items	GET	Неприменимо
Получает определенное свойство списка (в данном случае это заголовок списка)	lists/getbytitle('listname')?select=Title	GET	Не применимо
Создает список	lists	POST	См. пример
Добавляет элемент в список	lists/getbytitle('listname')/items	POST	См. пример

Пример данных для создания списка:

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

Пример данных для добавления элемента в список:

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

В приведенном выше фрагменте JSON замените строку listname на имя своего списка SharePoint, пропустив пробелы.

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

Служба REST в SharePoint Online (а также локальной среде SharePoint 2016 или более поздней версии) поддерживает объединение нескольких запросов в один вызов службы с помощью параметра запроса OData $batch. Подробные сведения и ссылки на примеры кода см. в статье Отправка пакетных запросов с помощью интерфейсов REST API.

Материалы по OData

• Разработка сервисноориентированных приложений с помощью WCF
• Open Data Protocol
• Соглашения об URI для протокола OData
• Адресация для операций службы
• Операции протокола OData
• Условия ошибок

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

Дополнительные сведения об использовании службы REST в SharePoint см. в перечисленных ниже ресурсах.

Название	Описание
Выполнение базовых операций с использованием конечных точек REST SharePoint	Узнайте, как выполнять операции CRUD (создание, чтение, обновление, удаление) с помощью интерфейса REST SharePoint.
Работа со списками и элементами списков в службе REST	Узнайте, как выполнять основные операции CRUD со списками и их элементами при помощи интерфейса REST SharePoint.
Работа с папками и файлами в службе REST	Узнайте, как выполнять основные операции CRUD с папками и файлами при помощи интерфейса REST SharePoint.
Навигация по структуре данных SharePoint, представленной в службе REST	Начните с конечной точки REST для определенного элемента SharePoint и перейдите и получите доступ к связанным элементам, например родительским сайтам или структуре библиотеки, в которой находится этот элемент.
Определение универсальных кодов ресурсов (URI) конечных точек службы SharePoint REST	Общие рекомендации по определению URI конечных точек REST в SharePoint на основе подписей соответствующих API клиентской объектной модели.
Использование операций запросов OData в запросах REST SharePoint	Узнайте, как использовать широкий спектр операторов строки запроса OData для выбора, фильтрации и упорядочивания данных, запрашиваемых у службы REST SharePoint.
Отправка пакетных запросов с помощью интерфейсов REST API	Узнайте, как объединить несколько запросов в один вызов службы REST.
Синхронизация элементов SharePoint с помощью службы REST	Узнайте, как синхронизировать элементы между SharePoint и надстройками или службами с помощью ресурса GetListItemChangesSinceToken, входящего в состав службы REST в SharePoint.
Отправка файла с помощью REST API и jQuery	В примерах кода в этой статье показано, как с помощью интерфейса REST и AJAX-запросов jQuery добавить локальный файл в библиотеку "Документы", а затем изменить свойства элемента списка, представляющего отправленный файл.
Установка настраиваемых разрешений для списка с помощью интерфейса REST	Сайты, списки и элементы списков SharePoint относятся к типу SecurableObject, наследующему разрешения от родительского объекта. Чтобы задать особые разрешения для объекта, необходимо запретить ему наследовать разрешения от родительского объекта, а затем определить новые разрешения, добавив или удалив назначения ролей.
Основные сведения о рабочих процессах SharePoint	Узнайте, как добавлять функции поиска в клиентские и мобильные приложения с помощью службы REST поиска в SharePoint Server 2013 и любой технологии, поддерживающей веб-запросы REST.
Справочные материалы по REST API каналов социальных сетей для SharePoint	Конечные точки REST SharePoint для выполнения задач, связанных с каналами.
Справочные материалы по REST API отслеживания пользователей и контента для SharePoint	Конечные точки REST SharePoint для подписки на людей и контент.
Разработка надстроек SharePoint	Здесь вы найдете подробные статьи и ресурсы, которые помогут вам расширить возможности своих надстроек SharePoint.