Расширенные возможности запросов для объектов каталога Azure AD

В Azure AD постоянно добавляются новые возможности, повышается стабильность, доступность и производительность этого решения. Одновременно ведется работа и над усовершенствованием Microsoft Graph для масштабирования и эффективного доступа к данным. Одно из направлений этого усовершенствования заключается в усилении поддержки возможностей расширенных запросов для различных объектов Azure AD и их свойств. Например, можно добавлять операторы Не (not), Не равно (ne) и Оканчивается на (endsWith) к параметру запроса $filter.

Механизм запросов Microsoft Graph использует хранилище индексов для выполнения запросов. Чтобы добавить поддержку дополнительных возможностей запросов для некоторых свойств, индексирование этих свойств теперь происходит в отдельном хранилище. Благодаря этому отдельному индексированию в Azure Active Directory расширена поддержка и повышена производительность запросов. Однако эти расширенные возможности запросов по умолчанию недоступны. Запросившая сторона также должна установить 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 поддерживается только в расширенных запросах. Поэтому необходимо добавить заголовок ConsistencyLevel, для которого должно быть указано значение eventual, а также использовать строку запроса $count=true.

    GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled ne true&$count=true
    ConsistencyLevel: eventual
    

Эти расширенные возможности запросов поддерживаются только для объектов каталога Azure Active Directory и их взаимосвязей, включая следующие часто используемые объекты:

