Расширенные возможности запросов к объектам Microsoft Entra ID
Microsoft Graph поддерживает расширенные возможности запросов к различным объектам Microsoft Entra ID, которые также называются объектами каталогов, что помогает эффективно получать доступ к данным. Например, добавление не (not
), не равно (ne
), и заканчивается (endsWith
) операторами в параметре $filter
запроса.
Механизм запросов Microsoft Graph использует хранилище индексов для выполнения запросов. Чтобы добавить поддержку дополнительных возможностей запросов для некоторых свойств, эти свойства можно индексировать в отдельном хранилище. Это отдельное индексирование повышает производительность запросов. Однако эти расширенные возможности запросов недоступны по умолчанию, но инициатор запроса должен задать для заголовка ConsistencyLevel значение eventual
и, за исключением $search
, использовать $count
параметр запроса. Заголовок ConsistencyLevel и $count
называются расширенными параметрами запроса.
Например, если нужно получить только учетные записи неактивных пользователей, можно выполнить любой из этих запросов, использующих параметр $filter
запроса.
Вариант 1.$filter
Используйте параметр запроса с оператором eq
. Этот запрос работает по умолчанию и не требует дополнительных параметров запроса.
GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq false
Вариант 2.$filter
Используйте параметр запроса с оператором ne
. Этот запрос не поддерживается по умолчанию, так как ne
оператор поддерживается только в расширенных запросах. Поэтому необходимо добавить заголовок eventual
ConsistencyLevel в значение и использовать $count=true
строку запроса.
GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$count=true
ConsistencyLevel: eventual
Microsoft Entra ID объектов (каталогов), поддерживающих расширенные возможности запросов
Расширенные возможности запросов поддерживаются только для объектов каталога и их связей, включая следующие объекты:
Сценарии запросов, требующие расширенных возможностей запросов
В следующей таблице приведены сценарии запросов для объектов каталога, поддерживаемые только в расширенных запросах:
Описание | Пример |
---|---|
Использование $count в качестве сегмента URL-адреса |
GET~/groups/$count |
Использование $count в качестве параметра строки запроса |
GET~/servicePrincipals?$count=true |
Использование $count в $filter выражении |
GET~/users?$filter=assignedLicenses/$count eq 0&$count=true |
Использование $search |
GET~/applications?$search="displayName:Browser" |
Использование $orderby для выбранных свойств |
GET~/applications?$orderby=displayName&$count=true |
Использование $filter с оператором endsWith |
GET~/users?$count=true&$filter=endsWith(mail,'@outlook.com') |
Использование $filter и $orderby в одном и том же запросе |
GET../applications?$orderby=displayName&$filter=startsWith(displayName, 'Box')&$count=true |
Использование $filter с операторами startsWith для определенных свойств |
GET~/users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true |
Использование $filter с операторами ne и not |
GET~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true |
Использование $filter с операторами not и startsWith |
GET~/users?$filter=NOT startsWith(displayName, 'Conf')&$count=true |
Использование $filter в коллекции с оператором endsWith |
GET~/users?$count=true&$filter=proxyAddresses/any (p:endsWith(p, 'contoso.com'))&$select=id,displayName,proxyaddresses |
Использование трансляции OData с транзитивным списком участников |
GET~/me/transitiveMemberOf/microsoft.graph.group?$count=true |
Примечание.
- Совместное использование
$filter
и$orderby
поддерживается только в расширенных запросах. -
$expand
в настоящее время не поддерживается в расширенных запросах. - Расширенные возможности запросов в настоящее время недоступны для клиентов Azure AD B2C.
- Чтобы использовать расширенные возможности запросов в пакетных запросах, укажите заголовок ConsistencyLevel в теле запроса JSON
POST
.
Поддержка фильтрации по свойствам объектов Microsoft Entra ID (каталогов)
Свойства объектов каталога ведут себя по-разному в отношении поддержки параметров запросов. Ниже приведены распространенные сценарии для объектов каталога:
- Оператор
in
поддерживается по умолчанию, когдаeq
оператор поддерживается по умолчанию. - Оператор
endswith
поддерживается только с расширенными параметрами запроса и только свойствами mail, otherMails, userPrincipalName и proxyAddresses . - Получение пустых коллекций (
/$count eq 0
,/$count ne 0
) и коллекций с менее чем одним объектом (/$count eq 1
,/$count ne 1
) поддерживается только с расширенными параметрами запроса. - Операторы
not
иne
отрицания поддерживаются только с расширенными параметрами запроса.- Все свойства, поддерживающие оператор,
eq
также поддерживают операторыne
илиnot
. - Для запросов, использующих лямбда-оператор
any
, используйте операторnot
. См. Фильтрация с помощью лямбда-операторов..
- Все свойства, поддерживающие оператор,
В следующих таблицах представлена поддержка $filter
операторов по свойствам объектов каталога и указывается, где запросы поддерживаются с помощью расширенных возможностей запросов.
Условные обозначения
-
Оператор
$filter
работает по умолчанию для этого свойства. -
Оператор
$filter
работает только без дополнительных параметров запроса. -
Оператор
$filter
требуетдополнительных параметров запроса, которые:- Заголовок
ConsistencyLevel=eventual
- Строка запроса
$count=true
- Заголовок
-
Оператор
$filter
не поддерживается для этого свойства. Отправьте свой отзыв, чтобы запросить поддержку этого свойства$filter
для сценариев. - Пустые ячейки указывают, что запрос недопустим для этого свойства.
- Столбец значение null указывает, что свойство является недействительным и фильтруемым с помощью
null
. - Свойства, которые не перечислены здесь, не поддерживаются
$filter
вообще.
Свойства административных единиц
Свойство | eq | startsWith | eq NULL |
---|---|---|---|
description |
|
|
|
displayName |
|
|
|
isMemberManagementRestricted |
|
||
membershipRule |
|
|
|
membershipRuleProcessingState |
|
Свойства приложения
Свойство | eq | startsWith | ge/le | eq NULL |
---|---|---|---|---|
appId |
|
|||
createdDateTime |
|
|
||
description |
|
|
|
|
disabledByMicrosoftStatus |
|
|||
displayName |
|
|
|
|
federatedIdentityCredentials/any(f:f/issuer) |
|
|
||
federatedIdentityCredentials/any(f:f/name) |
|
|
||
federatedIdentityCredentials/any(f:f/subject) |
|
|
||
identifierUris/any(p:p) |
|
|
||
info/logoUrl |
|
|||
info/termsOfServiceUrl |
|
|
||
notes |
|
|
|
|
publicClient/redirectUris/any(p:p) |
|
|
||
publisherDomain |
|
|
||
requiredResourceAccess/any(r:r/resourceAppId) |
|
|||
serviceManagementReference |
|
|
|
|
signInAudience |
|
|||
spa/redirectUris/any(p:p) |
|
|
||
tags/any(p:p) |
|
|
||
uniqueName |
|
|
||
verifiedPublisher/displayName |
|
|
|
|
web/homePageUrl |
|
|
|
|
web/redirectUris/any(p:p) |
|
|
Следующие свойства сущности приложения поддерживают $count
коллекцию в выражении фильтра.
Property | eq Count 0 | eq Count 1 |
---|---|---|
extensionProperties/$count |
|
|
federatedIdentityCredentials/$count |
|
|
Свойства контракта
Свойство | eq | startsWith |
---|---|---|
customerId |
|
|
defaultDomainName |
|
|
displayName |
|
|
Свойства устройства
Свойство | eq | startsWith | ge/le | eq NULL |
---|---|---|---|---|
accountEnabled |
|
|||
alternativeSecurityIds/any(a:a/identityProvider) |
|
|
||
alternativeSecurityIds/any(a:a/type) |
|
|||
approximateLastSignInDateTime |
|
|
||
deviceCategory |
|
|
|
|
deviceId |
|
|||
deviceOwnership |
|
|
||
displayName |
|
|
|
|
enrollmentProfileName |
|
|
|
|
extensionAttributes/extensionAttribute1-15 |
|
|
|
|
hostnames/any(p:p) |
|
|
||
isCompliant |
|
|||
isManaged |
|
|||
isRooted |
|
|
||
managementType |
|
|
||
manufacturer |
|
|
|
|
mdmAppId |
|
|
||
model |
|
|
|
|
onPremisesLastSyncDateTime |
|
|||
onPremisesSecurityIdentifier |
|
|
||
onPremisesSyncEnabled |
|
|
||
operatingSystem |
|
|
|
|
operatingSystemVersion |
|
|
|
|
physicalIds/any(p:p) |
|
|||
profileType |
|
|||
registrationDateTime |
|
|
||
trustType |
|
Следующие свойства сущности устройства поддерживают $count
коллекцию в выражении фильтра.
Property | eq Count 0 | eq Count 1 |
---|---|---|
physicalIds/$count |
|
|
systemLabels/$count |
|
|
Свойства роли каталога
Свойство | eq | startsWith | eq NULL |
---|---|---|---|
description |
|
|
|
displayName |
|
|
|
roleTemplateId |
|
|
Свойства группы
Свойство | eq | startsWith | ge/le | eq NULL |
---|---|---|---|---|
assignedLicenses/any(a:a/skuId) |
|
|||
classification |
|
|
||
createdByAppId |
|
|||
createdDateTime |
|
|
||
description |
|
|
|
|
displayName |
|
|
|
|
expirationDateTime |
|
|||
groupTypes/any(p:p) |
|
|||
hasMembersWithLicenseErrors |
|
|
||
infoCatalogs/any(p:p) |
|
|
||
isAssignableToRole |
|
|||
mail; |
|
|
|
|
mailEnabled |
|
|||
mailNickname |
|
|
|
|
membershipRule |
|
|
||
membershipRuleProcessingState |
|
|||
onPremisesLastSyncDateTime |
|
|||
onPremisesProvisioningErrors/any(o:o/category) |
|
|||
onPremisesProvisioningErrors/any(o:o/propertyCausingError) |
|
|||
onPremisesSamAccountName |
|
|
||
onPremisesSecurityIdentifier |
|
|
||
onPremisesSyncEnabled |
|
|
||
preferredLanguage; |
|
|
||
proxyAddresses/any(p:p) |
|
|
||
renewedDateTime |
|
|||
resourceBehaviorOptions/any(p:p) |
|
|||
resourceProvisioningOptions/any(p:p) |
|
|||
securityEnabled |
|
|||
uniqueName |
|
|
Следующие свойства сущности группы поддерживают $count
коллекцию в выражении фильтра.
Property | eq Count 0 | eq Count 1 |
---|---|---|
assignedLicenses/$count |
|
|
onPremisesProvisioningErrors/$count |
|
|
proxyAddresses/$count |
|
|
Свойства контактов организации
Свойство | eq | startsWith | ge/le | eq NULL |
---|---|---|---|---|
CompanyName |
|
|
|
|
department |
|
|
|
|
displayName |
|
|
|
|
givenName; |
|
|
|
|
jobTitle; |
|
|
|
|
mail; |
|
|
|
|
mailNickname |
|
|
|
|
manager/id |
|
|||
onPremisesLastSyncDateTime |
|
|||
onPremisesProvisioningErrors/any(o:o/category) |
|
|||
onPremisesProvisioningErrors/any(o:o/propertyCausingError) |
|
|||
onPremisesSyncEnabled |
|
|
||
proxyAddresses/any(p:p) |
|
|
||
surname; |
|
|
|
Следующие свойства сущности orgContact поддерживают $count
коллекцию в выражении фильтра.
Property | eq Count 0 | eq Count 1 |
---|---|---|
onPremisesProvisioningErrors/$count |
|
|
proxyAddresses/$count |
|
|
Свойства субъекта-службы
Свойство | eq | startsWith | ge/le | eq NULL |
---|---|---|---|---|
accountEnabled |
|
|||
alternativeNames/any(p:p) |
|
|
||
appId |
|
|||
appOwnerOrganizationId |
|
|||
appRoleAssignmentRequired |
|
|||
applicationTemplateId |
|
|||
claimsPolicy/id |
|
|||
createdObjects/any(c:c/id) |
|
|||
description |
|
|
|
|
displayName |
|
|
|
|
federatedIdentityCredentials/any(f:f/issuer) |
|
|
||
federatedIdentityCredentials/any(f:f/name) |
|
|
||
federatedIdentityCredentials/any(f:f/subject) |
|
|
||
homepage |
|
|
|
|
info/logoUrl |
|
|||
info/termsOfServiceUrl |
|
|
||
notes |
|
|
|
|
preferredSingleSignOnMode |
|
|||
preferredTokenSigningKeyEndDateTime |
|
|||
publisherName |
|
|
||
remoteDesktopSecurityConfiguration/id |
|
|||
servicePrincipalNames/any(p:p) |
|
|
||
servicePrincipalType |
|
|||
tags/any(p:p) |
|
|
||
verifiedPublisher/displayName |
|
|
|
Следующие свойства сущности servicePrincipal поддерживают $count
коллекцию в выражении фильтра.
Property | eq Count 0 | eq Count 1 |
---|---|---|
federatedIdentityCredentials/$count |
|
|
Свойства пользователя
Свойство | eq | startsWith | ge/le | eq NULL |
---|---|---|---|---|
accountEnabled |
|
|||
ageGroup |
|
|||
assignedLicenses/any(a:a/skuId) |
|
|||
assignedPlans/any(a:a/capabilityStatus) |
|
|||
assignedPlans/any(a:a/service) |
|
|
||
assignedPlans/any(a:a/servicePlanId) |
|
|||
authorizationInfo/certificateUserIds/any(p:p) |
|
|||
businessPhones/any(p:p) |
|
|
||
city |
|
|
|
|
cloudRealtimeCommunicationInfo/isSipEnabled |
|
|||
CompanyName |
|
|
|
|
consentProvidedForMinor |
|
|||
country |
|
|
|
|
createdDateTime |
|
|
||
createdObjects/any(c:c/id) |
|
|||
creationType |
|
|||
department |
|
|
|
|
displayName |
|
|
|
|
employeeHireDate |
|
|||
employeeId |
|
|
||
employeeOrgData/costCenter |
|
|
||
employeeOrgData/division |
|
|
||
employeeType |
|
|||
externalUserState |
|
|||
faxNumber |
|
|
|
|
givenName; |
|
|
|
|
identities/any(i:i/issuer) |
|
|
||
imAddresses/any(p:p) |
|
|
||
infoCatalogs/any(p:p) |
|
|
||
isLicenseReconciliationNeeded |
|
|||
isResourceAccount |
|
|||
jobTitle; |
|
|
|
|
mail; |
|
|
|
|
mailNickname |
|
|
|
|
mobilePhone; |
|
|
|
|
officeLocation; |
|
|
|
|
onPremisesDistinguishedName |
|
|
|
|
onPremisesExtensionAttributes/extensionAttribute1-15 |
|
|
|
|
onPremisesImmutableId |
|
|||
onPremisesLastSyncDateTime |
|
|||
onPremisesProvisioningErrors/any(o:o/category) |
|
|||
onPremisesProvisioningErrors/any(o:o/propertyCausingError) |
|
|||
onPremisesSamAccountName |
|
|
||
onPremisesSecurityIdentifier |
|
|
||
onPremisesSipInfo/isSipEnabled |
|
|||
onPremisesSyncEnabled |
|
|
||
otherMails/any(p:p) |
|
|
||
passwordPolicies |
|
|||
passwordProfile/forceChangePasswordNextSignIn |
|
|
||
passwordProfile/forceChangePasswordNextSignInWithMfa |
|
|
||
postalCode |
|
|
|
|
preferredLanguage; |
|
|
||
provisionedPlans/any(p:p/provisioningStatus) |
|
|||
provisionedPlans/any(p:p/service) |
|
|
||
proxyAddresses/any(p:p) |
|
|
||
state |
|
|
||
streetAddress |
|
|
|
|
surname; |
|
|
|
|
usageLocation |
|
|
|
|
userPrincipalName. |
|
|
||
userType |
|
|
Следующие свойства сущности пользователя поддерживают $count
коллекцию в выражении фильтра.
Property | eq Count 0 | eq Count 1 |
---|---|---|
assignedLicenses/$count |
|
|
onPremisesProvisioningErrors/$count |
|
|
otherMails/$count |
|
|
ownedObjects/$count |
|
|
proxyAddresses/$count |
|
|
В следующей таблице показана $filter
поддержка другими свойствами расширения объекта user .
Тип расширения | eq | startsWith | eq NULL |
---|---|---|---|
Расширения схемы |
|
|
|
Открытые расширения |
|
|
|
Расширения каталогов |
|
|
|
Поддержка сортировки по свойствам объектов Microsoft Entra ID (каталог)
В следующей таблице представлена поддержка $orderby
по свойствам объектов каталога и указано, где сортировка поддерживается с помощью расширенных возможностей запросов.
Условные обозначения
-
Оператор
$orderby
работает по умолчанию для этого свойства. -
Оператор
$orderby
требуетдополнительных параметров запроса, которые:- Заголовок
ConsistencyLevel=eventual
- Строка запроса
$count=true
- Заголовок
-
$filter
Для использования и$orderby
в одном запросе для объектов каталога всегда требуются дополнительные параметры запроса. Дополнительные сведения см. в статье Сценарии запросов, требующие расширенных возможностей запросов.
Объект каталога | Имя свойства | $orderby |
---|---|---|
administrativeUnit | createdDateTime |
|
administrativeUnit | deletedDateTime |
|
administrativeUnit | displayName |
|
приложение | createdDateTime |
|
приложение | deletedDateTime |
|
приложение | displayName |
|
orgContact | createdDateTime |
|
orgContact | displayName |
|
device; | approximateLastSignInDateTime |
|
device; | createdDateTime |
|
device; | deletedDateTime |
|
device; | displayName |
|
group | createdDateTime |
|
group; | deletedDateTime |
|
group | displayName |
|
servicePrincipal | createdDateTime |
|
servicePrincipal | deletedDateTime |
|
servicePrincipal | displayName |
|
пользователь | createdDateTime |
|
пользователь | deletedDateTime |
|
пользователь | displayName |
|
пользователь | userPrincipalName. |
|
[все остальные] | [все остальные] |
|
Обработка ошибок расширенных запросов к объектам каталога
В следующем разделе приведены примеры распространенных сценариев ошибок, когда при необходимости не используются дополнительные параметры запроса.
Подсчет объектов каталога поддерживается только с использованием расширенных параметров запросов.
ConsistencyLevel=eventual
Если заголовок не указан, запрос возвращает ошибку при $count
использовании сегмента URL-адреса (/$count
) или автоматически игнорирует $count
параметр запроса (?$count=true
), если он используется.
GET https://graph.microsoft.com/v1.0/users/$count
{
"error": {
"code": "Request_BadRequest",
"message": "$count is not currently supported.",
"innerError": {
"date": "2021-05-18T19:03:10",
"request-id": "d9bbd4d8-bb2d-44e6-99a1-71a9516da744",
"client-request-id": "539da3bd-942f-25db-636b-27f6f6e8eae4"
}
}
}
Для объектов каталога $search
поддерживается только в расширенных запросах. Если заголовок ConsistencyLevel не указан, запрос возвращает ошибку.
GET https://graph.microsoft.com/v1.0/applications?$search="displayName:Browser"
{
"error": {
"code": "Request_UnsupportedQuery",
"message": "Request with $search query parameter only works through MSGraph with a special request header: 'ConsistencyLevel: eventual'",
"innerError": {
"date": "2021-05-27T14:26:47",
"request-id": "9b600954-ba11-4899-8ce9-6abad341f299",
"client-request-id": "7964ef27-13a3-6ca4-ed7b-73c271110867"
}
}
}
Если свойство или параметр запроса в URL-адресе поддерживаются только в расширенных запросах, но отсутствует заголовок ConsistencyLevel или строка запроса $count=true
, то запрос возвращает ошибку.
GET https://graph.microsoft.com/beta/users?$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')
{
"error": {
"code": "Request_UnsupportedQuery",
"message": "Operator 'endsWith' is not supported because the required parameters might be missing. Try adding $count=true query parameter and ConsistencyLevel:eventual header. Refer to https://aka.ms/graph-docs/advanced-queries for more information",
"innerError": {
"date": "2023-07-14T08:43:39",
"request-id": "b3731da7-5c46-4c37-a8e5-b190124d2531",
"client-request-id": "a1556ddf-4794-929d-0105-b753a78b4c68"
}
}
}
Если свойство не индексируется для поддержки параметра запроса, запрос возвращает ошибку, даже если указаны дополнительные параметры запроса. Например, свойство createdDateTime ресурса группы не индексируется для возможностей запросов.
GET https://graph.microsoft.com/beta/groups?$filter=createdDateTime ge 2021-11-01&$count=true
ConsistencyLevel: eventual
{
"error": {
"code": "Request_UnsupportedQuery",
"message": "Unsupported or invalid query filter clause specified for property 'createdDateTime' of resource 'Group'.",
"innerError": {
"date": "2023-07-14T08:42:44",
"request-id": "b6a5f998-94c8-430d-846d-2eaae3031492",
"client-request-id": "2be83e05-649e-2508-bcd9-62e666168fc8"
}
}
}
Однако запрос, включающий параметры запроса, может завершиться ошибкой автоматически. Например, для неподдерживаемых параметров запроса и для неподдерживаемых сочетаний параметров запроса. В таких случаях проверьте данные, возвращаемые запросом, чтобы определить, оказали ли указанные параметры запроса желаемое действие. В следующем примере параметр @odata.count
отсутствует, даже если запрос успешно выполняется.
GET https://graph.microsoft.com/v1.0/users?$count=true
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
"value":[
{
"displayName":"Oscar Ward",
"mail":"oscarward@contoso.com",
"userPrincipalName":"oscarward@contoso.com"
}
]
}