Поделиться через


Настройка ответов с помощью параметров запроса

Microsoft Graph поддерживает параметры запроса, которые можно использовать для указания и управления объемом данных, возвращаемых в ответе. Поддержка точных параметров запроса зависит от одной операции API к другой, и в зависимости от API может отличаться между конечными точками версии 1.0 и бета-версией .

Совет

В бета-версии конечной $ точки префикс необязателен. Например, вместо $filter можно использовать filter. В конечной точке $версии 1.0 префикс необязателен только для подмножества API. Для простоты всегда включается $ во всех версиях.

Параметрами запроса могут быть системные параметры запроса OData или другие параметры запроса.

Системные параметры запроса OData

API Microsoft Graph может поддерживать один или несколько из указанных ниже системных параметров запроса OData. Эти параметры запроса совместимы с языком запросов OData версии 4 и поддерживаются только в операциях GET.

Щелкните примеры, чтобы попробовать поработать с ними в песочнице Graph.

Имя Описание Пример
$count Возвращает общее количество соответствующих ресурсов. /me/messages?$top=2&$count=true
$expand Получает связанные ресурсы. /groups?$expand=members
$filter Фильтрует результаты (строки). /users?$filter=startswith(givenName,'J')
$format Возвращает результаты в указанном формате мультимедиа. /users?$format=json
$orderby Упорядочивает результаты. /users?$orderby=displayName desc
$search Возвращает результаты на основании условий поиска. /me/messages?$search=pizza
$select Фильтрует свойства (столбцы). /users?$select=givenName,surname
$skip Индексирует результирующий набор. Также используется некоторыми API для реализации разбиения на страницы и может использоваться вместе с $top для страницы результатов вручную. /me/messages?$skip=11
$top Задает размер страницы результатов. /users?$top=2

Сведения о параметрах системных запросов OData, поддерживаемых API и его свойствами, см. в таблице "Свойства" на странице ресурсов и в разделе "Необязательные параметры запроса" операций LIST и GET для API.

Другие параметры запроса

Имя Описание Пример
$skipToken Возвращает следующую страницу результатов из результирующих наборов, занимающих несколько страниц. (Вместо этого используются $skip некоторые API.) /users?$skiptoken=X%274453707402000100000017...

Другие возможности URL-адресов OData

Следующие возможности OData 4.0 являются сегментами URL-адресов, а не параметрами запросов.

Имя Описание Пример
$count Получает целочисленную сумму коллекции. GET /users/$count
GET /groups/{id}/members/$count

Получение количества пользователей
$ref Обновляет принадлежность объектов к коллекции. POST /groups/{id}/members/$ref

Добавление участника в группу
$value Возвращает или обновляет двоичное значение элемента. GET /me/photo/$value

Получение фотографии пользователя, группы или команды
$batch Объединение нескольких HTTP-запросов в пакетный запрос. POST /$batch

Пакетная обработка JSON

Кодирование параметров запроса

Значения параметров запроса должны быть закодированы в процентах согласно RFC 3986. Например, все зарезервированные символы в строках запроса должны быть закодированы в процентах. Многие HTTP-клиенты, браузеры и средства (например, Обозреватель Graph) обрабатывают эту кодировку за вас. Если запрос завершается сбоем, одной из возможных причин является невозможность правильного кодирования значений параметров запроса. В некоторых случаях необходимо дважды закодировать значения.

Примечание.

Существует известная проблема, связанная с кодировкой символов амперсанда (&) в $search выражениях в конечной точке версии 1.0 . Дополнительные сведения о проблеме и рекомендуемое решение см. в статье Известная проблема: $search для объектов каталога завершается сбоем для символа закодированного амперсанда (&).

Например, незакодированный URL-адрес выглядит следующим образом:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')

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

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')

URL-адрес в двух кодировке выглядит следующим образом:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29

Экранирование одинарных кавычек

Для запросов, использующих одинарные кавычки, если какие-либо значения параметров также содержат одинарные кавычки, они должны быть экранированы в двойном виде; В противном случае запрос завершается ошибкой из-за недопустимого синтаксиса. В приведенном примере строковое значение let''s meet for lunch? содержит пропускаемую одинарную кавычку.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'

Параметр count

