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.
Wichtig
Es wird dringend empfohlen, für den Zugriff auf Azure Active Directory-Ressourcen Microsoft Graph zu verwenden, nicht die Azure AD Graph-API. Wir konzentrieren unsere Entwicklungsarbeit auf Microsoft Graph, weitere Verbesserungen für die Azure AD Graph-API sind nicht geplant. Es gibt einige wenige Szenarien, in denen die Azure AD Graph-API möglicherweise noch geeignet ist. Weitere Informationen finden Sie im Office Dev Center im Blogbeitrag Microsoft Graph or the Azure AD Graph.
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:
| Anforderung | Beschreibung |
|---|---|
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6 |
Gibt eine nach dem Anzeigenamen sortierte Liste der Benutzer zurück. |
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6 |
Gibt die ersten 60 Benutzer nach ihrem Anzeigenamen sortiert zurück. |
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:
| Anforderung | Beschreibung |
|---|---|
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6 |
Gibt das Gruppenobjekt sowie seine Mitglieder zurück. |
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6 |
Gibt das Benutzerobjekt sowie seine direkt unterstellten Mitarbeiter zurück. |
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6 |
Gibt das Benutzerobjekt sowie seinen Vorgesetzten zurück. |
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:
| Anforderung | Beschreibung |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000' |
Der $skiptoken-Parameter aus der vorherigen Antwort ist enthalten und ermöglicht das Abrufen der nächsten Seite mit Ergebnissen. |
Die folgende Beispielabfrage zeigt Rückwärtspaginierung:
| Anforderung | Beschreibung |
|---|---|
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=true |
Der $skiptoken-Parameter aus der vorherigen Antwort ist enthalten. Wenn dieser mit dem Parameter &previous-page=true kombiniert wird, werden die Ergebnisse der vorherigen Seite abgerufen. |
Die folgenden Schritte zeigen den Anforderungs-/Antwortdatenfluss für Vorwärts- und Rückwärtspaginierung:
- 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.
- Zum Abrufen der restlichen 5 Benutzer wird eine weitere Anforderung ausgegeben, die das Überspringungstoken enthält, das von der vorherigen Antwort zurückgegeben wurde.
- 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.
- 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.
| Ressource der obersten Ebene | Abfrageergebnisse | URI (für contoso.com) |
|---|---|---|
| Ressourcen der obersten Ebene | Gibt die URI-Liste der Ressourcen oberster Ebene für Verzeichnisdienste (siehe unten) zurück. | https://graph.windows.net/contoso.com?api-version=1.6 |
| Unternehmensinformationen | Gibt Unternehmensinformationen zurück. | https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6 |
| Kontakte | Gibt Organisationskontaktinformationen zurück. | https://graph.windows.net/contoso.com/contacts?api-version=1.6 |
| Users | Gibt Benutzerinformationen zurück. | https://graph.windows.net/contoso.com/users?api-version=1.6 |
| Gruppen | Gibt Gruppendaten zurück. | https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Verzeichnisrollen | Gibt alle aktivierten Verzeichnisrollen im Mandanten zurück. | https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6 |
| SubscribedSkus | Gibt die Abonnements des Mandanten zurück. | https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6 |
| Verzeichnismetadaten | Gibt ein Dienstmetadatendokument zurück, das das Datenmodell beschreibt (d. h. die Struktur und Organisation von Verzeichnisressourcen). | https://graph.windows.net/contoso.com/$metadata?api-version=1.6 |
Weitere Abfragevorgänge
Die folgende Tabelle enthält weitere Graph-API-Beispielabfragen mit „contoso.com“ als Beispielmandant.
| Abfragevorgang | URI (für contoso.com) |
|---|---|
| Auflisten aller Benutzer und Gruppen | https://graph.windows.net/contoso.com/users?api-version=1.6 https://graph.windows.net/contoso.com/groups?api-version=1.6 |
| Abrufen einzelner Benutzer durch Angabe von objectId oder userPrincipalName | https://graph.windows.net/contoso.com/users/d1f67a6c-02c9-4fe5-81fb-58160ce24fe5?api-version=1.6 https://graph.windows.net/contoso.com/users/admin@contoso.com?api-version=1.6 |
| Anfordern und Herausfiltern eines Benutzers, dessen displayName "Jon Doe" ist | https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6 |
| Anfordern und Herausfiltern bestimmter Benutzer, deren firstName "Jon" ist | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6 |
| Herausfiltern der Werte givenName und surname | https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6 |
| Abrufen einzelner Gruppen durch Angabe von objectId | https://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6 |
| Abrufen des Vorgesetzten eines Benutzers | https://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6 |
| Abrufen einer Liste mit Mitarbeitern, die dem Benutzer direkt unterstellt sind | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6 |
| Abrufen einer Liste mit Links zu den direkt unterstellten Mitarbeitern eines Benutzers | https://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6 |
| Abrufen der Mitgliederliste einer Gruppe | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6 |
| Abrufen einer Liste von Links zu den Mitgliedern einer Gruppe | https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6 |
| Abrufen der Gruppenmitgliedschaft eines Benutzers (nicht transitiv) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6 |
| Abrufen einer Liste der Gruppen, denen der Benutzer als Mitglied angehört (nicht transitiv) | https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6 |
| Anfordern und Herausfiltern von Gruppen, deren displayName => "az" und <= "dz" ist | https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6 |
| Zurückgeben aller Benutzer eines lokalen Kontos in einem Azure Active Directory B2C-Mandanten | https://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6 |
| Zurückgeben des Benutzers des lokalen Kontos mit dem Anmeldenamen „joe@example.com“ von einem Azure Active Directory B2C-Mandanten | https://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6 |
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