Знакомство с REST-интерфейсом SharePoint 2013 и его использование

SharePoint 2013 предоставляет интерфейс Representational State Transfer (REST), который позволяет использовать на этой платформе разработки стандартные веб-технологии и языки. Средства SharePoint давно были доступны веб-приложениям через клиентскую объектную модель, но эти API ориентированы только на .NET-приложения и языки. Полноценный интерфейс REST в SharePoint 2013 делает возможным доступ к большинству средств и сущностей SharePoint с помощью стандартных веб-языков, таких как JavaScript или PHP, и любого стека технологий или языка, который поддерживает REST.

Поскольку интерфейс REST не требует ссылаться на клиентские сборки, он также позволяет ограничить объем памяти, занимаемой вашими веб-приложениями — этот фактор особенно важен для мобильных приложений. REST имеет очевидные преимущества для мобильных приложений, написанных на платформах, отличных от Microsoft, например iOS и Android, но также является полезным ресурсом для разработчиков приложений Windows 8. Приложению Windows 8, написанному на HTML5 и JavaScript, интерфейс REST потребуется для любых операций в SharePoint, а разработчики на C#, заботящиеся о размере своих приложений, тоже могут поразмыслить об использовании REST. В этой статье будет продемонстрировано, как использовать этот интерфейс для включения мощи платформы SharePoint в ваши приложения и выполнения сложных операций над сущностями SharePoint.

Полноценный интерфейс REST в SharePoint 2013 делает возможным доступ к большинству средств и сущностей SharePoint с помощью стандартных веб-языков.

Основы

Прежде чем что-то делать с SharePoint, ваше удаленное веб- или мобильное приложение должно получить авторизованный доступ. В SharePoint 2013 существует два основных подхода к авторизации доступа к сайту SharePoint (независимо от того, используете ли вы REST). Первый подход включает аутентификацию пользователя SharePoint, и в этом случае ваше приложение получает тот же уровень доступа к данным и средствам SharePoint, что и пользователь. Различные способы аутентификации пользователя веб- или мобильного приложения выходят за рамки этой статьи, но мы кратко расскажем о двух новых вариантах в SharePoint 2013, потому что они влияют на то, как вы формируете свои REST-запросы.

• Если вы вызываете SharePoint из удаленно размещенного приложения, которое не может использовать только клиентский код (HTML и JavaScript), и между SharePoint и вашим приложением нет брандмауэра, то вы можете задействовать маркеры OAuth 2.0 от Microsoft Access Control Service (ACS), применяемого в качестве сервера защищенных маркеров.
• Если достаточно клиентского кода и разрешений пользователя, входящего в SharePoint, тогда хорошая альтернатива OAuth — библиотека кросс-доменного JavaScript (bit.ly/12kFwSP). Такая библиотека также является удобной альтернативой OAuth, если вы делаете удаленные вызовы через брандмауэр. Эти варианты подробно описываются в статье MSDN Library «Data access options for SharePoint 2013» (bit.ly/WGvt9L).

Применение OAuth Все подробности того, как OAuth работает в SharePoint 2013 и как вы можете получить маркер для своего приложения, изложены в статье MSDN Library «Authorization and authentication for apps in SharePoint 2013» (bit.ly/XAyv28). Получив маркер, вам нужно передавать его с каждым REST-запросом. Для этого вы добавляете заголовок Authorization, который передает маркер доступа как свое значение, которому предшествует слово «Bearer»:

Authorization: Bearer access_token

Примеры кода на C# и JavaScript, которые делают это, см. в разделе «Reading data with the SharePoint 2013 REST interface» статьи в MSDN Library «How to: Complete basic operations using SharePoint 2013 REST endpoints» (bit.ly/13fjqFn). Этот пример, в котором извлекаются все списки с сайта SharePoint, показывает, как выглядит базовый REST-запрос, передающий OAuth-маркер:

HttpWebRequest endpointRequest =
  (HttpWebRequest)HttpWebRequest.Create(
  "http:// <http:///> <site url>/_api/web/lists");
endpointRequest.Method = "GET";
endpointRequest.Accept = "application/json;odata=verbose";
endpointRequest.Headers.Add("Authorization", "Bearer " +
  accessToken);
