Freigeben über


Anpassen von Microsoft Graph-Antworten mit Abfrageparametern

Abfrageparameter helfen Ihnen bei der Optimierung von Microsoft Graph-API Antworten, indem sie genau steuern, welche Daten zurückgegeben werden. Anstatt alle verfügbaren Eigenschaften und Daten abzurufen, können Sie Abfrageparameter für Folgendes verwenden:

  • Filtern von Ergebnissen, um nur die benötigten Datensätze abzurufen
  • Auswählen bestimmter Eigenschaften, um die Antwortgröße zu reduzieren und die Leistung zu verbessern
  • Sortieren und Paginieren von Daten für eine bessere Benutzererfahrung
  • Erweitern verwandter Ressourcen zum Abrufen verbundener Daten in einer einzelnen Anforderung

In diesem Artikel wird erläutert, wie Sie OData-Systemabfrageoptionen und andere Microsoft Graph-Abfrageparameter effektiv verwenden. Sie lernen die Syntax kennen, sehen sich praktische Beispiele an und entdecken bewährte Methoden zum Erstellen effizienter Abfragen, die die Leistung Ihrer Anwendung verbessern.

Die Unterstützung für bestimmte Abfrageparameter variiert zwischen API-Vorgängen und kann sich zwischen v1.0 - und Beta-Endpunkten unterscheiden.

Tipp

Auf dem Betaendpunkt ist das $ Präfix optional. Sie können z. B. filter anstelle von $filter verwenden. Auf dem v1.0-Endpunkt ist das $ Präfix nur für eine Teilmenge der APIs optional. Der Einfachheit halber müssen Sie immer alle Versionen einbeziehen$.

OData-System-Abfrageoptionen

Ein Microsoft Graph-API-Vorgang kann eine oder mehrere der folgenden OData-System-Abfrageoptionen unterstützen. Diese Abfrageoptionen sind mit der OData V4-Abfragesprache kompatibel und werden nur in GET-Vorgängen unterstützt.

Wählen Sie die Beispiele aus, um sie in Graph Explorer auszuprobieren.

Name Beschreibung Beispiel
$count Gibt die Gesamtzahl der übereinstimmenden Ressourcen zurück. /me/messages?$top=2&$count=true
$expand Gibt verwandte Ressourcen zurück. /groups?$expand=members
$filter Dient zum Filtern von Ergebnissen (Zeilen). /users?$filter=startswith(givenName,'J')
$format Gibt Ergebnisse im angegebenen Medienformat zurück. /users?$format=json
$orderby Dient zum Sortieren von Ergebnissen. /users?$orderby=displayName desc
$search Dient zum Zurückgeben von Ergebnissen basierend auf Suchkriterien. /me/messages?$search=pizza
$select Dient zum Filtern von Eigenschaften (Spalten). /users?$select=givenName,surname
$skip Überspringt Elemente in einem Resultset. Wird auch von einigen APIs verwendet, um Paging zu implementieren, und kann mit $top verwendet werden, um Ergebnisse manuell auszugeben. /me/messages?$skip=11
$top Dient zum Festlegen der Seitengröße von Ergebnissen. /users?$top=2

Informationen zu den OData-Systemabfrageoptionen, die von einer API und ihren Eigenschaften unterstützt werden, finden Sie in der Tabelle "Eigenschaften" auf der Ressourcenseite und im Abschnitt "Optionale Abfrageparameter" der LIST- und GET-Vorgänge für die API.

Andere Abfrageparameter

Name Beschreibung Beispiel
$skipToken Gibt die nächste Seite der Ergebnisse aus Resultsets zurück, die sich über mehrere Seiten erstrecken. (Einige APIs verwenden $skip stattdessen.) /users?$skiptoken=X%274453707402000100000017...

Andere OData-URL-Funktionen

Die folgenden OData 4.0-Funktionen sind URL-Segmente, keine Abfrageparameter.

