Erweiterte Abfragefunktionen für Microsoft Entra ID-Objekte

Artikel
11/01/2024

Microsoft Graph unterstützt erweiterte Abfragefunktionen für verschiedene Microsoft Entra ID-Objekte, die auch als Verzeichnisobjekte bezeichnet werden, damit Sie effizient auf Daten zugreifen können. Zum Beispiel die Hinzufügung der OperatorenNicht (not), Ungleich (ne) und Endet mit (endsWith) für den$filterAbfrageparameter.

Die Microsoft Graph-Abfrage-Engine verwendet einen Indexspeicher, um Abfrageanforderungen zu erfüllen. Um Unterstützung für zusätzliche Abfragefunktionen für einige Eigenschaften hinzuzufügen, werden diese Eigenschaften möglicherweise in einem separaten Speicher indiziert. Diese separate Indizierung verbessert die Abfrageleistung. Diese erweiterten Abfragefunktionen sind jedoch nicht standardmäßig verfügbar, aber der Anforderer muss den ConsistencyLevel-Header auf eventual festlegen und mit Ausnahme $searchvon den $count Abfrageparametern verwenden. Der ConsistencyLevel-Header und $count werden als erweiterte Abfrageparameter bezeichnet.

Um beispielsweise nur inaktive Benutzerkonten abzurufen, können Sie eine der folgenden Abfragen mit dem $filterAbfrageparameter ausführen.

Option 1: Verwenden Sie den $filter Abfrageparameter mit dem eq Operator. Diese Anforderung funktioniert standardmäßig und erfordert keine erweiterten Abfrageparameter.

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)

Option 2: Verwenden Sie den $filter Abfrageparameter mit dem ne Operator. Diese Anforderung wird standardmäßig nicht unterstützt, da der ne Operator nur in erweiterten Abfragen unterstützt wird. Daher müssen Sie den auf festgelegten eventualConsistencyLevel-Header hinzufügen und die $count=true Abfragezeichenfolge verwenden.

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 (Verzeichnis)-Objekte, die erweiterte Abfragefunktionen unterstützen

Erweiterte Abfragefunktionen werden nur für Verzeichnisobjekte und deren Beziehungen unterstützt, einschließlich der folgenden Objekte:

Objekt	Beziehungen
administrativeUnit	Elemente
application	owners
appRoleAssignment	-
device	memberOf transitiveMemberOf registeredUsers registeredOwners
Gruppe	Elemente transitiveMembers memberOf transitiveMemberOf owners appRoleAssignments
oAuth2PermissionGrant (delegierte Berechtigungserteilungen)	-
orgContact	memberOf transitiveMemberOf
servicePrincipal	memberOf transitiveMemberOf appRoleAssignments appRoleAssignmentsTo oAuth2PermissionGrant
user	memberOf transitiveMemberOf ownedObjects registeredDevices ownedDevices transitiveManagers directReports transitiveReports appRoleAssignments oAuth2PermissionGrant

Abfrageszenarien, die erweiterte Abfragefunktionen erfordern

In der folgenden Tabelle sind Abfrageszenarien für Verzeichnisobjekte aufgeführt, die nur in erweiterten Abfragen unterstützt werden:

Beschreibung	Beispiel
Verwendung von `$count` als URL-Segment	ABRUFEN`~/groups/$count`
Verwenden von `$count` als Abfragezeichenfolgenparameter	ABRUFEN`~/servicePrincipals?$count=true`
Verwendung von`$count`in einem`$filter`Ausdruck	ABRUFEN`~/users?$filter=assignedLicenses/$count eq 0&$count=true`
Verwenden von `$search`	ABRUFEN`~/applications?$search="displayName:Browser"`
Verwenden von `$orderby` für bestimmte Eigenschaften	ABRUFEN`~/applications?$orderby=displayName&$count=true`
Verwenden von `$filter` mit dem Operator `endsWith`	ABRUFEN`~/users?$count=true&$filter=endsWith(mail,'@outlook.com')`
Verwendung von `$filter` und `$orderby` in derselben Abfrage	ABRUFEN`../applications?$orderby=displayName&$filter=startsWith(displayName, 'Box')&$count=true`
Verwenden von `$filter` mit den `startsWith`-Operatoren für bestimmte Eigenschaften.	ABRUFEN`~/users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true`
Verwenden von `$filter` mit den Operatoren `ne` und `not`	ABRUFEN`~/users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`
Verwenden von `$filter` mit den Operatoren `not` und `startsWith`	ABRUFEN`~/users?$filter=NOT startsWith(displayName, 'Conf')&$count=true`
Verwendung für `$filter` eine Sammlung mit `endsWith` Operator	ABRUFEN`~/users?$count=true&$filter=proxyAddresses/any (p:endsWith(p, 'contoso.com'))&$select=id,displayName,proxyaddresses`
Verwendung der OData-Umwandlung mit transitiver Memberliste	ABRUFEN`~/me/transitiveMemberOf/microsoft.graph.group?$count=true`

