Расширенные возможности запросов к объектам Microsoft Entra ID

2024-08-23

Microsoft Graph поддерживает расширенные возможности запросов к различным объектам Microsoft Entra ID, которые также называются объектами каталогов, что помогает эффективно получать доступ к данным. Примеры включают добавление операторов not (not), not equals (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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "accountEnabled eq false";
});



mgc users list --filter "accountEnabled eq false"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)


requestFilter := "accountEnabled eq false"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "accountEnabled eq false";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('accountEnabled eq false')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "accountEnabled eq false";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled eq false"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "accountEnabled eq false",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

Вариант 2.$filter Используйте параметр запроса с оператором ne . Этот запрос не поддерживается по умолчанию, так как ne оператор поддерживается только в расширенных запросах. Поэтому необходимо добавить заголовок eventualConsistencyLevel в значение и использовать $count=true строку запроса.

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "accountEnabled ne true";
	requestConfiguration.QueryParameters.Count = true;
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});



mgc users list --filter "accountEnabled ne true" --count "true" --consistency-level "eventual"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestFilter := "accountEnabled ne true"
requestCount := true

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Count: &requestCount,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "accountEnabled ne true";
	requestConfiguration.queryParameters.count = true;
	requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.header('ConsistencyLevel','eventual')
	.filter('accountEnabled ne true')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;

$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "accountEnabled ne true";
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled ne true" -CountVariable CountVar  -ConsistencyLevel eventual


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "accountEnabled ne true",
		count = True,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")


result = await graph_client.users.get(request_configuration = request_configuration)

Microsoft Entra ID объектов (каталогов), поддерживающих расширенные возможности запросов

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

Объект	Связи
administrativeUnit	члены
application	владельцы
appRoleAssignment	-
device	memberOf transitiveMemberOf registeredUsers registeredOwners
group	члены transitiveMembers memberOf transitiveMemberOf владельцы appRoleAssignments
oAuth2PermissionGrant (предоставление делегированных разрешений)	-
orgContact	memberOf transitiveMemberOf
servicePrincipal	memberOf владельцы transitiveMemberOf appRoleAssignments appRoleAssignedTo oAuth2PermissionGrant
user	memberOf transitiveMemberOf ownedObjects registeredDevices ownedDevices transitiveManagers directReports transitiveReports appRoleAssignments oAuth2PermissionGrant

Примечание.

Использование в отношениях предыдущего списка объектов каталога поддерживается только с расширенными параметрами $filter запроса. Однако в таких случаях не используйте $expand в одном и том же запросе, так как он не поддерживается с расширенными параметрами запроса.

Сценарии запросов, требующие расширенных возможностей запросов

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

Описание	Пример
Использование `$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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Users.Count.GetAsync();



mgc users count get



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Users().Count().Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

graphClient.users().count().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let int32 = await client.api('/users/$count')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$graphServiceClient->users()->count()->get()->wait();


Import-Module Microsoft.Graph.Users

Get-MgUserCount


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

await graph_client.users.count.get()

{
    "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"


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Applications.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"displayName:Browser\"";
});



mgc applications list --search ""displayName:Browser""



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphapplications "github.com/microsoftgraph/msgraph-sdk-go/applications"
	  //other-imports
)


requestSearch := "\"displayName:Browser\""

requestParameters := &graphapplications.ApplicationsRequestBuilderGetQueryParameters{
	Search: &requestSearch,
}
configuration := &graphapplications.ApplicationsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
applications, err := graphClient.Applications().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ApplicationCollectionResponse result = graphClient.applications().get(requestConfiguration -> {
	requestConfiguration.queryParameters.search = "\"displayName:Browser\"";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let applications = await client.api('/applications')
	.search('displayName:Browser')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Applications\ApplicationsRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new ApplicationsRequestBuilderGetRequestConfiguration();
$queryParameters = ApplicationsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = "\"displayName:Browser\"";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->applications()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Applications

Get-MgApplication -Search '"displayName:Browser"'


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.applications.applications_request_builder import ApplicationsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = ApplicationsRequestBuilder.ApplicationsRequestBuilderGetQueryParameters(
		search = "\"displayName:Browser\"",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.applications.get(request_configuration = request_configuration)

{
    "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%[email protected]')


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "endsWith(userPrincipalName,'";
});



mgc-beta users list --filter "endsWith(userPrincipalName,'"



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
	  //other-imports
)


requestFilter := "endsWith(userPrincipalName,'"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "endsWith(userPrincipalName,'";
});

Snippet not available


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "endsWith(userPrincipalName,'";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Beta.Users

Get-MgBetaUser -Filter "endsWith(userPrincipalName,'"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "endsWith(userPrincipalName,'",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

{
    "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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "createdDateTime ge 2021-11-01";
	requestConfiguration.QueryParameters.Count = true;
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});



mgc-beta groups list --filter "createdDateTime ge 2021-11-01" --count "true" --consistency-level "eventual"



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphgroups "github.com/microsoftgraph/msgraph-beta-sdk-go/groups"
	  //other-imports
)

headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestFilter := "createdDateTime ge 2021-11-01"
requestCount := true

requestParameters := &graphgroups.GroupsRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Count: &requestCount,
}
configuration := &graphgroups.GroupsRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

GroupCollectionResponse result = graphClient.groups().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "createdDateTime ge 2021-11-01";
	requestConfiguration.queryParameters.count = true;
	requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});


const options = {
	authProvider,
};

const client = Client.init(options);

let groups = await client.api('/groups')
	.version('beta')
	.header('ConsistencyLevel','eventual')
	.filter('createdDateTime ge 2021-11-01')
	.get();


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Groups\GroupsRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new GroupsRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;

$queryParameters = GroupsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "createdDateTime ge 2021-11-01";
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->groups()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Beta.Groups

Get-MgBetaGroup -Filter "createdDateTime ge 2021-11-01" -CountVariable CountVar  -ConsistencyLevel eventual


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.groups.groups_request_builder import GroupsRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = GroupsRequestBuilder.GroupsRequestBuilderGetQueryParameters(
		filter = "createdDateTime ge 2021-11-01",
		count = True,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")


result = await graph_client.groups.get(request_configuration = request_configuration)

{
    "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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Count = true;
});



mgc users list --count "true"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)


requestCount := true

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Count: &requestCount,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
	requestConfiguration.queryParameters.count = true;
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -CountVariable CountVar


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		count = True,
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "value":[
    {
      "displayName":"Oscar Ward",
      "mail":"[email protected]",
      "userPrincipalName":"[email protected]"
    }
  ]
}

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

Расширенные возможности запросов к объектам Microsoft Entra ID

Microsoft Entra ID объектов (каталогов), поддерживающих расширенные возможности запросов

Сценарии запросов, требующие расширенных возможностей запросов

Поддержка фильтрации по свойствам объектов Microsoft Entra ID (каталогов)

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

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

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

Свойства контракта

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

Свойства роли каталога

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

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

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

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

Поддержка сортировки по свойствам объектов Microsoft Entra ID (каталог)

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

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

Связанные материалы

Обратная связь

Дополнительные ресурсы