Unterstützte Abfragen, Filter und Paginierungsoptionen | Graph-API-Konzepte

In diesem Artikel werden Abfrageoptionen, Filter- und Paginierungsvorgänge aufgeführt, die Sie mit der Azure AD (Active Directory) Graph-API verwenden können. Der letzte Abschnitt bietet Beispiele für allgemeine Abfragen, die Sie mit der Azure AD Graph-API ausführen können.

Adressierung

Alle folgenden Abfragen adressieren den Mandanten über einen Domänennamen. Sie können contoso.com durch einen der registrierten Domänennamen des Mandanten, durch die ID (GUID) des Mandanten oder durch den Alias MyOrganization (für delegierten Zugriff) ersetzen. In einigen Fällen können Sie möglicherweise den Alias me verwenden. Weitere Informationen über Methoden zur Adressierung des Mandanten finden Sie unter Übersicht über die Vorgänge.

Unterstützte Abfrageoptionen

Graph unterstützt die folgenden Abfrageoptionen: $filter, $orderby, $expand, $top und $format. Die folgenden Abfrageoptionen werden derzeit nicht unterstützt: $count, $inlinecount und $skip.

$filter

Die folgenden allgemeinen Einschränkungen gelten für Abfragen, die einen Filter enthalten:

• $filter darf nicht mit $orderby-Ausdrücken kombiniert werden.

• Filtervorgänge werden nicht für Abfragen der Verzeichnisobjekte DirectoryRole oder SubscribedSku unterstützt.

• Nicht alle Eigenschaften der unterstützten Verzeichnisobjekte können in einem Filterausdruck verwendet werden. Weitere Informationen zu filterbaren Eigenschaften unterstützter Typen finden Sie unter User, Group und Contact.

Für Filterausdrücke gelten die folgenden Einschränkungen:

• Logische Operatoren: and und or werden unterstützt. Beispiel: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=accountEnabled eq true and (userPrincipalName eq 'jonlawr@contoso.com' or mail eq 'jonlawr@contoso.com')

• Vergleichsoperatoren: eq (gleich), ge (größer als oder gleich) und le (kleiner als oder gleich) werden unterstützt.

• startswith wird unterstützt. Beispiel: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')

• any wird beim Abfragen mehrwertiger Eigenschaften unterstützt. Beispiel: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=userPrincipalName eq 'Mary@Contoso.com' or proxyAddresses/any(c:c eq 'smtp:Mary@Contoso.com')

• Arithmetische Operatoren: nicht unterstützt.

• Funktionen: nicht unterstützt.

• null-Werte werden nicht als Operand in Filterausdrücken unterstützt. Sie können beispielsweise keinen null-Wert angeben, um nicht festgelegte Eigenschaften herauszufiltern.

• Um eine binäre Eigenschaft wie issuerUserId in userIdentities filtern zu können, muss der Wert zunächst Base64-codiert werden, bevor er in der $filter-Zeichenfolge verwendet werden kann.

$orderby

$orderby sortiert die zurückgegebenen Objekte nach dem angegebenen Parameter. Beispielanforderungen unter Verwendung der $orderby-Option:

Für $orderby-Ausdrücke gelten die folgenden Einschränkungen:

• Derzeit werden zwei Sortierreihenfolgen unterstützt: DisplayName für User- und Group-Objekte und UserPrincipalName für User-Objekte. Die Standardsortierreihenfolge für Benutzer erfolgt nach UserPrincipalName.

• $orderby darf nicht mit $filter-Ausdrücken kombiniert werden.

$expand

$expand gibt ein Objekt und seine verknüpften Objekte zurück. Beispielanforderungen unter Verwendung der $expand-Option:

Für $expand-Ausdrücke gelten die folgenden Einschränkungen:

• Die maximale Anzahl zurückgegebener Objekte für eine Anforderung beträgt 20.

$top

$top wird in Abfragen für DirectoryRole oder SubscribedSku nicht unterstützt.

Unterstützung der Paginierung

Graph ermöglicht Vorwärts- und Rückwärtspaginierung. Eine Antwort, die in Seiten eingeteilte Ergebnisse enthält, umfasst ein Überspringungstoken (odata.nextLink), das Ihnen das Abrufen der nächsten Ergebnisseite ermöglicht. Dieses Überspringungstoken kann mit dem Abfrageargument previous-page=true kombiniert werden, um die vorherige Seite aufzurufen.