Используйте параметр $count запроса, чтобы получить общее количество элементов в коллекции или совпадение с выражением. $count можно использовать следующими способами:

  1. В качестве параметра строки запроса с синтаксисом $count=true , включающем общее количество элементов в коллекции вместе со страницей значений данных, возвращенных из Microsoft Graph. Например, users?$count=true.
  2. В качестве сегмента URL-адреса можно получить только целочисленную сумму коллекции. Например, users/$count.
  3. В $filter выражении с операторами равенства для получения коллекции данных, где отфильтрованное свойство является пустой коллекцией. См . раздел Использование параметра запроса $filter для фильтрации коллекции объектов.

Примечание.

  1. Для ресурсов, производных от directoryObject, $count это поддерживается только в расширенных запросах. См . дополнительные возможности запросов к объектам каталога.
  2. Использование $count не поддерживается в клиентах Azure AD B2C.

Например, следующий запрос возвращает коллекцию контактов текущего пользователя и количество элементов в коллекции контактов в свойстве @odata.count .

GET  https://graph.microsoft.com/v1.0/me/contacts?$count=true

Для объектов каталога, то есть ресурсов, производных от directoryObject, $count параметр запроса поддерживается только в расширенных запросах.

Параметр expand

Многие ресурсы Microsoft Graph отображают как объявленные свойства ресурса, так и его связи с другими ресурсами. Эти связи также называются свойствами ссылки или навигации и могут ссылаться как на один ресурс, так и на коллекцию ресурсов. Например, папки почты, руководитель и подчиненные пользователя выводятся как связи.

С помощью строкового параметра запроса $expand в результаты можно включить расширенный ресурс или коллекцию, на которые ссылается одно отношение (свойство навигации). Для некоторых API можно развернуть только одну связь в одном запросе.

В приведенном ниже примере возвращаются сведения о корневом каталоге, а также дочерние элементы верхнего уровня на диске.

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children

В некоторых коллекциях ресурсов можно также указать свойства, возвращаемые в расширенных ресурсах, добавив $select параметр . В следующем примере выполняется тот же запрос, что и в предыдущем примере, но используется $select оператор , чтобы ограничить свойства, возвращаемые для расширенных дочерних элементов, свойствами идентификатора и имени .

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)

Примечание.

  • Не все отношения и ресурсы поддерживают параметр запроса $expand. Например, можно развернуть отношения directReports, manager, and memberOf для пользователя, но невозможно развернуть отношения events, messages и photo. Не все ресурсы и отношения поддерживают использование параметра $select для развернутых элементов.

  • Ресурсы Microsoft Entra, производные от directoryObject, такие как пользователь и группа, $expand обычно возвращают не более 20 элементов для расширенной связи и не имеют @odata.nextLink. Дополнительные сведения см. в разделе Ограничения параметров запроса.

  • $expand в настоящее время не поддерживается в расширенных запросах.

Параметр filter

Параметр запроса $filter позволяет получить только подмножество объектов коллекции. Инструкции по использованию $filterсм. в разделе Использование параметра запроса $filter для фильтрации коллекции объектов.

Параметр format

Параметр запроса $format позволяет указать формат мультимедиа для элементов, возвращаемых из Microsoft Graph.

Например, указанный ниже запрос возвращает список пользователей организации в формате JSON.

GET https://graph.microsoft.com/v1.0/users?$format=json

Примечание.

Параметр $format запроса поддерживает несколько форматов (например, atom, xmlи json), но результаты могут возвращаться не во всех форматах.

Параметр orderby

Параметр запроса $orderby позволяет указать порядок сортировки элементов, возвращаемых из Microsoft Graph. По умолчанию используется сортировка по возрастанию.

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

GET https://graph.microsoft.com/v1.0/users?$orderby=displayName

Некоторые API поддерживают сортировку по сущностям сложных типов. Следующий запрос получает сообщения и сортирует их по поле адреса свойства from , которое имеет сложный тип emailAddress:

GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address

Чтобы отсортировать результаты в порядке возрастания или убывания, добавьте или ascdesc к имени поля, разделенное пробелом, ?$orderby=name desc например (без кода), ?$orderby=name%20desc (URL-адрес закодирован). Если порядок сортировки не указан, выводится порядок по возрастанию по умолчанию.

Некоторые API позволяют упорядочивать результаты по нескольким свойствам. Например, приведенный ниже запрос позволяет упорядочить сообщения в папке "Входящие" пользователя сначала по имени отправителей по убыванию (от Я до А), а затем — по возрастанию (по умолчанию).

GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$orderby=from/emailAddress/name desc,subject

Примечание.

При указании $filterслужба определяет порядок сортировки результатов. Если вы одновременно используете $orderby и $filter для получения сообщений, так как сервер всегда определяет порядок сортировки результатов $filter, необходимо задать свойства определенным образом.

