Определение URI конечных точек службы REST в SharePoint

Совет

Прежде чем приступать к работе, ознакомьтесь со следующими ресурсами:

Знакомство со службой REST SharePointНавигация по структуре данных SharePoint, представленной в службе REST

• Программирование с использованием службы SharePoint REST

Структура URI конечной точки REST в SharePoint

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

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"

Но в некоторых случаях URI конечной точки отличается от соответствующей подписи клиентской объектной модели для соответствия соглашениям REST или OData.

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

Структура синтаксиса URI REST SharePoint**

Синтаксис некоторых конечных точек для ресурсов SharePoint не соответствует этой структуре:

• Методы, в качестве параметров которых требуются сложные типы. Если соответствующий метод клиентской объектной модели требует, чтобы в качестве параметров передавались сложные типы, конечная точка REST может отклоняться от этой структуры синтаксиса в связи с ограничениями REST.
• Статические методы и свойства. Синтаксис конечных точек REST отличается от структуры синтаксиса для URI, представляющих статические методы и свойства.

Как определить конечные точки службы REST в SharePoint

Чтобы создать конечную точку REST для ресурса SharePoint, выполните указанные ниже действия.

1. Начните со ссылки на службу REST:

   https://{site_url}/_api

2. Укажите соответствующую точку входа. Пример:

   https://{site_url}/_api/web

3. Перейдите от точки входа к конкретным ресурсам, к которым нужно получить доступ. Это включает указание параметров для конечных точек, которые соответствуют методам в клиентской объектной модели. Например:

   https://{site_url}/_api/web/lists/getbytitle('{list_name}')

Ссылка на службу REST SharePoint в URI конечной точки

Используйте _api, чтобы указать ссылку на службу REST SharePoint в URI конечной точки. Служба REST входит в состав веб-службы client.svc. Но чтобы упростить создание URI REST и сократить базовый путь к URI REST, служба REST использует _api, избавляя от необходимости явно ссылаться на веб-службу client.svc.

Служба REST по-прежнему распознает и принимает URI, которые ссылаются на веб-службу client.svc. Например, вы можете использовать https://{site_url}/_vti_bin/client.svc/web/lists вместо https://{site_url}/_api/web/lists. Однако лучше использовать _api. Максимальная длина URL-адреса составляет 256 символов, а _api сокращает базовый URI, оставляя в запасе больше символов для составления URL-адреса.

Указание точек входа для службы REST SharePoint

Основные точки входа для службы REST представляют семейство веб-сайтов и сайт указанного контекста. Таким образом, эти точки входа соответствуют свойствам ClientContext.Site и ClientContext.Web клиентских объектных моделей.

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

https://{site_url}/_api/site

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

https://{site_url}/_api/web

Помимо /site и /web, служба REST включает несколько других точек доступа, которые позволяют разработчикам переходить к определенным компонентам. В приведенной ниже таблице перечислены эти точки доступа.

Область функций	Точка доступа
Сайт	https://{site_url}/_api/site
Интернет	https://{site_url}/_api/web
Профиль пользователя	https://{site_url}/_api/SP.UserProfiles.PeopleManager
Поиск	https://{site_url}/_api/search

Переход к определенным ресурсам, к которым требуется получить доступ

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

API клиентской объектной модели	Конечная точка REST
ClientContext.Web.Lists	https://{site_url}/_api/web/lists
ClientContext.Web.Lists[guid]	https://{site_url}/_api/web/lists('<guid>')
ClientContext.Web.Lists.GetByTitle("Title")	https://{site_url}/_api/web/lists/getbytitle('<Title>')

URI конечных точек указываются с учетом регистра. В примере из предыдущей таблицы используется метод /getbytitle, который представляет собой аналог метода GetByTitle() в службе REST.

Указание параметров в URI конечных точек REST

SharePoint расширяет спецификацию OData, позволяя использовать круглые скобки для указания параметров методов и значений индекса. Это предотвращает потенциальные проблемы с устранением неоднозначности в URI, содержащих несколько одноименных параметров. Например, следующие два URI содержат одноименные параметры:

https://{site_url}/_api/web/lists/getByTitle('Announcements')/fields/getByTitle('Description')

https://{site_url}/_api/web/lists('{list_guid}')/fields/getById('{guid}')

Чтобы указать несколько параметров, включите параметр как пару "значение-имя" и разделите параметры запятыми. Пример:

https://{site_url}/_api/web/getAvailableWebTemplates(lcid=1033, includeCrossLanguage=true)

На следующем рисунке показан синтаксис параметров SharePoint REST.

Синтаксис параметров службы REST в SharePoint

Сложные типы в качестве параметров для службы REST