HttpWebResponse endpointResponse =
  (HttpWebResponse)endpointRequest.GetResponse();

Применение библиотеки кросс-доменного JavaScript Эта библиотека содержится в файле SP.RequestExecutor.js, который находится в виртуальном каталоге /_layouts/15/ на серверах SharePoint. Чтобы использовать эту библиотеку, загрузите ее файл в удаленную веб-страницу. В JavaScript создайте объект SP.RequestExecutor, а затем вызовите его метод executeAsync. В качестве параметра этого метода передайте информацию, необходимую для формирования HTTP-запроса к REST-сервису. Основные различия между REST-вызовами, использующими OAuth, и REST-вызовами, использующими кросс-доменную библиотеку, заключаются в том, что во втором случае вам не надо передавать в запросе маркер доступа, но вы должны указывать (в RESTful URL) веб-сайт SharePoint, который будет действовать как сайт клиентского контекста. В статье MSDN Library «How to: Access SharePoint 2013 data from remote apps using the cross-domain library» (bit.ly/12kFwSP) эти детали обсуждаются более полно. В следующем примере, который извлекает все списки с сайта SharePoint, показывается, как выглядит REST-запрос, использующий кросс-доменную библиотеку:

var executor = new SP.RequestExecutor(appweburl);
  executor.executeAsync(
    {
      url:
        appweburl +
"/_api/SP.AppContextSite(@target)/web/lists?@target='" +
  hostweburl + "'",
  method: "GET",
  headers: { "Accept": "application/json; odata=verbose" },
  success: successHandler,
    error: errorHandler
    }
      );

Формирование RESTful URL REST-сервис SharePoint реализуется в файле client.svc в виртуальной папке /_vti_bin на веб-сайте SharePoint, но SharePoint 2013 поддерживает аббревиатуру «_api» в качестве заменителя «_vti_bin/client.svc». Вот как выглядит базовый URL для каждой конечной точки:

http://<domain>/<site url>/_api/

Прежде чем что-то делать с SharePoint, ваше удаленное веб- или мобильное приложение должно получить авторизованный доступ.

К этой базе дописываются относительные сервису URL конкретных конечных точек; например, вы можете извлечь все списки с сайта SharePoint с помощью такого URL:

http://<domain>/<site url>/_api/web/lists

Чтобы получить ссылку на конкретный список, укажите его идентификатор или, как в следующем примере, его заголовок:

_api/web/lists/getByTitle('samplelist')/

В этих примерах web не является шаблоном подстановки — это имя объекта класса Web в клиентской объектной модели SharePoint; lists — имя свойств-набора, а getByTitle — метод этого объекта-набора. Такая парадигма позволяет Microsoft комбинировать API-ссылку для конечных точек и объектную модель JavaScript; примеры см. в SP.Web.lists и SP.ListCollection.getByTitle по ссылкам bit.ly/14a38wZ и bit.ly/WNtRMO соответственно. Кроме того, синтаксис приблизительно отражает структуру области клиента (tenancy) SharePoint. Вы получаете информацию о наборе сайтов по _api/site, сведения о веб-сайте SharePoint — по _api/web и данные обо всех списках на веб-сайте — по _api/web/lists. Последний URL доставляет набор lists, содержащий все списки на сайте SharePoint. Вы также можете посмотреть, как эти объекты представлены в XML, переходя по указанным URL в своем наборе сайтов.

Вам доступны все основные классы в объектной модели контента SharePoint, в том числе набор сайтов, веб-сайты, списки, папки, поля и элементы списков. Вы можете получать сведения о пользователях через классы SP.User (bit.ly/15M4fzo), SP.UserCollection (bit.ly/16TQTnW), SP.Group (bit.ly/X55Pga) и SP.GroupCollection (bit.ly/ZnFHbG). В табл. 1 показаны примеры различных конечных точек для операций чтения.

Табл. 1. Конечные точки для операций чтения

По умолчанию данные возвращаются как XML в формате AtomPub, расширенном форматом OData, но вы можете получать данные в формате JSON, добавив в HTTP-запрос следующий заголовок accept:

accept: application/json;odata=verbose