В приведенном ниже примере показан запрос, отфильтрованный по свойствам subject и importance, а затем отсортированный по свойствам subject, importance и receivedDateTime в порядке убывания.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=Subject eq 'welcome' and importance eq 'normal'&$orderby=subject,importance,receivedDateTime desc

Примечание.

Для объектов каталога поддерживаются параметры запросов $orderby и $filter. См . дополнительные возможности запросов в объектах каталога.

Параметр search

Параметр запроса $search позволяет ограничить результаты запроса с помощью условия поиска. Синтаксис и поведение различаются для разных операций API. Сведения о синтаксисе $search для разных ресурсов см. в статье Использование параметра запроса $search для сопоставления с условием поиска.

Параметр select

$select Используйте параметр запроса, чтобы вернуть подмножество свойств для ресурса. С помощью $select можно указать подмножество или надмножество свойств по умолчанию.

При выполнении запроса GET без использования $select для ограничения объема данных свойств Microsoft Graph включает свойство @microsoft.graph.tips , которое предоставляет рекомендации по использованию $select , аналогичное следующему сообщению:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Например, при получении сообщений вошедшего пользователя можно указать, что необходимо вернуть только свойства from и subject:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Важно!

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

В версии 1.0 некоторые ресурсы Microsoft Entra, производные от directoryObject, такие как пользователь и группа, возвращают ограниченное подмножество свойств по умолчанию при чтении. Для этих ресурсов необходимо использовать $select для возврата свойств за пределами набора по умолчанию.

Параметр skip

$skip Используйте параметр запроса, чтобы задать количество элементов, которые необходимо пропустить в начале коллекции. Например, следующий запрос возвращает события для пользователя, отсортированного по дате создания, начиная с 21-го события в коллекции:

GET  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20

Некоторые API Microsoft Graph, такие как Почта и календари Outlook (сообщение, событие и календарь), используют $skip для реализации разбиения по страницам. Если результаты запроса охватывают несколько страниц, эти API возвращают свойство @odata.nextLink с URL-адресом $skip , содержащим параметр. Этот URL-адрес можно использовать для возврата следующей страницы результатов. Подробнее…

Объекты каталога , такие как пользователь, группа и приложение , не поддерживают $skip.

Параметр skipToken

Некоторые запросы возвращают несколько страниц данных. Это происходит из-за разбиения по страницам на стороне сервера или из-за использования параметра $top для ограничения размера возвращаемых страниц. Многие API Microsoft Graph используют параметр запроса skipToken для ссылки на следующие страницы результатов.
Этот параметр содержит непрозрачный маркер, который ссылается на следующую страницу результатов и возвращается в URL-адресе, указанном в свойстве @odata.nextLink в ответе. Подробнее…

Примечание.

Если вы используете OData Count (добавляя $count=true в строку запроса) для запросов к объектам каталога, свойство @odata.count присутствует только на первой странице.

Заголовок ConsistencyLevel требуется для расширенных запросов объектов каталога. Этот заголовок по умолчанию не включен в запросы последующих страниц. Его необходимо явным образом задавать на последующих страницах.

Параметр top

$top Используйте параметр запроса, чтобы указать количество элементов, которые будут включены в результат.

Если в результирующем наборе остается больше элементов, текст ответа содержит параметр @odata.nextLink . Этот параметр содержит URL-адрес, с помощью которого можно получить следующую страницу результатов. Дополнительные сведения см. в статье о разбиении по страницам.

Минимальное значение $top является 1, а максимальное зависит от соответствующего API.

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

GET https://graph.microsoft.com/v1.0/me/messages?$top=5

Примечание.

Заголовок ConsistencyLevel требуется для расширенных запросов объектов каталога. Этот заголовок по умолчанию не включен в запросы последующих страниц. Его необходимо явным образом задавать на последующих страницах.

Обработка ошибок параметров запроса

Если указанный параметр запроса не поддерживается, некоторые запросы возвращают сообщение об ошибке. Например, нельзя использовать $expand для user/photo связи.

https://graph.microsoft.com/v1.0/me?$expand=photo
{
    "error":{
        "code":"ExpandNotSupported",
        "message":"Expand is not allowed for property 'Photo' according to the entity schema.",
        "innerError":{
            "request-id":"1653fefd-bc31-484b-bb10-8dc33cb853ec",
            "date":"2017-07-31T20:55:01"
        }
    }
}

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