Erweiterte Abfragefunktionen für Azure AD-Verzeichnisobjekte

Artikel
07/18/2022
7 Minuten Lesedauer

Während Azure AD immer mehr Funktionen und Verbesserungen in Bezug auf Stabilität, Verfügbarkeit und Leistung bereitstellt, wird auch Microsoft Graph weiterentwickelt und skaliert, um effizient auf die Daten zugreifen zu können. Eine Möglichkeit bietet die zunehmende Unterstützung von Microsoft Graph für erweiterte Abfragefunktionen für verschiedene Azure AD-Objekte und deren Eigenschaften. Zum Beispiel die Hinzufügung der Operatoren Nicht (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 zusätzliche Abfragefunktionen für bestimmte Eigenschaften zu unterstützen, werden diese Eigenschaften jetzt auf einem separaten Speicher indiziert. Diese separate Indizierung ermöglicht es Azure AD, die Unterstützung zu erhöhen und die Leistung der Abfrageanforderungen zu verbessern. Diese erweiterten Abfragefunktionen sind jedoch standardmäßig nicht verfügbar, aber der Anforderer muss auch den ConsistencyLevel-Header festlegen auf eventual und, mit Ausnahme von $search, den $count Abfrageparameter 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 Abfrageparameter $filter mit dem Operator eq. Diese Anforderung funktioniert standardmäßig, d. h., für die Anforderung sind nicht die erweiterten Abfrageparameter erforderlich.

GET https://graph.microsoft.com/v1.0/users?$filter=accountEnabled eq false

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=CS
var user = await graphClient.Users.Request()
    .Filter("accountEnabled eq false")
    .GetAsync();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Javascript
let users = await client.api('/users')
  .filter('accountEnabled eq false')
  .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Objective-C
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users?$filter=accountEnabled eq false"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *usersDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

  NSError *jsonError = nil;
  MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
  MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[usersDataTask execute];

// See https://docs.microsoft.com/en-us/graph/sdks/create-client?tabs=Java
UserCollectionPage users = graphClient.users()
    .buildRequest()
    .filter("accountEnabled eq false")
    .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Go
requestParameters := &msgraphsdk.UsersRequestBuilderGetQueryParameters{
    Filter: "accountEnabled eq false",
}

options := &msgraphsdk.UsersRequestBuilderGetOptions{
    Q: requestParameters,
}

result, err := client.Users().Get(options)

Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "accountEnabled eq false"

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

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

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=CS
var user = await graphClient.Users.Request()
    .Request(new Option[] { new QueryOption("$count", "true")})
    .Header("ConsistencyLevel", "eventual")
    .Filter("accountEnabled ne true")
    .GetAsync();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Javascript
let users = await client.api('/users')
  .header('ConsistencyLevel','eventual')
  .filter('accountEnabled ne true')
  .count(true)
  .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Objective-C
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users?$filter=accountEnabled ne true&$count=true"]]];
[urlRequest setHTTPMethod:@"GET"];
[urlRequest setValue:@"eventual" forHTTPHeaderField:@"ConsistencyLevel"];

MSURLSessionDataTask *usersDataTask = [httpClient dataTaskWithRequest:urlRequest
completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

  NSError *jsonError = nil;
  MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
  MSGraphUser *user = [[MSGraphUser alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[usersDataTask execute];

// See https://docs.microsoft.com/en-us/graph/sdks/create-client?tabs=Java
LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));
requestOptions.add(new QueryOption("$count", "true"))

UserCollectionPage users = graphClient.users()
    .buildRequest(requestOptions)
    .filter("accountEnabled ne true")
    .get();

// See https://docs.microsoft.com/graph/sdks/create-client?tabs=Go
requestParameters := &msgraphsdk.UsersRequestBuilderGetQueryParameters{
    Filter: "accountEnabled ne true",
    Count: true,
}

headers := map[string]string{
    "ConsistencyLevel": "eventual"
}

options := &msgraphsdk.UsersRequestBuilderGetOptions{
    Q: requestParameters,
    H: headers,
}

result, err := client.Users().Get(options)

Import-Module Microsoft.Graph.Users

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

Diese erweiterten Abfragefunktionen werden nur für Azure AD-Verzeichnisobjekten und deren Beziehungen unterstützt, einschließlich der folgenden häufig verwendeten 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

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	GET `../groups/$count`
Verwenden von `$count` als Abfragezeichenfolgenparameter	GET `../servicePrincipals?$count=true`
Verwendung von`$count`in einem`$filter`Ausdruck	GET `../users?$filter=assignedLicenses/$count eq 0&$count=true`
Verwenden von `$search`	GET `../applications?$search="displayName:Browser"`
Verwenden von `$orderby` für bestimmte Eigenschaften	GET `../applications?$orderby=displayName&$count=true`
Verwenden von `$filter` mit dem Operator `endsWith`	GET `../users?$count=true&$filter=endsWith(mail,'@outlook.com')`
Verwendung von `$filter` und `$orderby` in derselben Abfrage	GET `../applications?$orderby=displayName&$filter=startsWith(displayName, 'Box')&$count=true`
Verwenden von `$filter` mit den `startsWith`-Operatoren für bestimmte Eigenschaften.	GET `../users?$filter=startsWith(mobilePhone, '25478') OR startsWith(mobilePhone, '25473')&$count=true`
Verwenden von `$filter` mit den Operatoren `ne` und `not`
GET `../users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true`
Verwenden von `$filter` mit den Operatoren `not` und `startsWith`
GET `../users?$filter=NOT startsWith(displayName, 'Conf')&$count=true`
Verwendung für `$filter` eine Sammlung mit `endsWith` Operator	[GET] (https://developer.microsoft.com/en-us/graph/graph-explorer?request=users%3F%24count%3Dtrue%26%24filter%3DproxyAddresses%2Fany(p%3AendsWith(p%2C%2B'OnMicrosoft.com'))%26select%3Did%2CdisplayName%2Cproxyaddresses&method=GET&version=beta&GraphUrl=https://graph.microsoft.com&headers=W3sibmFtZSI6IkNvbnNpc3RlbmN5TGV2ZWwiLCJ2YWx1ZSI6ImV2ZW50dWFsIn1d) `../users?$count=true&$filter=proxyAddresses/any(p:endsWith(p,+'OnMicrosoft.com'))&select=id,displayName,proxyaddresses`
Verwendung der OData-Umwandlung mit transitiver Memberliste	GET `../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 von Filtern für Eigenschaften von Azure AD-Verzeichnisobjekte

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

Abfragen, die standardmäßig unterstützt werden, funktionieren auch in erweiterten Abfragen, aber die Antwort ist letztendlich konsistent.
Der Operator in wird standardmäßig unterstützt, insofern der Operator eq standardmäßig unterstützt wird.
Der endsWith Operator wird nur mit erweiterten Abfragen für die Eigenschaften mail, otherMails, userPrincipalName und proxyAddresses unterstützt.
Die Negierungsoperatoren not und ne werden nur bei erweiterten Abfragen unterstützt.
- Alle Eigenschaften, die den Operator eq unterstützen, unterstützen auch die Operatoren ne oder not.
- Verwenden Sie für Abfragen, die den any-Lambdaoperator verwenden, den Operator not. Weitere Informationen finden Sie unter Filtern mit Lambdaoperatoren.

In den folgenden Tabellen wird die Unterstützung für $filter-Operatoren anhand der Eigenschaften von Verzeichnisobjekten zusammengefasst, die von den erweiterten Abfragefunktionen unterstützt werden.

Legende

Der Operator $filter funktioniert standardmäßig für diese Eigenschaft.
Der Operator $filter erfordert erweiterte Abfrageparameter wie:
- ConsistencyLevel=eventual-Header
- $count=true-Abfragezeichenfolge
Der Operator $filter 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 deuten darauf hin, 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

Eigenschaftenname	eq	startsWith	ge	le	Null-Wert
description
displayName
isMemberManagementRestricted

Anwendungseigenschaften

Eigenschaftenname	eq	startsWith	ge	le	Null-Wert
appId
createdDateTime
createdOnBehalfOf/deletedDateTime
createdOnBehalfOf/id
description
disabledByMicrosoftStatus
displayName
identifierUris/any(p:p)
info/logoUrl
info/termsOfServiceUrl
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)

Geräteeigenschaften

Eigenschaftenname	eq	startsWith	ge	le	Null-Wert
accountEnabled
alternativeSecurityIds/any(a:a/identityProvider)
alternativeSecurityIds/any(a:a/type)
approximateLastSignInDateTime
deviceId
displayName
extensionAttributes1-15
hostnames/any(p:p)
isCompliant
isManaged
mdmAppId
onPremisesLastSyncDateTime
onPremisesSyncEnabled
operatingSystem
operatingSystemVersion
physicalIds/any(p:p)
registrationDateTime

Gruppeneigenschaften

Eigenschaftenname	eq	startsWith	ge	le	Null-Wert
assignedLicenses/any(a:a/skuId)
classification
createdByAppId
createdOnBehalfOf/deletedDateTime
createdOnBehalfOf/id
description
displayName
expirationDateTime
hasMembersWithLicenseErrors
infoCatalogs/any(p:p)
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

Eigenschaften von Organisationskontakten

Eigenschaftenname	eq	startsWith	ge	le	Null-Wert
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

Dienstprinzipaleigenschaften

Eigenschaftenname	eq	startsWith	ge	le	Null-Wert
accountEnabled
alternativeNames/any(p:p)
appId
appOwnerOrganizationId
appRoleAssignmentRequired
applicationTemplateId
createdObjects/any(c:c/id)
description
displayName
homepage
info/logoUrl
info/termsOfServiceUrl
preferredTokenSigningKeyEndDateTime
publisherName
servicePrincipalNames/any(p:p)
tags/any(p:p)

Benutzereigenschaften

Eigenschaftenname	eq	startsWith	ge	le	Null-Wert
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)
Ort
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)
isResourceAccount
jobTitle
mail
mailNickname
manager/deletedDateTime
manager/id
mobilePhone
officeLocation
onPremisesExtensionAttributes/extensionAttribute1-15
onPremisesImmutableId
onPremisesLastSyncDateTime
onPremisesProvisioningErrors/any(o:o/category)
onPremisesProvisioningErrors/any(o:o/propertyCausingError)
onPremisesSamAccountName
onPremisesSecurityIdentifier
onPremisesSyncEnabled
onPremisesUserPrincipalName
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

Fehlerbehandlung bei erweiterten Abfragen für Verzeichnisobjekten

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

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

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

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

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.

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

Wenn eine Eigenschaft nicht indiziert wurde, um einen Abfrageparameter zu unterstützen, gibt die Anforderung auch dann einen Fehler zurück, wenn die erweiterten Abfrageparameter angegeben werden.

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

Beachten Sie jedoch, dass Abfrageparameter, die in einer Anforderung angegeben sind, im Hintergrund einen Fehler verursachen können. Dies gilt für nicht unterstützte Abfrageparameter sowie für nicht unterstützte Kombinationen von Abfrageparametern. In diesen Fällen sollten Sie die von der Anforderung zurückgegebenen Daten überprüfen, um zu ermitteln, ob die angegebenen Abfrageparameter den gewünschten Effekt erzielt haben. Im folgenden Beispiel fehlt beispielsweise der Parameter @odata.count, auch wenn die Abfrage erfolgreich war.

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