Применение JSON или Atom (XML) зависит от ваших навыков, платформы и того, насколько критичны сетевые задержки для вашего приложения. JSON использует гораздо меньше символов, поэтому его имеет смысл применять для передачи малых объемов данных по сети. С другой стороны, на большинстве основных платформ, включая Microsoft .NET Framework, имеются полнофункциональные библиотеки для разбора XML.

Позже мы опишем, как использовать операторы OData-запроса для выборки, фильтрации и упорядочения данных.

Запись в SharePoint Все предыдущие запросы использовали HTTP-команду GET. При записи в SharePoint ваши запросы применяют команду POST, хотя в некоторых случаях вы будете переопределять эту команду, добавляя в запрос заголовок X-HTTP-Method и указывая значение PUT, MERGE или DELETE. В принципе, POST применяется, когда вы создаете объект вроде сайта, списка или элемента списка. MERGE используется, когда вы обновляете определенные свойства объекта и хотите, чтобы остальные свойства сохранили текущие значения. PUT выполняет замену какого-либо элемента; свойства, не указанные в запросе, получают значения по умолчанию. DELETE позволяет удалить какой-либо элемент.

Каждый запрос, что-то записывающий в SharePoint, должен включать сводку формы (form digest). Ваш код получает сводку как часть набора информации, возвращаемой следующей конечной точкой:

_api/contextinfo

Вы должны использовать команду POST в этом запросе (с пустым телом) и включить заголовок Authorization, как пояснялось ранее. В некоторых инфраструктурах вам придется указывать, что длина запроса POST равна 0. В возвращаемой структуре имеется свойство FormDigestValue, содержащее сводку формы. Во все последующие запросы POST вы добавляете заголовок X-Request­Digest со сводкой в качестве его значения.

Заметьте: если вы работаете с приложением, размещенным в SharePoint, и страницей, использующей эталонную страницу для SharePoint по умолчанию, сводка уже находится в странице в элементе с идентификатором __REQUESTDIGEST (с двумя знаками подчеркивания). Поэтому вместо вызова конечной точки contextinfo вы просто считываете значение в скрипте, например в таком jQuery-коде:

var formDigestValue = $("__REQUESTDIGEST").val()

Конечно, вы должны добавить в тело запроса данные, которые вы хотите записать, или идентификацию данных, которые вы хотите удалить. Вы можете применять либо формат AtomPub/OData, либо формат JSON. Если вы предпочтете последний, то должны добавить в запрос заголовок content-type:

content-type: application/json;odata=verbose

Полный набор примеров CRUD-операций (Create, Read, Update, Delete) с объектами SharePoint см. в «How to: Complete basic operations using SharePoint 2013 REST endpoints» по ссылке bit.ly/13fjqFn.

За мощь интерфейса REST в SharePoint 2013 приходится расплачиваться определенным увеличением сложности.

Более сложные операции

За мощь интерфейса REST в SharePoint 2013 приходится расплачиваться определенным увеличением сложности. Этот интерфейс поддерживает операции сортировки, фильтрации и упорядочения возвращаемых им данных. Он также поддерживает большое количество операций, специфичных для SharePoint. Эти расширенные возможности добавляют средства, которые вы не всегда увидите в стандартной реализации REST. В следующих разделах обсуждаются некоторые из важнейших факторов, которые вы должны учитывать при работе с REST и SharePoint.

Фильтрация, выборка и сортировка Вы можете использовать системные параметры OData-запросов для управления тем, какие данные возвращаются и как они сортируются. Поддерживаемые параметры приведены в табл. 2.

Табл. 2. Параметры фильтрации и сортировки данных

Например, чтобы получить автора книги, ее название и ISBN из списка Books, вы должны были бы указать следующее:

_api/web/lists/getByTitle('Books')/items?$select=
  Author,Title,ISBN

Если параметр $select не применяется, возвращаются все поля, кроме тех, которые оказались бы для сервера слишком интенсивно использующими ресурсы. Если вам нужны эти поля, вы должны задействовать параметр $select и указывать их по имени. Чтобы получить все поля, включите $select='*'.

Чтобы получить все книги Марка Твена (Mark Twain):

_api/web/lists/getByTitle('Books')/items?$filter=
  Author eq 'Mark Twain'