Name Beschreibung Beispiel
$count Gibt die ganzzahlige Summe der Auflistung zurück. GET /users/$count
GET /groups/{id}/members/$count

Abrufen der Anzahl von Benutzern
$ref Aktualisiert die Mitgliedschaft von Entitäten in einer Sammlung. POST /groups/{id}/members/$ref

Hinzufügen eines Mitglieds zu einer Gruppe
$value Gibt den Binärwert eines Elements zurück oder aktualisiert diesen. GET /me/photo/$value

Abrufen des Fotos für einen Benutzer, eine Gruppe oder ein Team
$batch Kombiniert mehrere HTTP-Anforderungen in einer Batchanforderung. POST /$batch

JSON-Batchverarbeitung

Codieren von Abfrageparametern

Prozentcodierte Abfrageparameterwerte gemäß RFC 3986. Alle reservierten Zeichen in Abfragezeichenfolgen müssen prozentual codiert sein. Viele HTTP-Clients, Browser und Tools (z. B. die Graph-Explorer) verarbeiten diese Codierung automatisch. Wenn eine Abfrage fehlschlägt, ist eine mögliche Ursache ein Fehler beim Codieren der Abfrageparameterwerte. Manchmal müssen Sie Werte doppelt codieren.

Hinweis

Es gibt ein bekanntes Problem beim Codieren von amper- und (&)-Symbolen in $search Ausdrücken auf dem v1.0-Endpunkt . Weitere Informationen zu dem Problem und die empfohlene Problemumgehung finden Sie unter Bekanntes Problem: $search für Verzeichnisobjekte schlägt für codiertes kaufmännisches und -zeichen (&) fehl.

Eine nicht codierte URL sieht beispielsweise wie folgt aus:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')

Die ordnungsgemäß prozentcodierte URL sieht wie folgt aus:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')

Die doppelt codierte URL sieht wie folgt aus:

GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29

Escapezeichen für einfache Anführungszeichen

Bei Anforderungen, die einfache Anführungszeichen verwenden, sollten Parameterwerte, die auch einfache Anführungszeichen enthalten, doppelt mit Escapezeichen versehen werden. Andernfalls schlägt die Anforderung aufgrund einer ungültigen Syntax fehl. Im Beispiel wurden für den Zeichenfolgenwert let''s meet for lunch? Escapezeichen für das einfache Anführungszeichen verwendet.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'

Count

Verwenden Sie den $count Abfrageparameter, um die Anzahl der Gesamtanzahl von Elementen in einer Auflistung oder einem übereinstimmenden Ausdruck abzurufen. Sie können auf folgende Weise verwenden $count :

  1. Als Abfragezeichenfolgenparameter mit der Syntax $count=true , die eine Anzahl der Gesamtanzahl von Elementen in einer Auflistung zusammen mit der Seite der von Microsoft Graph zurückgegebenen Datenwerte einschließt. Beispiel: users?$count=true.
  2. Als URL-Segment , um nur die ganzzahlige Summe der Sammlung abzurufen. Beispiel: users/$count.
  3. In einem $filter Ausdruck mit Gleichheitsoperatoren, um eine Sammlung von Daten abzurufen, bei denen die gefilterte Eigenschaft eine leere Auflistung ist. Weitere Informationen finden Sie unter Verwenden des abfrageparameters $filter, um eine Auflistung von Objekten zu filtern.

Hinweis

  1. Bei Ressourcen, die vondirectoryObject,$countabgeleitet sind, wird dies nur in einer erweiterten Abfrage unterstützt. Weitere Informationen finden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.
  2. Die Verwendung von $count wird in Azure AD B2C-Mandanten nicht unterstützt.

Die folgende Anforderung gibt beispielsweise sowohl die Kontaktauflistung des aktuellen Benutzers als auch die Anzahl der Elemente in der Kontaktauflistung in einer @odata.count-Eigenschaft zurück.

GET  https://graph.microsoft.com/v1.0/me/contacts?$count=true