Die folgende Beispielabfrage zeigt Vorwärtspaginierung:

Die folgende Beispielabfrage zeigt Rückwärtspaginierung:

Die folgenden Schritte zeigen den Anforderungs-/Antwortdatenfluss für Vorwärts- und Rückwärtspaginierung:

1. Es erfolgt eine Anforderung zum Abrufen der ersten 10 Benutzer aus einer Liste von 15 Benutzern. Die Antwort enthält ein Überspringungstoken, um die letzte Seite mit 10 Benutzern anzugeben.
2. Zum Abrufen der restlichen 5 Benutzer wird eine weitere Anforderung ausgegeben, die das Überspringungstoken enthält, das von der vorherigen Antwort zurückgegeben wurde.
3. Für Rückwärtspaginierung wird eine Anforderung mithilfe des Überspringungstokens ausgegeben, das in Schritt 1 zurückgegeben wurde. Außerdem wird der Anforderung der Parameter &previous-page=true hinzugefügt.
4. Die Antwort enthält die vorherige (erste) Seite mit 10 Benutzern. In einem anderen Szenario, in dem eine größere Anzahl von Restseiten vorhanden ist, würde ein neues Überspringungstoken zurückgegeben. Dieses neue Überspringungstoken kann der Anforderung zusammen mit &previous-page=true hinzugefügt werden, um erneut die vorherige Seite aufzurufen.

Für Seitenanforderungen gelten die folgenden Einschränkungen:

• Die Standardseitengröße ist 100. Die maximale Seitengröße ist 999.
• Bei Abfragen für Rollen wird keine Paginierung unterstützt. Dies schließt auch das Lesen von Rollenobjekten sowie Rollenmitgliedern ein.
• Ressourcenlisten, z. B. die Suche nach allen Benutzern in einem Mandanten (/users), unterstützen keine Paginierung. Beispiel: https://graph.windows.net/contoso.com/users?api-version=1.6. Für alle Typen gilt jedoch, dass die Paginierung bei Anwendung eines Filters nicht unterstützt wird und dass nur die erste Ergebnisseite zurückgegeben wird.
• Paginierung wird für Linksuchvorgänge (z. B. für das Abgragen von Gruppenmitgliedern) nicht unterstützt. Beispiel: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.

Sortierreihenfolge

• Das Resultset einer Abfrage nach allen Benutzern wird anhand der UserPrincipalName-Eigenschaft sortiert. Beispiel: https://graph.windows.net/contoso.com/users?api-version=1.6.
• Das Resultset einer Abfrage nach allen anderen Ressourcen auf oberster Ebene (z. B. nach Gruppen, Kontakten usw.) wird anhand der objectId-Eigenschaft sortiert. Beispiel: https://graph.windows.net/contoso.com/groups?api-version=1.6.
• Die Reihenfolge der Abfrageergebnisse, die keine Ressourcen oberster Ebene betreffen, ist nicht festgelegt.

Allgemeine Abfragen

Die folgenden Abschnitte bieten Beispiele für allgemeine Abfragen, die Sie mit der Graph-API ausführen können.

Abfragen von Ressourcen der obersten Ebene

Die folgenden Abfragen demonstrieren, wie Sie mit der Graph-API auf Ressourcen der obersten Ebene zugreifen, wobei Sie „contoso.com“ als Beispielmandant verwenden. Beachten Sie, dass zum Ausführen von Abfragen für einen Mandanten ein Autorisierungsheader mit einem gültigen, von Azure AD empfangenen Trägertoken erforderlich ist.

Weitere Abfragevorgänge

Die folgende Tabelle enthält weitere Graph-API-Beispielabfragen mit „contoso.com“ als Beispielmandant.

Hinweis: Leerzeichen in der Abfragezeichenfolge sollten URL-codiert werden, bevor eine Anforderung gesendet wird. Die Abfragezeichenfolge https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 sollte beispielsweise wie folgt URL-codiert werden: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6

Zusätzliche Ressourcen

• Differenzielle Abfragen der Azure AD Graph-API
• Referenz zur Azure AD Graph-API