Verwenden von Abfrageparametern zum Anpassen von Antworten

Microsoft Graph unterstützt optionale Abfrageparameter, die Sie zum Festlegen und Steuern der in einer Antwort zurückgegebenen Datenmenge verwenden können. Die Unterstützung der Abfrageparameter ist je nach API-Vorgang unterschiedlich, und je nach API sind v1.0- oder Beta-Endpunkte verfügbar.

Tipp

Am Beta-Endpunkt ist das $-Präfix optional. Sie können z. B. filter anstelle von $filter verwenden. Beim v1-Endpunkt ist das $-Präfix für nur eine Teilmenge der APIs optional. Verwenden Sie zur Vereinfachung immer $ wenn Sie den v1-Endpunkt verwenden.

Abfrageparameter können OData-Systemabfrageoptionen oder andere Abfrageparameter sein.

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.

Klicken Sie auf die Beispiele, um sie im Graph-Tester auszuprobieren.

Name Beschreibung Beispiel
$count Dient zum Abrufen der Gesamtzahl übereinstimmender Ressourcen. /me/messages?$top=2&$count=true
$expand Dient zum Abrufen von verwandten Ressourcen. /groups?$expand=members
$filter Dient zum Filtern von Ergebnissen (Zeilen). /users?$filter=startswith(givenName,'J')
$format Dient zum Zurückgeben der Ergebnisse im angegebenen Medienformat. /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 Indizes in einem Resultset. Wird auch von einigen APIs verwendet, um Paging zu implementieren, und kann zusammen 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 Optional-Abfrageparameter Abschnitt der LIST- und GET-Vorgänge für die API.

Andere Abfrageparameter