Hinweis

Die gemeinsame Verwendung von $filter und $orderby wird nur bei erweiterten Abfragen unterstützt.
$expand wird derzeit bei erweiterten Abfragen nicht unterstützt.
Die erweiterten Abfragefunktionen sind derzeit auf Azure AD B2C-Mandanten nicht verfügbar.
Um erweiterte Abfragefunktionen in Stapelanfragen zu verwenden, geben Sie den ConsistencyLevel Header im JSON-Text der POST Anforderung an.

Unterstützung für das Filtern nach Eigenschaften von Microsoft Entra ID (Verzeichnis)-Objekten

Eigenschaften von Verzeichnisobjekten verhalten sich bei der Unterstützung von Abfrageparametern unterschiedlich. Im Folgenden sind häufige Szenarien für Verzeichnisobjekte aufgeführt:

Der Operator in wird standardmäßig unterstützt, insofern der Operator eq standardmäßig unterstützt wird.
Der endswith Operator wird nur mit erweiterten Abfrageparametern und nur durch die Eigenschaften mail, otherMails, userPrincipalName und proxyAddresses unterstützt.
Das Abrufen leerer Auflistungen (/$count eq 0, /$count ne 0) und Auflistungen mit weniger als einem Objekt (/$count eq 1, /$count ne 1) wird nur mit erweiterten Abfrageparametern unterstützt.
Die not Negationsoperatoren und ne werden nur mit erweiterten Abfrageparametern unterstützt.
- Alle Eigenschaften, die den eq -Operator unterstützen, unterstützen auch die ne Operatoren oder not .
- Verwenden Sie für Abfragen, die den any-Lambdaoperator verwenden, den Operator not. Weitere Informationen finden Sie unter Filtern mit Lambdaoperatoren.

Die folgenden Tabellen fassen die Unterstützung von $filter Operatoren nach Eigenschaften von Verzeichnisobjekten zusammen und geben an, wo Abfragen durch erweiterte Abfragefunktionen unterstützt werden.

Legende

Der $filter Operator funktioniert standardmäßig für diese Eigenschaft.
Der $filter Operator funktioniert nur ohne erweiterte Abfrageparameter.
Für $filterden Operator sinderweiterte Abfrageparameter erforderlich:
- ConsistencyLevel=eventual-Header
- $count=true-Abfragezeichenfolge
Der $filter Operator wird für diese Eigenschaft nicht unterstützt. Senden Sie uns Feedback, um diese Unterstützung dieser Eigenschaft für Ihre Szenarien $filter anzufordern.
Leere Zellen geben an, dass die Abfrage für diese Eigenschaft ungültig ist.
Die Spalte mit dem Nullwert gibt an, dass die Eigenschaft nullbar und mithilfe von null filterbar ist.
Eigenschaften, die hier nicht aufgeführt sind, unterstützen $filter überhaupt nicht.

Eigenschaften von Verwaltungseinheiten

Eigenschaft	eq	startsWith	eq Null
description
displayName
isMemberManagementRestricted
membershipRule
membershipRuleProcessingState

Anwendungseigenschaften

Eigenschaft	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)

Die folgenden Eigenschaften der Anwendungsentität unterstützen $count eine Auflistung in einem Filterausdruck.

Eigenschaft	eq Count 0	eq Count 1
extensionProperties/$count
federatedIdentityCredentials/$count