Für Verzeichnisobjekte, d. h. Ressourcen, die von directoryObject abgeleitet werden, wird der $count Abfrageparameter nur in erweiterten Abfragen unterstützt.

Expand

Viele Microsoft Graph-Ressourcen machen sowohl deklarierte Eigenschaften der Ressource als auch deren Beziehungen zu anderen Ressourcen verfügbar. Diese Beziehungen werden auch als Verweiseigenschaften oder Navigationseigenschaften bezeichnet und können auf eine einzelne Ressource oder auf eine Sammlung von Ressourcen verweisen. Beispielsweise werden die E-Mail-Ordner, die Vorgesetzten und die direkten Mitarbeiter eines Benutzers alle als Beziehungen verfügbar gemacht.

Sie können den $expand-Zeichenfolgen-Abfrageparameter verwenden, um die erweiterte Ressource oder die Sammlung, auf die von einer einzigen Beziehung verwiesen wird (Navigationseigenschaft) in Ihre Ergebnisse einzuschließen. Bei einigen APIs kann nur eine Beziehung in einer einzelnen Anforderung erweitert werden.

Im folgenden Beispiel werden Informationen des Stammlaufwerks zusammen mit den untergeordneten Elementen der obersten Ebene in einem Laufwerk abgerufen:

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children

Bei einigen Ressourcensammlungen können Sie auch die Eigenschaften angeben, die in den erweiterten Ressourcen zurückgegeben werden sollen, indem Sie einen $select Parameter hinzufügen. Im folgenden Beispiel wird dieselbe Abfrage wie im vorherigen Beispiel ausgeführt, aber es wird eine $select -Anweisung verwendet, um die für die erweiterten untergeordneten Elemente zurückgegebenen Eigenschaften auf die Eigenschaften id und name zu beschränken.

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)

Hinweis

  • Nicht alle Beziehungen und Ressourcen unterstützen den $expand-Abfrageparameter. Beispielsweise können Sie die DirectReports-, Manager- und memberOf-Beziehungen für einen Benutzer erweitern, aber Sie können seine Ereignisse, Nachrichten oder Fotobeziehungen nicht erweitern. Nicht alle Ressourcen oder Beziehungen unterstützen die Verwendung von $select in erweiterten Elementen.

  • Bei Microsoft Entra Ressourcen, die von directoryObject abgeleitet werden, z. B. Benutzer und Gruppe, $expand gibt in der Regel maximal 20 Elemente für die erweiterte Beziehung zurück und verfügt nicht über @odata.nextLink. Weitere Informationen finden Sie unter Einschränkungen von Abfrageparametern.

  • $expand wird derzeit nicht für erweiterte Abfragen unterstützt.

Filter

Verwenden Sie den $filter Abfrageparameter, um nur eine Teilmenge einer Auflistung abzurufen. Eine Anleitung zur Verwendung von $filterfinden Sie unter Verwenden des abfrageparameters $filter zum Filtern einer Auflistung von -Objekten.

Format

Verwenden Sie zum Festlegen des Medienformats der von Microsoft Graph zurückgegebenen Elemente den $format-Abfrageparameter.

Die folgende Anforderung gibt beispielsweise die Benutzer im organization im JSON-Format zurück:

GET https://graph.microsoft.com/v1.0/users?$format=json

Hinweis

Der $format Abfrageparameter unterstützt viele Formate (z. B atom. , xmlund json), aber ergebnisse werden möglicherweise nicht in allen Formaten zurückgegeben.

OrderBy

Verwenden Sie zum Festlegen der Sortierreihenfolge der von Microsoft Graph zurückgegebenen Elemente den $orderby-Abfrageparameter. Die Standardreihenfolge ist aufsteigend.

Die folgende Anforderung gibt z. B. Benutzer im organization nach ihrem Anzeigenamen in aufsteigender Reihenfolge zurück:

GET https://graph.microsoft.com/v1.0/users?$orderby=displayName

