Teilen über


Verwenden von Abfrageparametern zum Anpassen von Antworten

Microsoft Graph unterstützt Abfrageparameter, mit denen Sie die Menge der in einer Antwort zurückgegebenen Daten angeben und steuern können. Die Unterstützung für die genauen Abfrageparameter variiert je nach API-Vorgang und kann je nach API zwischen v1.0 - und Betaendpunkten variieren.

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$.

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 "Optionale Abfrageparameter" 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

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 Ruft den Binärwert eines Elements ab oder aktualisiert ihn. GET /me/photo/$value

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

JSON-Batchverarbeitung

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. graph-Explorer) übernehmen diese Codierung für Sie. Wenn eine Abfrage fehlschlägt, ist eine mögliche Ursache ein Fehler beim Codieren der Abfrageparameterwerte. In einigen Fällen müssen Sie die Werte 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

Bei Anforderungen, die einfache Anführungszeichen verwenden, müssen 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-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 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-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.

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. 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 werden in der Regel maximal 20 Elemente für die erweiterte Beziehung zurückgegeben, und es gibt keine @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. , xmlund json), aber die Ergebnisse werden 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 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 die 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 die Sortierreihenfolge nicht angegeben ist, wird die standardmäßige 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 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 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 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 Version 1.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.

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 sich die Ergebnisse einer Abfrage über mehrere Seiten erstrecken, 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.
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 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 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 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 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. 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.