Table of contents

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

Jimaco Brannian|Zuletzt aktualisiert: 07.09.2016
|
1 Mitwirkender

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

Die Funktionen der Azure AD Graph-API sind auch über Microsoft Graph verfügbar. Dies ist eine einheitliche API, die auch APIs von anderen Microsoft-Diensten wie Outlook, OneDrive, OneNote, Planner und Office Graph enthält. Auf alle wird über einen einzigen Endpunkt mit einem einzigen Zugriffstoken zugegriffen.

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.

$orderby

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

AnforderungBeschreibung
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6Gibt eine nach dem Anzeigenamen sortierte Liste der Benutzer zurück.
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6Gibt 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:

AnforderungBeschreibung
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6Gibt das Gruppenobjekt sowie seine Mitglieder zurück.
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6Gibt das Benutzerobjekt sowie seine direkt unterstellten Mitarbeiter zurück.
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6Gibt 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:

AnforderungBeschreibung
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:

AnforderungBeschreibung
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=trueDer $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:

  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.

Ressource der obersten EbeneAbfrageergebnisseURI (für contoso.com)
Ressourcen der obersten EbeneGibt die URI-Liste der Ressourcen oberster Ebene für Verzeichnisdienste (siehe unten) zurück.https://graph.windows.net/contoso.com?api-version=1.6
UnternehmensinformationenGibt Unternehmensinformationen zurück.https://graph.windows.net/contoso.com/tenantDetails?api-version=1.6
KontakteGibt Organisationskontaktinformationen zurück.https://graph.windows.net/contoso.com/contacts?api-version=1.6
UsersGibt Benutzerinformationen zurück.https://graph.windows.net/contoso.com/users?api-version=1.6
GruppenGibt Gruppendaten zurück.https://graph.windows.net/contoso.com/groups?api-version=1.6
VerzeichnisrollenGibt alle aktivierten Verzeichnisrollen im Mandanten zurück.https://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkusGibt die Abonnements des Mandanten zurück.https://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
VerzeichnismetadatenGibt 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.

AbfragevorgangURI (für contoso.com)
Auflisten aller Benutzer und Gruppenhttps://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 userPrincipalNamehttps://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" isthttps://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6
Anfordern und Herausfiltern bestimmter Benutzer, deren firstName "Jon" isthttps://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6
Herausfiltern der Werte givenName und surnamehttps://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6
Abrufen einzelner Gruppen durch Angabe von objectIdhttps://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
Abrufen des Vorgesetzten eines Benutzershttps://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 sindhttps://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 Benutzershttps://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6
Abrufen der Mitgliederliste einer Gruppehttps://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 Gruppehttps://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" isthttps://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-Mandantenhttps://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-Mandantenhttps://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

Zusätzliche Ressourcen

© 2017 Microsoft