Einige APIs unterstützen die Sortierung nach komplexen Typentitäten. Die folgende Anforderung ruft Nachrichten ab und sortiert sie nach dem Adressfeld der from-Eigenschaft , die vom komplexen Typ emailAddress ist:

GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address

Um Ergebnisse in aufsteigender oder absteigender Reihenfolge zu sortieren, fügen Sie entweder asc oder desc an den Feldnamen an, getrennt durch ein Leerzeichen, ?$orderby=name desc z. B. (nicht codiert), ?$orderby=name%20desc (URL-codiert). Wenn Sie die Sortierreihenfolge nicht angeben, wird die aufsteigende Reihenfolge abgeleitet.

Bei einigen APIs können Sie die Ergebnisse anhand mehrerer Eigenschaften sortieren. Die folgende Anforderung sortiert die Nachrichten im Posteingang des Benutzers beispielsweise zuerst nach dem Namen der Person, die die Nachricht gesendet hat, in absteigender Reihenfolge (von Z nach A) und anschließend nach dem Betreff in aufsteigender Reihenfolge (Standard).

GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$orderby=from/emailAddress/name desc,subject

Hinweis

Wenn Sie angeben $filter, leitet der Dienst eine Sortierreihenfolge für die Ergebnisse ab. Wenn Sie sowohl $orderby als auch $filter zum Abrufen von Nachrichten verwenden, müssen Sie Eigenschaften auf bestimmte Weise angeben, da der Server immer eine Sortierreihenfolge für die Ergebnisse eines $filter ableitet.

Das folgende Beispiel zeigt eine Abfrage, die nach den Eigenschaften subject und importance gefiltert ist und dann nach den Eigenschaften subject, importance und receivedDateTime in absteigender Reihenfolge sortiert werden.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=Subject eq 'welcome' and importance eq 'normal'&$orderby=subject,importance,receivedDateTime desc

Hinweis

Das Kombinieren der Abfrageparameter $orderby und $filter wird für Verzeichnisobjekte unterstützt. Weitere Informationen finden Sie unter Erweiterte Abfragefunktionen für Verzeichnisobjekte.

Verwenden Sie den $search Abfrageparameter, um die Anforderungsergebnisse so zu beschränken, dass sie einem Suchkriterium entsprechen. Die Syntax und das Verhalten variieren je nach Ressourcen. Weitere Informationen finden Sie unter Verwenden des abfrageparameters $search zum Abgleichen eines Suchkriteriums.

Auswählen

Verwenden Sie den $select Abfrageparameter, um eine Teilmenge der Eigenschaften für eine Ressource zurückzugeben. Mit $select können Sie eine Teilmenge oder eine Obermenge der Standardeigenschaften angeben.

Wenn Sie eine GET-Anforderung ausführen, ohne $select die Eigenschaftsdaten einzuschränken, enthält Microsoft Graph eine @microsoft.graph.tips-Eigenschaft , die eine Empfehlung für bewährte Methoden für die Verwendung $select ähnlich der folgenden Meldung bereitstellt:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Wenn Sie beispielsweise die Nachrichten des angemeldeten Benutzers abrufen, können Sie angeben, dass nur die Eigenschaften from und subject zurückgegeben werden:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Wichtig

Es wird empfohlen, dass Sie verwenden $select , um die von einer Abfrage zurückgegebenen Eigenschaften auf die von Ihrer App benötigten Eigenschaften zu beschränken. Dies gilt insbesondere für Abfragen, die möglicherweise ein großes Resultset zurückgeben. Das Einschränken der in jeder Zeile zurückgegebenen Eigenschaften reduziert die Netzwerklast und verbessert die Leistung Ihrer App.

In v1.0 geben einige Microsoft Entra Ressourcen, die von directoryObject abgeleitet werden, wie z. B. Benutzer und Gruppe, eine begrenzte Standardteilmenge von Eigenschaften für Lesevorgänge zurück. Für diese Ressourcen müssen Sie verwenden $select , um Eigenschaften außerhalb des Standardsatzes zurückzugeben.

Überspringen