Полный список операторов, поддерживаемых параметром $filter см. в статье MSDN Library «Programming using the SharePoint 2013 REST service» по ссылке bit.ly/Zlqf3e.

Для сортировки книг по названию в порядке возрастания (ascending order):

_api/web/lists/getByTitle('Books')/items?$orderby=Title asc

Для сортировки в порядке убывания (descending order) замените asc на desc. Чтобы сортировать по нескольким полям, укажите список этих полей, разделяя их запятыми.

Важно учитывать, что при обновлении файлов вы можете использовать только HTTP-метод PUT.

Вы можете объединять несколько параметров оператором &. Чтобы получить только Title первых двух книг Марка Твена, укажите:

_api/web/lists/getByTitle('Books')/items?$select=
  Title&$filter=Author eq 'Mark Twain'&$top=2

Сервис будет полностью разрешать каждый параметр до применения следующего. Поэтому каждый параметр применяется только к набору данных, созданному предыдущими параметрами в URL. А значит, порядок задания параметров имеет значение. Например, следующий URL возвращает элементы 3–10:

_api/web/lists/getByTitle('Books')/items?$top=10&$skip=2

Но те же параметры в обратном порядке приведут к тому, что вы получите элементы 3–12:

_api/web/lists/getByTitle('Books')/items?$skip=2&$top=10

Вы можете получить нижние n элементов, используя параметр $orderby с сортировкой по убыванию и параметр $top (в таком порядке). Следующий URL возвращает нижние два элемента:

_api/web/lists/getByTitle('Books')/items?
  $orderby=ID desc&$top=2

Когда в списке SharePoint есть поле поиска (lookup field) в другом списке, это фактически приводит к соединению двух списков. Вы можете использовать параметр $expand для возврата спроецированных полей из присоединенного списка. Например, если в списке Books имеется поле PublishedBy, которое отыскивает данные в поле Name списка Publisher, то вы можете вернуть эти имена с помощью такого URL:

_api/web/lists/getByTitle('Books')/items?$select=Title,
  PublishedBy/Name&$expand=PublishedBy

Заметьте, что вы ссылаетесь на поле во внешнем списке по синтаксису lookup_column_display_name/foreign_column_name, а не foreign_list_name/foreign_column_name. Не менее важно, что имя поля поиска нельзя выбрать без его раскрытия.

Работа с файлами и папками Лучший способ добраться до библиотеки документов — задействовать преимущества метода GetFolderByServerRelativeUrl, доступного в /_api/web. Добавляя файл в библиотеку документов, вы отправляете содержимое этого файла в тело запроса и передаете имя файла в URL:

http://<site url>/_api/web/GetFolderByServerRelativeUrl(
  '/Shared Documents')/Files/add(url='a.txt',overwrite=true)

Важно учитывать, что при обновлении файлов вы можете использовать только HTTP-метод PUT. Следовательно, вы не можете объединить содержимое файла с тем, что уже хранится в библиотеке документов. Вместо этого вы заменяете одну версию файла другой. Вам также нужно использовать оператор $value в URL, чтобы получить доступ к содержимому файла, а не к метаданным, сопоставленным с файлом:

http://<site url>/_api/web/GetFileByServerRelativeUrl(
  '/Shared Documents/a.txt')/$value

Хорошим стилем в SharePoint считается снятие файлов с контроля перед внесением изменений в них, поэтому вы должны снять файл с контроля до его обновления, а по окончании вернуть обратно на контроль. Следующие операции требуют выдавать запросы POST по этим URL, причем тела запросов должны быть пустыми:

http://<site url>/_api/web/GetFileByServerRelativeUrl(
  '/Shared Documents/a.txt')/CheckOut()
http://<site url>/_api/web/GetFileByServerRelativeUrl(
  '/Shared Documents/a.txt')/CheckIn(comment='Comment',
  checkintype=0)

Метод CheckIn принимает два параметра. Параметр comment позволяет добавить комментарий в CheckIn, а параметр checkintype указывает тип возвращаемого в систему контроля изменения — незначительное (0) или существенное (1).

Хорошим стилем в SharePoint считается снятие файлов с контроля перед внесением изменений в них.

