Использование операций запросов OData в запросах REST SharePoint
Совет
Перед началом ознакомьтесь со следующими ресурсами:
Служба REST SharePoint поддерживает широкий диапазон операторов строки запроса OData, который позволяет выбирать, фильтровать и упорядочивать запрашиваемые данные.
Совет
Служба REST в SharePoint Online (а также локальной среде SharePoint 2016 или более поздней версии) поддерживает объединение нескольких запросов в один вызов службы с помощью параметра запроса OData $batch. Подробные сведения и ссылки на примеры кода см. в статье Отправка пакетных запросов с помощью интерфейсов REST API.
Выбор полей для возврата
С помощью параметра запроса $select укажите, какие поля необходимо возвращать для списка, элемента списка или другого объекта SharePoint, представленного набором сущностей. Для возврата всех доступных полей используйте запрос $select=*.
Примечание.
Как правило, если вы не указываете параметр запроса $select, служба REST по умолчанию возвращает все доступные поля. Но иногда некоторые объекты SharePoint включают свойства, для получения которых требуется очень много ресурсов. Для оптимизации работы службы REST эти свойства не включаются в запрос по умолчанию. Их следует запрашивать специально. Например, свойство SPWeb.EffectiveBasePermissions по умолчанию не возвращается, его необходимо запросить с помощью параметра запроса $select.
Вы также можете указать, что запрос возвращает спроецированные поля из других списков и значения поиска. Для этого укажите имя поля в параметрах запроса $select и $expand. Например:
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$select=Title,Products/Name&$expand=Products/Name
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Массовое расширение и выбор связанных элементов не поддерживается.
Выбор элементов для возврата
С помощью параметра запроса $filter укажите, какие элементы необходимо возвращать. В разделе Операторы запросов OData, поддерживаемые в службе SharePoint REST указаны параметры сравнения и функции для фильтрации запросов, которые можно использовать в службе SharePoint REST.
Запрос полей подстановки с одним значением
Поля подстановки одиночного значения представлены двумя отдельными полями в службе REST SharePoint: одно поле представляет фактическое значение поля, а другое — имя поля. Запросы к значению поля подстановки можно выполнять так же, как и любое другое поле этого типа данных. Например, если значением поля подстановки является строка, вы можете использовать в вашем запросе параметры сравнения строк.
Запрос пользователей
В службе REST SharePoint пользователи представлены понятным (отображаемым) именем пользователя, а не их псевдонимами или комбинацией домена и псевдонима. Следовательно, вам необходимо сформировать запросы к понятным именам пользователей.
Примечание.
Запросы на получение пользователей с учетом членства в группах не поддерживаются. Использование оператора Current для выполнения запросов с использованием идентификатора текущего пользователя не поддерживается.
Запрос на получение полей подстановки с несколькими значениями и пользователей
Так как поля поиска с несколькими значениями возвращаются в виде строки с несколькими значениями, нет возможности запросить их (например, эквивалент элемента Includes или NotIncludes не поддерживается).
Сортировка результатов
Используйте параметр $orderby, чтобы указать, как нужно сортировать результаты запроса. Чтобы сортировать результаты по нескольким полям, укажите список полей через запятую. Вы также можете указать, в каком порядке нужно сортировать элементы (по возрастанию или по убыванию), добавив к запросу ключевое слово asc или desc.
Постраничное разбиение результатов
С помощью параметров запроса $top и $skiptoken выберите часть элементов, которую нужно исключить из результатов запроса.
Примечание.
Параметр запроса $skip не работает с запросами для элементов списков SharePoint.
Параметр $top позволяет выбрать первые n результатов для возврата. Например, следующий URI запрашивает, чтобы на самом деле были возвращены только первые 10 элементов в предполагаемом наборе возврата:
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$top=10`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Опция запроса $skiptoken позволяет пропускать элементы до тех пор, пока указанный элемент не будет достигнут, и вернуть остальные.
GET https://{site_url}/_api/web/lists('{list_guid}')/items?$skiptoken=Paged=TRUE%26p_ID=5`
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Примечание.
При использовании этих параметров запроса следует учитывать, что постраничное разбиение в OData выполняется по порядку. Предположим, что вы размещаете кнопку следующей страницы для отображения элементов списка SharePoint. Вы используете службу REST, чтобы кнопка возвращала элементы 1–20, элементы 21–40 и так далее. Однако предположим, что другой пользователь удаляет элемент 4 и 18 между нажатиями кнопки "Далее". В этом случае порядковое размещение остальных элементов сбрасывается, и при отображении элементов 21–40 пропускаются два элемента.
Операторы запросов OData, поддерживаемые в службе SharePoint REST
| Поддерживаются | Не поддерживаются |
|---|---|
| Числовые сравнения (lt le gt ge eq ne) | Арифметические операторы (add, sub, mul, div, mod) Базовые математические функции (округление, пол, потолок) |
| Сравнение строк начинается ( {Col to query},'{string to check}' ) подстрока ( '{string to check}', {Col to query} ) eq ne |
заканчивается, заменить, подстрока, tolower, toupper, отделка, concat |
| Функции даты и времени день(), месяц(), год(), час(), минута(), секунда () | Оператор DateTimeRangesOverlap Выполнение запроса для выяснения того, входит ли дата или время в указанный повторяющийся временной интервал |
Ниже показаны поддерживаемые параметры запроса OData.
Поддерживаемые параметры запроса OData