Verwenden Sie den $skip Abfrageparameter, um die Anzahl der zu überspringenden Elemente am Anfang einer Sammlung festzulegen. Die folgende Anforderung gibt z. B. Ereignisse für den Benutzer zurück, die nach Erstellungsdatum sortiert sind, beginnend mit dem 21. Ereignis in der Auflistung:

GET  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20

Einige Microsoft Graph-APIs, z. B. Outlook-Mail und Outlook-Kalender (Nachricht, Ereignis und Kalender), verwenden $skip zur Implementierung von Paging. Wenn abfrageergebnisse mehrere Seiten umfassen, geben diese APIs eine @odata.nextLink-Eigenschaft mit einer URL zurück, die einen $skip Parameter enthält. Sie können diese URL verwenden, um die nächste Seite mit Ergebnissen zurückzugeben. Weitere Informationen finden Sie unter Paging.

Verzeichnisobjekte wie Benutzer, Gruppe und Anwendung unterstützen $skipnicht .

SkipToken

Einige Anforderungen geben mehrere Seiten mit Daten zurück, entweder aufgrund von serverseitigem Paging oder aufgrund der Verwendung des $top Parameters, um die Seitengröße der Antwort einzuschränken. Viele Microsoft Graph-APIs verwenden den skipToken-Abfrageparameter, um auf nachfolgende Seiten des Ergebnisses zu verweisen.
Dieser Parameter enthält ein nicht transparentes Token, das auf die nächste Ergebnisseite verweist und in der URL zurückgegeben wird, die in der @odata.nextLink-Eigenschaft in der Antwort angegeben ist. Weitere Informationen finden Sie unter Paging.

Hinweis

Wenn Sie die OData-Anzahl (durch Hinzufügen von $count=true in der Abfragezeichenfolge) bei Abfragen für Verzeichnisobjekte verwenden, ist die Eigenschaft @odata.count nur auf der ersten Seite vorhanden.

Der für erweiterte Abfragen von Verzeichnisobjekten erforderliche ConsistencyLevel-Header ist in nachfolgenden Seitenanforderungen standardmäßig nicht enthalten. Er muss auf nachfolgenden Seiten explizit festgelegt werden.

Oben

Verwenden Sie den $top Abfrageparameter, um die Anzahl der Elemente anzugeben, die in das Ergebnis eingeschlossen werden sollen.

Wenn weitere Elemente im Resultset verbleiben, enthält der Antworttext einen parameter @odata.nextLink . Dieser Parameter enthält eine URL, die Sie verwenden können, um die nächste Seite mit Ergebnissen abzurufen. Weitere Informationen finden Sie unter Paging.

Der Mindestwert von „$top“ ist „1“ und der Höchstwert hängt von der entsprechenden API ab.

Die folgende list messages-Anforderung gibt beispielsweise die ersten fünf Nachrichten im Postfach des Benutzers zurück:

GET https://graph.microsoft.com/v1.0/me/messages?$top=5

Hinweis

Der für erweiterte Abfragen von Verzeichnisobjekten erforderliche ConsistencyLevel-Header ist in nachfolgenden Seitenanforderungen standardmäßig nicht enthalten. Er muss auf nachfolgenden Seiten explizit festgelegt werden.

Fehlerbehandlung für Abfrageparameter

Einige Anforderungen geben eine Fehlermeldung zurück, wenn ein angegebener Abfrageparameter nicht unterstützt wird. Sie können z. B. nicht für die user/photo Beziehung verwenden$expand.

https://graph.microsoft.com/v1.0/me?$expand=photo
{
    "error":{
        "code":"ExpandNotSupported",
        "message":"Expand is not allowed for property 'Photo' according to the entity schema.",
        "innerError":{
            "request-id":"1653fefd-bc31-484b-bb10-8dc33cb853ec",
            "date":"2017-07-31T20:55:01"
        }
    }
}

Manchmal schlagen abfrageparameter, die in einer Anforderung angegeben sind, jedoch im Hintergrund fehl. 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.