Name Beschreibung Beispiel
$skipToken Dient zum Abrufen der nächsten Seite von Ergebnissen aus Resultsets, die mehrere Seiten umfassen. (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 Ruft die ganzzahlige Summe der Sammlung ab. GET /users/$count
GET /groups/{id}/members/$count
$ref Aktualisiert die Mitgliedschaft von Entitäten in einer Sammlung. POST /groups/{id}/members/$ref
$value Ruft den Binärwert eines Elements ab oder aktualisiert ihn. GET /me/photo/$value
$batch Kombinieren Sie mehrere HTTP-Anforderungen in einer Batchanforderung. POST /$batch

Codieren von Abfrageparametern

Die Werte von Abfrageparametern sollten gemäß RFC 3986 prozent codiert sein. Beispielsweise müssen alle reservierten Zeichen in Abfragezeichenfolgen prozentual codiert sein. Viele HTTP-Clients, Browser und Tools (z. B. der Graph-Tester) sind Ihnen dabei behilflich. Wenn bei einer Abfrage ein Fehler auftritt, kann eine der möglichen Ursachen dafür sein, dass die Werte von Abfrageparametern nicht ordnungsgemäß codiert wurden. In einigen Fällen müssen Sie die Werte möglicherweise doppelt codieren.

Hinweis

Es gibt ein bekanntes Problem im Zusammenhang mit der Codierung 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

Für Anfragen, die einfache Anführungszeichen verwenden, müssen doppelte Escapezeichen verwendet werden, wenn andere Parameterwerte auch einfache Anführungszeichen enthalten. Andernfalls tritt bei der Anfrage ein Fehler aufgrund einer ungültigen Syntax auf. 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-Parameter

Verwenden Sie den $count Abfrageparameter, um die Gesamtzahl der Elemente in einer Auflistung oder eines entsprechenden Ausdrucks abzurufen. $countkönnen auf folgende Weise verwendet werden:

  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. Kann auch als URL-Segment verwendet werden, um die ganzzahlige Summe der Sammlung abzurufen. Beispiel: users/$count.
  3. In einem $filter Ausdruck mit Gleichheitsoperatoren, um eine Auflistung von Daten abzurufen, wobei 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 für Azure AD B2C-Mandanten nicht unterstützt.

Die folgende Anforderung gibt beispielsweise sowohl die contact-Sammlung des aktuellen Benutzers als auch die Anzahl von Elementen in der contact-Sammlung in der @odata.count-Eigenschaft zurück.

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

Der Abfrageparameter $count wird für Sammlungen der folgenden häufig verwendeten Ressourcen und deren Beziehungen, die sich aus directoryObject ableiten, und nur in erweiterten Abfragen unterstützt:

expand-Parameter

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.

Normalerweise können Sie die Eigenschaften einer Ressource oder eine ihrer Beziehungen in einer einzelnen Anforderung abfragen, aber nicht beides gleichzeitig. 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. In einer einzelnen Anforderung kann nur eine Beziehung 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. Sie können z. B. die directReports-, manager- und memberOf-Beziehungen für einen Benutzer erweitern, aber nicht die Beziehungen events, messages oder photo. 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 mit erweiterten Abfragenunterstützt.

filter-Parameter

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

format-Parameter

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

Die folgende Anforderung gibt beispielsweise die Benutzer in der Organisation im JSON-Format zurück:

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

Hinweis

Der $format-Abfrageparameter unterstützt eine Reihe von Formaten (z. B. Atom, XML und JSON), die Ergebnisse werden aber möglicherweise nicht in allen Formaten zurückgegeben.

orderby-Parameter

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

Die folgende Anforderung gibt beispielsweise die Benutzer in der Organisation sortiert nach ihrem Anzeigenamen zurück:

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

Sie können auch nach komplexen Typentitäten sortieren. 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

Wenn Sie die Ergebnisse in aufsteigender oder absteigender Reihenfolge sortieren möchten, fügen Sie entweder asc oder desc getrennt durch ein Leerzeichen an den Namen des Felds an, z. B. ?$orderby=name%20desc. Wenn die Sortierreihenfolge nicht angegeben ist, wird der Standardwert (aufsteigende Reihenfolge) verwendet.

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 $filter angeben, leitet der Server 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 in Verzeichnisobjekten.

search-Parameter

Um die Ergebnisse einer Anforderung so zu beschränken, dass sie einem Suchkriterium entsprechen, verwenden Sie den $search-Abfrageparameter. Syntax und Verhalten variieren je nach API-Vorgang. Informationen zur Syntax für $search in verschiedenen Ressourcen finden Sie unter Verwenden des $search-Abfrageparameters zum Abgleichen eines Suchkriteriums.

select-Parameter

Verwenden Sie den $select-Abfrageparameter, um eine Reihe von Eigenschaften zurückzugeben, die sich von den Standardeigenschaften für eine einzelne Ressource oder eine Sammlung von Ressourcen unterscheidet. Mit $select können Sie eine Teilmenge oder eine Obermenge der Standardeigenschaften angeben.

Wenn Sie eine GET-Anforderung ausführen, ohne $select die Menge der Eigenschaftendaten zu begrenzen, 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 bietet:

"@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 z. B. 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

Im Allgemeinen wird empfohlen, dass Sie $select verwenden, um die von einer Abfrage zurückgegebenen Eigenschaften auf diejenigen zu beschränken, die von Ihrer App benötigt werden. Dies gilt insbesondere für Abfragen, die möglicherweise ein großes Resultset zurückgeben. Durch Beschränken der in den einzelnen Zeilen zurückgegebenen Eigenschaften werden die Netzwerklast reduziert und die Leistung Ihrer App verbessert.

In v1.0geben einige Microsoft Entra Ressourcen, die von directoryObject abgeleitet werden, wie z. B. Benutzer und Gruppe, eine eingeschränkte 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.

skip-Parameter

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 Ergebnisse einer Abfrage 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-Parameter

Einige Abfragen geben mehrere Seiten von Daten zurück, entweder aufgrund von serverseitigem Paging oder aufgrund der Verwendung des $top-Parameters, um die Seitengröße der Antwort zu begrenzen. Viele Microsoft Graph-APIs verwenden den skipToken-Abfrageparameter, um auf nachfolgende Seiten des Ergebnisses zu verweisen.
Der $skiptoken-Parameter enthält ein undurchsichtiges Token, das auf die nächste Seite von Ergebnissen verweist und in der URL zurückgegeben wird, die in der @odata.nextLink-Eigenschaft in der Antwort bereitgestellt wird. 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 ConsistencyLevel-Header, der für erweiterte Abfragen von Verzeichnisobjekten erforderlich ist, ist in nachfolgenden Seitenanforderungen standardmäßig nicht enthalten. Er muss auf nachfolgenden Seiten explizit festgelegt werden.

top-Parameter

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

Wenn mehr Elemente im Resultset verbleiben, enthält der Antworttext einen @odata.nextLink-Parameter. 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 ConsistencyLevel-Header, der für erweiterte Abfragen von Verzeichnisobjekten erforderlich ist, 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 beispielsweise 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"
        }
    }
}

Beachten Sie jedoch, dass Abfrageparameter, die in einer Anforderung angegeben sind, im Hintergrund einen Fehler verursachen können. Dies gilt für nicht unterstützte Abfrageparameter sowie für nicht unterstützte Kombinationen von Abfrageparametern. In diesen Fällen sollten Sie die von der Anforderung zurückgegebenen Daten überprüfen, um zu ermitteln, ob die angegebenen Abfrageparameter den gewünschten Effekt erzielt haben.