Объект Связи
Административная единица
  • члены
  • Приложение
  • владельцы
  • Устройство
  • memberOf
  • transitiveMemberOf
  • registeredUsers
  • registeredOwners
  • Группа
  • члены
  • transitiveMembers
  • memberOf
  • transitiveMemberOf
  • владельцы
  • appRoleAssignments
  • Контакты организации
  • memberOf
  • transitiveMemberOf
  • Субъект-служба
  • memberOf
  • transitiveMemberOf
  • appRoleAssignments
  • appRoleAssignmentsTo
  • oAuth2PermissionGrant
  • Пользователь
  • memberOf
  • transitiveMemberOf
  • ownedObjects
  • registeredDevices
  • ownedDevices
  • transitiveManagers
  • directReports
  • transitiveReports
  • appRoleAssignments
  • oAuth2PermissionGrant
  • В следующей таблице приведены сценарии запросов для объектов каталога, поддерживаемые только в расширенных запросах:

    Описание Пример
    Использование $count в качестве сегмента URL-адреса GET ../groups/$count
    Использование $count в качестве параметра строки запроса GET ../servicePrincipals?$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
    Использование функции OData cast с другим параметром запроса GET ../me/transitiveMemberOf/microsoft.graph.group?$count=true

    Примечание

    • Совместное использование $filter и $orderBy поддерживается только в расширенных запросах.
    • $expand в настоящее время не поддерживается в расширенных запросах.
    • Расширенные возможности запросов в настоящее время недоступны для клиентов Azure AD B2C.

    Поддержка фильтрации по свойствам объектов каталога Azure AD

    Свойства объектов каталога ведут себя по-разному в отношении поддержки параметров запросов. Ниже приведены распространенные сценарии для объектов каталога:

    • Запросы, поддерживаемые по умолчанию, также поддерживаются в расширенных запросах, но в конечном итоге ответ будет согласованным.
    • Оператор in поддерживается по умолчанию, когда eq оператор поддерживается по умолчанию.
    • Оператор endsWith поддерживается только расширенными запросами и свойствами mail и userPrincipalName.
    • Операторы отрицания not и ne поддерживаются только расширенными запросами.

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

    Условные обозначения

    • Работает по умолчанию. Не требуются расширенные параметры запроса. Оператор $filter по умолчанию работает для этого свойства.
    • Требуются расширенные параметры запроса. Оператору $filter требуются расширенные параметры запроса, которые:
      • Заголовок ConsistencyLevel=eventual
      • Строка запроса $count=true
    • Не поддерживаются. Оператор $filter не поддерживается для этого свойства. Отправьте свой отзыв, чтобы запросить поддержку этого свойства $filter для сценариев.
    • Пустые ячейки указывают, что запрос является недействительным для этого свойства.
    • Столбец значение null указывает, что свойство является недействительным и фильтруемым с помощью null.
    • Свойства, не указанные здесь, совсем не $filter поддерживаются.

    Свойства административных единиц

    Имя свойства eq startsWith ge le Значение NULL
    description Требуются расширенные параметры запроса Требуются расширенные параметры запроса Не поддерживается
    displayName Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса

    Свойства приложения

    Имя свойства eq startsWith ge le Значение NULL
    appId Поддержка по умолчанию Не поддерживается
    applicationTemplateId Поддержка по умолчанию Не поддерживается
    createdDateTime Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    createdOnBehalfOf/id Поддержка по умолчанию Не поддерживается
    description Требуются расширенные параметры запроса Требуются расширенные параметры запроса Не поддерживается
    disabledByMicrosoftStatus Поддержка по умолчанию Не поддерживается
    displayName Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    identifierUris/any(p:p) Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию
    info/logoUrl Не поддерживается Не поддерживается Требуются расширенные параметры запроса
    info/termsOfServiceUrl Требуются расширенные параметры запроса Не поддерживается Не поддерживается
    keyCredentials/any(k:k/endDateTime) Требуются расширенные параметры запроса Требуются расширенные параметры запроса Требуются расширенные параметры запроса Не поддерживается
    publisherDomain Поддержка по умолчанию Поддержка по умолчанию Не поддерживается
    requiredResourceAccess/any(r:r/resourceAppId) Требуются расширенные параметры запроса Не поддерживается
    signInAudience Поддержка по умолчанию Не поддерживается
    tags/any(p:p) Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию
    verifiedPublisher/displayName Требуются расширенные параметры запроса Не поддерживается Требуются расширенные параметры запроса

    Свойства устройства

    Имя свойства eq startsWith ge le Значение NULL
    accountEnabled Поддержка по умолчанию Не поддерживается
    alternativeSecurityIds/any(a:a/identityProvider) Требуются расширенные параметры запроса Не поддерживается Не поддерживается
    alternativeSecurityIds/any(a:a/type) Поддержка по умолчанию Требуются расширенные параметры запроса Требуются расширенные параметры запроса Не поддерживается
    approximateLastSignInDateTime Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    deviceId Поддержка по умолчанию Не поддерживается
    displayName Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    extensionAttributes/extensionAttribute1-15 Требуются расширенные параметры запроса Не поддерживается Требуются расширенные параметры запроса
    isCompliant Поддержка по умолчанию Не поддерживается
    isManaged Поддержка по умолчанию Не поддерживается
    mdmAppId Поддержка по умолчанию Не поддерживается
    onPremisesLastSyncDateTime Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Не поддерживается
    onPremisesSyncEnabled Поддержка по умолчанию Требуются расширенные параметры запроса
    operatingSystem Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    operatingSystemVersion Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    physicalIds/any(p:p) Поддержка по умолчанию

    Свойства группы

    Имя свойства eq startsWith ge le Значение NULL
    assignedLicenses/any(a:a/skuId) Поддержка по умолчанию Не поддерживается
    classification Поддержка по умолчанию Поддержка по умолчанию Не поддерживается
    createdOnBehalfOf/id Поддержка по умолчанию Не поддерживается
    description Требуются расширенные параметры запроса Требуются расширенные параметры запроса Не поддерживается
    displayName Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    expirationDateTime Требуются расширенные параметры запроса Требуются расширенные параметры запроса Требуются расширенные параметры запроса Не поддерживается
    hasMembersWithLicenseErrors Поддержка по умолчанию Поддержка по умолчанию
    isAssignableToRole Поддержка по умолчанию Не поддерживается
    mail Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    mailEnabled Поддержка по умолчанию Не поддерживается
    mailNickname Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    membershipRule Поддержка по умолчанию Поддержка по умолчанию Не поддерживается
    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 Поддержка по умолчанию Не поддерживается

    Свойства контактов организации

    Имя свойства eq startsWith ge le Значение 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 Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса

    Свойства субъекта-службы

    Имя свойства eq startsWith ge le Значение NULL
    accountEnabled Поддержка по умолчанию Не поддерживается
    alternativeNames/any(p:p) Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию
    appId Поддержка по умолчанию Не поддерживается
    appOwnerOrganizationId Требуются расширенные параметры запроса Не поддерживается
    appRoleAssignmentRequired Требуются расширенные параметры запроса Не поддерживается
    applicationTemplateId Поддержка по умолчанию Не поддерживается
    createdObjects/any(c:c/id) Требуются расширенные параметры запроса Не поддерживается
    description Требуются расширенные параметры запроса Требуются расширенные параметры запроса Не поддерживается
    displayName Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    info/logoUrl Не поддерживается Не поддерживается Требуются расширенные параметры запроса
    info/termsOfServiceUrl Требуются расширенные параметры запроса Не поддерживается Не поддерживается
    keyCredentials/any(k:k/endDateTime) Требуются расширенные параметры запроса Требуются расширенные параметры запроса Требуются расширенные параметры запроса Не поддерживается
    servicePrincipalNames/any(p:p) Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию
    tags/any(p:p) Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию

    Свойства пользователя

    Имя свойства eq startsWith ge le Значение NULL
    accountEnabled Поддержка по умолчанию Не поддерживается
    ageGroup Поддержка по умолчанию Не поддерживается
    assignedLicenses/any(a:a/skuId) Поддержка по умолчанию Не поддерживается
    assignedPlans/any(a:a/capabilityStatus) Требуются расширенные параметры запроса Не поддерживается
    assignedPlans/any(a:a/service) Требуются расширенные параметры запроса Не поддерживается Не поддерживается
    assignedPlans/any(a:a/servicePlanId) Требуются расширенные параметры запроса Не поддерживается
    businessPhones/any(p:p) Требуются расширенные параметры запроса Требуются расширенные параметры запроса Требуются расширенные параметры запроса Требуются расширенные параметры запроса
    city Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    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) Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию
    isResourceAccount Поддержка по умолчанию Не поддерживается
    jobTitle Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    mail Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    mailNickname Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    manager/id Поддержка по умолчанию Не поддерживается
    mobilePhone Требуются расширенные параметры запроса Требуются расширенные параметры запроса Требуются расширенные параметры запроса
    officeLocation Требуются расширенные параметры запроса Требуются расширенные параметры запроса Требуются расширенные параметры запроса
    onPremisesExtensionAttributes/extensionAttribute1-15 Требуются расширенные параметры запроса Не поддерживается Требуются расширенные параметры запроса
    onPremisesImmutableId Поддержка по умолчанию Не поддерживается
    onPremisesLastSyncDateTime Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Не поддерживается
    onPremisesProvisioningErrors/any(o:o/category) Поддержка по умолчанию Не поддерживается
    onPremisesProvisioningErrors/any(o:o/propertyCausingError) Поддержка по умолчанию Не поддерживается
    onPremisesSamAccountName Требуются расширенные параметры запроса Требуются расширенные параметры запроса Не поддерживается
    onPremisesSecurityIdentifier Не поддерживается Требуются расширенные параметры запроса
    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) Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию Поддержка по умолчанию
    showInAddressList Требуются расширенные параметры запроса Не поддерживается
    state Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    streetAddress Требуются расширенные параметры запроса Требуются расширенные параметры запроса Требуются расширенные параметры запроса
    surname Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    usageLocation Поддержка по умолчанию Поддержка по умолчанию Требуются расширенные параметры запроса
    userPrincipalName Поддержка по умолчанию Поддержка по умолчанию Не поддерживается
    userType Поддержка по умолчанию Требуются расширенные параметры запроса

    Обработка ошибок расширенных запросов к объектам каталога

    Подсчет объектов каталога поддерживается только с использованием расширенных параметров запросов. Если заголовок ConsistencyLevel=eventual не указан, запрос возвращает ошибку, когда используется сегмент URL-адреса $count, или автоматически игнорирует параметр запроса $count (?$count=true), если он используется.

    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 не указан, запрос возвращает ошибку.

    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, то запрос возвращает ошибку.

    https://graph.microsoft.com/v1.0/users?$filter=endsWith(mail,'@outlook.com')
    
    {
        "error": {
            "code": "Request_UnsupportedQuery",
            "message": "Unsupported Query.",
            "innerError": {
                "date": "2021-05-18T19:12:36",
                "request-id": "63f2093c-399c-4350-9609-3ce9b62abe3c",
                "client-request-id": "e60ed0ba-df5d-e190-f056-f9c0318456d7"
            }
        }
    }
    

    Если свойство не проиндексировано для поддержки параметра запроса, даже если указаны расширенные параметры запроса, то запрос возвращает ошибку.

    https://graph.microsoft.com/beta/groups?$filter=createdDateTime ge 2021-11-01&$count=true
    ConsistencyLevel: eventual
    
    {
        "error": {
            "code": "Request_UnsupportedQuery",
            "message": "The request uses a filter property that is not indexed",
            "innerError": {
                "date": "2021-06-10T19:32:01",
                "request-id": "5625ba13-0c9f-4fce-a853-4b52f3e0bd09",
                "client-request-id": "76fe4cd8-df3a-f8c3-659b-594274b6bb31"
            }
        }
    }
    

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

    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"
        },
      ]
    }
    

    См. также