Vertragseigenschaften

Eigenschaft	eq	startsWith
customerId
defaultDomainName
displayName

Geräteeigenschaften

Eigenschaft	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
Hersteller
mdmAppId
model
onPremisesLastSyncDateTime
onPremisesSecurityIdentifier
onPremisesSyncEnabled
operatingSystem
operatingSystemVersion
physicalIds/any(p:p)
profileType
registrationDateTime
trustType

Die folgenden Eigenschaften der Geräteentität unterstützen $count eine Auflistung in einem Filterausdruck.

Eigenschaft	eq Count 0	eq Count 1
physicalIds/$count
systemLabels/$count

Verzeichnisrolleneigenschaften

Eigenschaft	eq	startsWith	eq Null
description
displayName
roleTemplateId

Gruppeneigenschaften

Eigenschaft	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

Die folgenden Eigenschaften der Gruppenentität unterstützen $count eine Auflistung in einem Filterausdruck.

Eigenschaft	eq Count 0	eq Count 1
assignedLicenses/$count
onPremisesProvisioningErrors/$count
proxyAddresses/$count

Kontakteigenschaften der Organisation

Eigenschaft	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

Die folgenden Eigenschaften der orgContact-Entität unterstützen $count eine Auflistung in einem Filterausdruck.

Eigenschaft	eq Count 0	eq Count 1
onPremisesProvisioningErrors/$count
proxyAddresses/$count

Dienstprinzipaleigenschaften

Eigenschaft	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

Die folgenden Eigenschaften der servicePrincipal-Entität unterstützen $count eine Auflistung in einem Filterausdruck.

Eigenschaft	eq Count 0	eq Count 1
federatedIdentityCredentials/$count

Benutzereigenschaften

Eigenschaft	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)
Ort
cloudRealtimeCommunicationInfo/isSipEnabled
CompanyName
consentProvidedForMinor
Land/Region
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

Die folgenden Eigenschaften der Benutzerentität unterstützen $count eine Auflistung in einem Filterausdruck.

Eigenschaft	eq Count 0	eq Count 1
assignedLicenses/$count
onPremisesProvisioningErrors/$count
otherMails/$count
ownedObjects/$count
proxyAddresses/$count

Die folgende Tabelle zeigt die Unterstützung für $filter durch andere Erweiterungseigenschaften für das Benutzerobjekt .

Erweiterungstyp	eq	startsWith	eq null
Schemaerweiterungen
Offene Erweiterungen
Verzeichnisschemaerweiterungen

Unterstützung für die Sortierung nach Eigenschaften von Microsoft Entra ID (Verzeichnis)-Objekten

In der folgenden Tabelle wird die Unterstützung für $orderby durch Eigenschaften von Verzeichnisobjekten zusammengefasst und angegeben, wo die Sortierung durch erweiterte Abfragefunktionen unterstützt wird.

Legende

Der $orderby Operator funktioniert standardmäßig für diese Eigenschaft.
Für $orderbyden Operator sinderweiterte Abfrageparameter erforderlich:
- ConsistencyLevel=eventual-Header
- $count=true-Abfragezeichenfolge
Die Verwendung von $filter und $orderby in derselben Abfrage für Verzeichnisobjekte erfordert immer erweiterte Abfrageparameter. Weitere Informationen finden Sie unter Abfrageszenarien, die erweiterte Abfragefunktionen erfordern.

Verzeichnisobjekt	Eigenschaftenname	$orderby
administrativeUnit	createdDateTime
administrativeUnit	deletedDateTime
administrativeUnit	displayName
Anwendung	createdDateTime
Anwendung	deletedDateTime
Anwendung	displayName
orgContact	createdDateTime
orgContact	displayName
Gerät	approximateLastSignInDateTime
Gerät	createdDateTime
Gerät	deletedDateTime
Gerät	displayName
Gruppe	createdDateTime
Gruppe	deletedDateTime
Gruppe	displayName
servicePrincipal	createdDateTime
servicePrincipal	deletedDateTime
servicePrincipal	displayName
Benutzer	createdDateTime
Benutzer	deletedDateTime
Benutzer	displayName
Benutzer	userPrincipalName
[alle anderen]	[alle anderen]