И последнее соображение. Если вы работаете с кодом (скажем, JavaScript), который выполняется в клиенте на основе браузера, и вы хотите закачать файл размером более 1,5 Мб, то REST — ваш единственный выбор. Этот вид операций с большими файлами (более 1,5 Мб) доступен только для Internet Explorer 10 (и выше) и других современных браузеров. Пример на рис. 1 показывает, как вы могли бы закачать двоичный файл, используя кросс-доменную библиотеку.

Рис. 1. Закачка двоичного файла с применением кросс-доменной библиотеки

function uploadFileBinary() {
  var executor = new SP.RequestExecutor(appweburl);
var body = "";
for (var i = 0; i < 1000; i++) {
  var ch = i % 256;
  body = body + String.fromCharCode(ch);
}
var info = {
  url: "_api/web/lists/getByTitle('Shared Documents')/
  RootFolder/Files/Add(url='a.dat', overwrite=true)",
  method: "POST",
  binaryStringRequestBody: true,
  body: body,
  success: success,
  error: fail,
  state: "Update"
};
executor.executeAsync(info);
}

Запросы изменений До сих пор мы описывали, как REST работает с сущностями SharePoint, доступными вам по URL, имитирующим структуру сайта SharePoint. Однако некоторые типы SharePoint недостижимы этим способом (или их просто нельзя представить таким образом). В контексте REST три важнейших из таких типов: ChangeQuery, ChangeLogItemQuery и ChangeToken.

Объекты ChangeQuery позволяют запрашивать журнал изменений SharePoint для любых обновлений, выполненных с набором сайтов SharePoint, сайтом или списком. Интерфейс REST предоставляет метод getchanges в каждой из перечисленных ниже конечных точек:

• /_api/site (для наборов сайтов);
• /_api/web (для сайтов);
• /_api/web/lists/list(guid'<list id>') или /_api/web/lists/getByTitle('list title') (для списков).

Вы передаете запрос по любому из этих адресов, добавляя /getchanges к соответствующему пути URL, а затем отправляете объект ChangeQuery через тело POST вашего запроса. Простой запрос изменений для получения всех элементов, добавленных в список, будет выглядеть примерно так (в JSON):

{'query': { '__metadata': {'type': 'SP.ChangeQuery'}, 'Add':
  'true','Item': 'true'}}

Метод getchanges ожидает, что тело запроса содержит представление объекта ChangeQuery внутри параметра запроса. Вы посылаете этот запрос по URL для конкретного списка:

/_api/web/lists/list(guid'<list id>')/getchanges

или

/_api/web/lists/getByTitle('<list title>')/getchanges

В ответе возвращается результат, который содержит набор изменений, соответствующий запросу. Если в списке только один элемент, тело ответа выглядит так:

{"d":{"results":[{"__metadata":{"id":"https://<site url>/_api/
SP.ChangeItema7e7c6e9-2c41-47c3-aae9-2b4a63b7a087","uri":
"https://site url/_api/SP.ChangeItem","type":"SP.ChangeItem"},
"ChangeToken":{"__metadata":{"type":"SP.ChangeToken"},
"StringValue":"1;3;482e418a-0900-414b-8902-02248c2e44e8;
634955266749500000;5749111"},"ChangeType":1,"SiteId":"ce11bfbb-
cf9d-4b2b-a642-8673bd48cceb","Time":"2013-02-03T22:17:54Z",
"ItemId":1,"ListId":"482e418a-0900-414b-8902-02248c2e44e8",
"WebId":"a975b994-fc67-4203-a519-b160175ca967"}]}}

Этот ответ сообщает, что в список был добавлен один элемент (со значением ItemId, равным 1) на момент, отраженный ChangeToken в журнале изменений. Вы можете использовать строковое значение этого объекта, чтобы сделать свои запросы более точными. Например, можно указать значения для свойств ChangeTokenStart и ChangeTokenEnd вашего объекта ChangeQuery, чтобы получить изменения, внесенные до или после некоего момента времени либо в промежутке между двумя временными точками.

Кроме того, значение объекта ChangeToken можно задействовать при использовании метода getListItemChangesSinceToken:

/_api/web/lists/list(guid'<list id>')/getListChangesSinceToken

Этот метод имеется только в интерфейсе REST. Если вы хотите выяснить все изменения в элементах данного списка с момента добавления первого элемента, сконструируйте объект ChangeLogItemQuery, который содержит маркер изменений (change token):

{'query': { '__metadata': {'type': 'SP.ChangeLogItemQuery'},
'ChangeToken':'1;3;482e418a-0900-414b-8902-02248c2e44e8;
634955266749500000;5749111'}}

Области компонентов (feature areas) SharePoint Server 2013 Все операции, обсуждаемые в этой статье, применимы к SharePoint Foundation 2013 и SharePoint Server 2013, так как они используют базовые средства SharePoint. Интерфейс SharePoint REST также предоставляет множество средств из областей компонентов SharePoint Server 2013. Рассмотрение этих областей выходит за рамки данной статьи, но вы можете обратиться к следующим ресурсам в SDK за подробной информацией о применении REST для работы с ними:

• «SharePoint 2013: Using the search REST service from an app for SharePoint» (bit.ly/Mt4szN);
• «Get started developing with social features in SharePoint 2013» (bit.ly/102qIGM);
• «BCS REST API reference for SharePoint 2013» (bit.ly/10FFMMu).

Очевидно, что самой важной частью информации, необходимой для выполнения какой-либо REST-операции, является корректный URL.

Отладка

Очевидно, что самой важной частью информации, необходимой для выполнения какой-либо REST-операции, является корректный URL. Мы упомянули о многих наиболее важных частях, а остальные вы можете изучить в SharePoint SDK. Поскольку модель интерфейса REST основана на клиентской объектной модели, сведения об URL конечных точек REST можно найти в справочнике по объектной модели JavaScript. Так, если вы хотите узнать, какие URL доступны для работы с наборами списков, загляните в справочную документацию для объекта SP.ListCollection по ссылке bit.ly/108hI1e.

Вы также можете перейти по REST URL как зарегистрированный пользователь и просмотреть XML-вывод любого запроса GET, чтобы понять, какие данные доступны в каждой конечной точке и как они структурированы. Это не поможет с запросами POST, но позволит ознакомиться с различными сущностями и информацией SharePoint, предоставляемыми каждой конечной точкой.

Важно, чтобы HTTP-запросы, посылаемые из вашего кода, содержали корректно кодированные URL. При запуске приложения в SharePoint вы можете получить кодированный URL из строкового аргумента SPHostUrl запроса, но в других контекстах вам, возможно, понадобится самостоятельно кодировать URL.

При выполнении более сложных операций — особенно тех, которые требуют HTTP-команды POST, — вам понадобится утилита трассировки HTTP, чтобы отлаживать свои HTTP-запросы. SharePoint возвращает сообщения об ошибках всякий раз, когда вы выдаете неправильный запрос, и эти сообщения могут многое сказать вам о том, где вы ошиблись в запросах. Например, ваше приложение (или пользователь) может быть просто не авторизовано для получения определенных видов информации от SharePoint. Кроме того, вы могли сконструировать неправильный JSON-объект или присвоить ошибочное значение какому-либо свойству.

Важно, чтобы HTTP-запросы, посылаемые из вашего кода, содержали корректно кодированные URL.

Некоторые инфраструктуры предоставляют готовые утилиты трассировки HTTP. При работе с приложениями ASP.NET можно пользоваться trace.axd (bit.ly/8bnst4). Если вы посылаете запросы напрямую из браузера, как и в случае JavaScript, то можете задействовать утилиту Fiddler (fiddler2.com/fiddler2). Мы применяли Fiddler для генерации примеров HTTP-ответов, включенных в эту статью.

Взаимодействие PHP-приложения с SharePoint через REST

Как мы говорили во введении, интерфейс REST позволяет взаимодействовать с SharePoint из любых стандартных языков и инфраструктур, обычно используемых веб-разработчиками. Для демонстрации мы опубликовали пример PHP-приложения, которое показывает, как взаимодействовать с сайтом SharePoint из удаленного веб-приложения, написанного на PHP. Это приложение для SharePoint, рассчитанное на запуск с сайта Office 365 SharePoint и выполнение в Windows Azure Web Site. Эта архитектура упрощает некоторые этапы, например публикацию веб-сайта, но PHP-код в примере может работать в любой архитектуре, поддерживающей PHP.

Вы можете просмотреть и скачать пример со страницы галереи кода по ссылке bit.ly/ZQsmvP. Пример иллюстрирует многие вещи, в том числе как работать с файлами и папками через REST, как получать маркер доступа OAuth из PHP-приложения и как использовать кросс-доменную библиотеку JavaScript. В этом контексте важнее всего то, что он демонстрирует, как получать и закачивать файлы в библиотеку документов SharePoint, используя REST и PHP.

Поскольку это приложение записывает данные на сайт SharePoint, первым делом (после получения маркера доступа) оно должно запросить сводку формы с _api/contextinfo. Этот запрос передает маркер доступа в заголовках и настраивает POST-запрос на использование SSL URL. Код, показанный на рис. 2, будет знаком каждому, кто работал с URL-объектами PHP-клиента.

Рис. 2. Запрос сводки формы

$opts = array (
  'Authorization: Bearer ' . $accToken
);
$ch = curl_init();
  $url = $appweburl . '/_api/contextinfo';
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $opts);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, '');
curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);