Некоторые методы клиентской объектной модели принимают полезные данные больших размеров в качестве параметра. Для обеспечения паритета функциональности между конечными точками REST и соответствующими API клиентской объектной модели необходимо, чтобы конечные точки принимали параметр сложного типа. В этих случаях служба REST расширяет существующий протокол OData, чтобы разрешить этим конечным точкам REST принимать единственный комплексный тип в качестве параметра. Это применяется только к операциям POST, и вам необходимо передать комплексный тип в формат Atom или JSON соответственно стандартам OData.

Например, метод ListCollection.Add принимает в качестве параметра объект Microsoft.SharePoint.Client.ListCreationInformation. Чтобы добавить список на указанный сайт, создайте соответствующую конечную точку REST следующим образом:

POST https://{site_url}/_api/web/lists/add
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}

{ "d" : {
    "results": {
      "__metadata": {
        "type": "SP.ListCreationInformation"
      },
      "CustomSchemaXml": "…large payload…/",
      "Description": "desc",
      "DocumentTemplateType": "1",
      "TemplateType": "101",
      "Title": "Announcements"
    }
  }
}

Использование псевдонимов параметров в вызовах службы REST

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

Например, два приведенных ниже URI REST эквивалентны.

Непосредственное указание значения параметра:

https://{site_url}/_api/web/applyWebTemplate("STS#0")

Использование псевдонима параметра и указание фактического значения параметра в строке запроса URI:

https://{site_url}/_api/web/applyWebTemplate(title=@template)?@template="STS#0"

Однако служба SharePoint REST не поддерживает передачу комплексных типов через псевдонимы параметров. Например, следующий URI, содержащий комплексный тип в качестве параметра, не поддерживается:

https://{site_url}/_api/userProfiles/People(7)/GetWorkplace(@address)?@address={"__metadata":{"type: "ODataDemo.Address"},"Street":"NE 228th", "City":"Sammamish","State":"WA","ZipCode":"98074","Country": "USA"}

Синтаксис присвоения псевдонима параметру службы REST в SharePoint

Указание словарей в качестве значений параметров

Для конечных точек REST, которые соответствуют методам, принимающим в качестве параметров словари Dictionary<String, String>, словарь следует передавать в строке запроса в формате разделенных запятыми пар "имя-значение".

Синтаксис службы REST для параметров словаря

Объект Dictionary<String, object> представлен как многозначный объект с именем KeyedPropertyValue, содержащий следующие строковые свойства:

• Key. Ключ многозначного объекта.
• Value. Значение объекта.
• Valuetype Тип значения объекта . Для простых типов значений, сопоставленных с существующими типами модели данных сущности (EDM), служба REST возвращает соответствующую строку типа EDM. Например, "Edm.String". В противном случае служба REST возвращает тип значения, возвращаемый функцией Type.ToString .

Указание значений параметров в строке запроса

Если URI REST завершается вызовом метода, с помощью синтаксиса строки запроса можно указать значения параметров метода. Например:

https://{site_url}/_api/web/applyWebTemplate?template="STS#0"

Ниже показан синтаксис службы REST для параметров в строке запроса.

Синтаксис службы REST для параметров в строке запроса

Указание статических методов и свойств в виде URI службы REST

Для создания URI, соответствующих статическим методам или свойствам, используйте имя соответствующего API из объектной модели ECMAScript, начиная с объявления пространства имен и использования точечной нотации. Например, SP. Utilities.Utility.getImageUrl(imageName) в клиентской объектной модели ECMAScript будет иметь следующий эквивалент REST:

https://{site_url}/_api/SP.Utilities.Utility.getImageUrl('imageName')

Однако к статическим свойствам возможен только прямой доступ, и их нельзя указывать в составе более длинных URI. Например, прямой доступ к методу SP.Utility.AssetsLibrary в REST можно получить следующим образом:

https://{site_url}/_api/SP.Utility.assetsLibrary/id

При этом нельзя использовать расположение ресурса в качестве параметра для более сложного URI, как показано в примере ниже:

https://{site_url}/_api/getList(~SP.Utility/assetsLibrary/id)

Ниже показан синтаксис статического элемента для службы REST в SharePoint.

Синтаксис статического элемента для службы REST в SharePoint

Служба SharePoint REST поддерживает широкий набор операторов строки запроса OData, позволяющих выбирать, фильтровать и упорядочивать данные, запрошенные у конечной точки. Дополнительные сведения см. в статье Использование операций запросов OData в запросах SharePoint REST.

См. также

• Знакомство со службой REST в SharePoint
• Получение версий списков документов с помощью значений ETag в службе REST
• Материалы по OData
• Разработка надстроек SharePoint