Erweiterte Abfragefunktionen für Microsoft Entra ID-Objekte
Artikel
Da Microsoft Entra weiterhin mehr Funktionen und Verbesserungen bei Stabilität, Verfügbarkeit und Leistung bietet, wird Microsoft Graph auch weiterentwickelt und skaliert, um effizient auf die Daten zuzugreifen. Eine Möglichkeit besteht darin, dass Microsoft Graph erweiterte Abfragefunktionen für verschiedene Microsoft Entra ID-Objekte, auch verzeichnisobjekte genannt, und deren Eigenschaften zunehmend unterstützt. 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 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 Microsoft Entra ID, die Unterstützung zu erhöhen und die Leistung der Abfrageanforderungen zu verbessern. Diese erweiterten Abfragefunktionen sind jedoch nicht standardmäßig verfügbar, aber der Anforderer muss auch 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, d. h., die Anforderung erfordert nicht die 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";
});
// 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";
});
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");
});
// 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");
});
Microsoft Entra ID (Verzeichnis)-Objekte, die erweiterte Abfragefunktionen unterstützen
Diese erweiterten Abfragefunktionen werden nur für Verzeichnisobjekte und deren Beziehungen unterstützt, einschließlich der folgenden häufig verwendeten Objekte:
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:
Abfragen, die standardmäßig unterstützt werden, funktionieren auch mit erweiterten Abfrageparametern, 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 Abfrageparametern nach den 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.
Legend
Der $filter Operator funktioniert standardmäßig für diese Eigenschaft.
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
scopedRoleMembers/any(s:s/id)
Anwendungseigenschaften
Eigenschaft
eq
startsWith
ge/le
eq Null
appId
createdDateTime
createdOnBehalfOf/id
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.
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.
Legend
Der $orderby Operator funktioniert standardmäßig für diese Eigenschaft.
Für $orderbyden Operator sinderweiterte Abfrageparameter erforderlich:
Fehlerbehandlung bei erweiterten Abfragen für Verzeichnisobjekten
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 verwendet wird, oder ignoriert den $count Abfrageparameter (?$count=true), wenn er verwendet wird.
// 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();
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
graphClient.users().count().get();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$graphServiceClient->users()->count()->get()->wait();
{
"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\"";
});
// 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\"";
});
{
"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,'";
});
// 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,'";
});
{
"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 wurde, gibt die Anforderung auch dann einen Fehler zurück, wenn die erweiterten Abfrageparameter angegeben sind.
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");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta groups list --filter "createdDateTime ge 2021-11-01" --count "true" --consistency-level "eventual"
// 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");
});
{
"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;
});
// 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;
});
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.