После выполнения запроса приложения разбирает XML и сохраняет значение сводки формы:

$root = new SimpleXmlElement($result);
$ns = $root->getNameSpaces(TRUE);
$childrenNodes = $root->children($ns['d']);
$formValue = $childrenNodes->FormDigestValue;

Оно также сохраняет маркер доступа в файле cookie. Когда пользователь закачивает какой-либо файл, приложения передает эти значения в HTML-файл, который конструирует HTTP-запрос на загрузку файлов в библиотеку документов. Перед настройкой этого запроса приложение считывает данные из локально хранящегося файла в строковый объект, который будет передан как тело POST-запроса:

$accToken = $_COOKIE["moss_access_token"];
$url = $_REQUEST["target"] .
$furl = $_FILES["file"]["tmp_name"];
$file = fopen($furl,"r");
$post_data = fread($file,filesize($furl));
fclose($file);

Код на рис. 3 получает значения сводки формы и маркера доступа, а затем подготавливает и выполняет HTTP-запрос, который закачивает файл.

Рис. 3. Выполнение запроса, который закачивает файл

"/_api/web/GetFolderByServerRelativeUrl('Lists/SharedDoc')/
Files/add(url='" . $_FILES["file"]["name"] .
"',overwrite=true)";
$opts = array (
'X-RequestDigest:' . $_REQUEST["digest"],
'Authorization: Bearer ' . $accToken);
// Инициализация cURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, $opts);
// Задайте URL, по которому вы хотите
// передавать форму и/или данные
curl_setopt($ch, CURLOPT_URL, $url);
// Передаваемые данные и файлы
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
// Передайте TRUE или 1, если вы хотите ждать
// и захватывать ответ на выданный запрос
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Для режима отладки; показывает любую ошибку,
// произошедшую при выполнении операции
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt ($ch, CURLOPT_SSL_VERIFYPEER, 0);
// Выполнение запроса
$response = curl_exec($ch);

Что дальше?

Хотя интерфейс REST в SharePoint 2013 не имеет полного паритета с клиентской объектной моделью, он достаточно обширен и эффективен, чтобы разработчики большинства веб- и мобильных приложений могли сделать то, что им нужно, особенно если они работают с инфраструктурами, отличными от .NET. Мы рассмотрели многие наиболее важные способы, с помощью которых вы можете интегрировать SharePoint в свои приложения через интерфейс REST, но возможностей на самом деле гораздо больше.

Интерфейс REST позволяет взаимодействовать с SharePoint из любых стандартных языков и инфраструктур, обычно используемых веб-разработчиками.

SharePoint 2013 SDK содержит набор ресурсов для REST-разработки, и вы можете найти ссылки на них на странице MSDN Library «SharePoint 2013 REST API, endpoints and samples» (bit.ly/137q9yk). Этот набор будет улучшаться, и в него войдет особенно большое количество примеров, поскольку, как демонстрирует пример с PHP, интерфейс REST значительно расширяет мир разработки для SharePoint.