Fehlerbehandlung bei erweiterten Abfragen für Verzeichnisobjekten

Der folgende Abschnitt enthält Beispiele für häufige Fehlerszenarien, wenn Sie bei Bedarf keine erweiterten Abfrageparameter verwenden.

Das Zählen von Verzeichnisobjekten wird nur mithilfe der erweiterten Abfrageparameter unterstützt. Wenn der ConsistencyLevel=eventual Header nicht angegeben ist, gibt die Anforderung einen Fehler zurück, wenn das $count URL-Segment (/$count) verwendet wird, oder ignoriert den $count Abfrageparameter (?$count=true), wenn er verwendet wird.

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

Bei Verzeichnisobjekten funktioniert $search nur in erweiterten Abfragen. Wenn der ConsistencyLevel-Header nicht angegeben ist, gibt die Anforderung einen Fehler zurück.

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

Wenn eine Eigenschaft oder ein Abfrageparameter in der URL nur in erweiterten Abfragen unterstützt wird, aber entweder der ConsistencyLevel-Header oder die $count=true-Abfragezeichenfolge fehlt, gibt die Anforderung einen Fehler zurück.

GET https://graph.microsoft.com/beta/users?$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')


// 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"
        }
    }
}

Wenn eine Eigenschaft nicht zur Unterstützung eines Abfrageparameters indiziert ist, gibt die Anforderung auch dann einen Fehler zurück, wenn erweiterte Abfrageparameter angegeben sind. Beispielsweise ist die createdDateTime-Eigenschaft der Gruppenressource nicht für Abfragefunktionen indiziert.

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

Eine Anforderung, die Abfrageparameter enthält, kann jedoch im Hintergrund fehlschlagen. Beispielsweise für nicht unterstützte Abfrageparameter und für nicht unterstützte Kombinationen von Abfrageparametern. Untersuchen Sie in diesen Fällen die von der Anforderung zurückgegebenen Daten, um zu ermitteln, ob die von Ihnen angegebenen Abfrageparameter die gewünschte Wirkung hatten. Im folgenden Beispiel fehlt beispielsweise der Parameter @odata.count, auch wenn die Abfrage erfolgreich war.

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":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

Freigeben über

Erweiterte Abfragefunktionen für Microsoft Entra ID-Objekte

Microsoft Entra ID (Verzeichnis)-Objekte, die erweiterte Abfragefunktionen unterstützen

Abfrageszenarien, die erweiterte Abfragefunktionen erfordern

Unterstützung für das Filtern nach Eigenschaften von Microsoft Entra ID (Verzeichnis)-Objekten

Legende

Eigenschaften von Verwaltungseinheiten

Anwendungseigenschaften

Vertragseigenschaften

Geräteeigenschaften

Verzeichnisrolleneigenschaften

Gruppeneigenschaften

Kontakteigenschaften der Organisation

Dienstprinzipaleigenschaften

Benutzereigenschaften

Unterstützung für die Sortierung nach Eigenschaften von Microsoft Entra ID (Verzeichnis)-Objekten

Legende

Fehlerbehandlung bei erweiterten Abfragen für Verzeichnisobjekten

Feedback

Zusätzliche Ressourcen

Freigeben über

Erweiterte Abfragefunktionen für Microsoft Entra ID-Objekte

Microsoft Entra ID (Verzeichnis)-Objekte, die erweiterte Abfragefunktionen unterstützen

Abfrageszenarien, die erweiterte Abfragefunktionen erfordern

Unterstützung für das Filtern nach Eigenschaften von Microsoft Entra ID (Verzeichnis)-Objekten

Legende

Eigenschaften von Verwaltungseinheiten

Anwendungseigenschaften

Vertragseigenschaften

Geräteeigenschaften

Verzeichnisrolleneigenschaften

Gruppeneigenschaften

Kontakteigenschaften der Organisation

Dienstprinzipaleigenschaften

Benutzereigenschaften

Unterstützung für die Sortierung nach Eigenschaften von Microsoft Entra ID (Verzeichnis)-Objekten

Legende

Fehlerbehandlung bei erweiterten Abfragen für Verzeichnisobjekten

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen