Optionale Abfrageparameter in Microsoft Graph

Microsoft Graph stellt mehrere optionale Abfrageparameter bereit, die Sie zum Festlegen und Steuern der in einer Antwort zurückgegebenen Datenmenge verwenden können. Microsoft Graph unterstützt die folgenden Abfrageoptionen.

Name Wert Beschreibung
$search string Ein Eigenschaft-/Wertpaar, das durch einen Doppelpunkt getrennt ist.
$select string Durch Trennzeichen getrennte Liste der Eigenschaften, die in der Antwort aufgenommen werden.
$expand string Durch Trennzeichen getrennte Liste der Beziehungen, die in der Antwort erweitert und aufgenommen werden.
$orderby string Durch Trennzeichen getrennte Liste von Eigenschaften, die zum Sortieren der Elemente in der Antwortsammlung verwendet werden.
$filter string Filtert die Antwort basierend auf einer Reihe von Kriterien.
$top int Die Anzahl der Elemente, die in einem Resultset zurückgegeben werden.
$skip int Die Anzahl der Elemente, die in einem Resultset übersprungen werden.
$skipToken string Pagingtoken, das zum Abrufen des nächsten Resultsets verwendet wird.
$count Keine Eine Auflistung, und die Anzahl der Elemente in der Auflistung.

Diese Parameter sind kompatibel mit der Abfragesprache OData V4.

Hinweis: Auf dem Microsoft Graph Beta-Endpunkt, kann das Präfix $ entfallen, um die Erfahrung zu vereinfachen. Anstelle von $Erweitern, können Sie z. B. Erweitern verwenden. Weitere Informationen und Beispiele finden Sie unter Abfrageparameter ohne $ Präfixe in Microsoft Graph unterstützen.

Codieren von Abfrageparametern

  • Wenn Sie Abfrageparameter in Microsoft Graph Explorer ausprobieren, können Sie einfach die unten aufgeführten Beispiele kopieren und einfügen, ohne der Abfragezeichenfolge eine URL-Codierung hinzufügen zu müssen. Das folgende Beispiel funktioniert einwandfrei im Graph Explorer, ohne die Leerzeichen und Anführungszeichen zu codieren:
GET https://graph.microsoft.com/v1.0/me/messages?$filter=from/emailAddress/address eq 'jon@contoso.com'
  • Stellen Sie beim Festlegen von Abfrageparametern in Ihrer App allgemein sicher, dass Sie solche Zeichen angemessen codieren, für die im URI eine besondere Bedeutung reserviert ist. Codieren Sie zum Beispiel die Leerzeichen und Anführungszeichen im letzten Beispiel wie dargestellt:
GET https://graph.microsoft.com/v1.0/me/messages?$filter=from/emailAddress/address%20eq%20%27jon@contoso.com%27

Um die Ergebnisse einer Anforderung zu beschränken, die einem Suchkriterium entsprechen, verwenden Sie den $search-Abfrageparameter.

Hinweis: Sie können derzeit $search für Sammlungen von message und person verwenden, jedoch nicht von contact oder event. Eine $search-Anforderung gibt bis zu 250 Ergebnisse zurück. $filter oder $orderby kann in einer $search-Abfrage nicht verwendet werden.

Suchkriterien werden mithilfe von Advanced Query Syntax (AQS) ausgedrückt.

Anwenden von $search auf Nachrichten

Suchergebnisse werden nach Datum und Uhrzeit sortiert, an dem bzw. zu der die Nachricht gesendet wurde.

Sie können die folgenden Eigenschaften in einem message-Objekt in einem $search-Kriterium angeben:attachments, bccRecipients, body, category, ccRecipients, content, from, hasAttachments, participants, receivedDateTime, sender, subject, toRecipients

Wenn Sie eine Suche nach Nachrichten durchführen und nur einen Wert angeben, wird die Suche anhand der Standardsucheigenschaftenfrom, subject und body ausgeführt.

Im folgenden Beispiel werden alle Nachrichten im Posteingang des angemeldeten Benutzers zurückgegeben, die das Wort „Pizza“ in einer der drei Standardsucheigenschaften enthalten:

GET https://graph.microsoft.com/v1.0/me/messages?$search="pizza"

Im nächsten Beispiel werden alle Nachrichten im Posteingang des Benutzers gesucht, die von einer bestimmten E-Mail-Adresse gesendet wurden:

GET https://graph.microsoft.com/v1.0/me/messages?$search="from:help@contoso.com"

$select

Um für die Rückgabe eine andere Gruppe von Eigenschaften anzugeben als die Standardgruppe von Graph, verwenden Sie die Abfrageoption $select. Die $select-Option ermöglicht die Auswahl einer Teilmenge oder Obermenge der zurückgegebenen Standardgruppe. Wenn Sie z. B. Ihre Nachrichten abrufen, möchten Sie ggf. festlegen, dass nur die Eigenschaften Von und Betreff der Nachrichten zurückgegeben werden.

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

$expand

In Microsoft Graph-API-Anforderungen wird die Navigation zu einem Objekt oder einer Auflistung des Elements, auf das verwiesen wird, nicht automatisch erweitert. Dies ist beabsichtigt, da der Netzwerkdatenverkehr und die Zeit zum Generieren einer Antwort vom Dienst auf diese Weise reduziert werden. Möglicherweise möchten Sie jedoch in einigen Fällen diese Ergebnisse in eine Antwort einbeziehen.

Sie können den $expand-Abfragezeichenfolgen-Parameter verwenden, um die API zum Erweitern eines untergeordneten Objekts oder einer Auflistung und zum Einbeziehen dieser Ergebnisse anzuweisen.

Verwenden Sie beispielsweise zum Abrufen von Stammlaufwerkinformationen und der untergeordneten Elemente auf oberster Ebene in einem Laufwerk den $expand-Parameter. In diesem Beispiel wird auch eine $select-Anweisung verwendet, um nur die Eigenschaften_ID_ und Name der untergeordneten Elemente zurückzugeben.

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

Hinweis: Die maximale Anzahl der erweiterten Objekte für eine Anforderung beträgt 20.

Wenn Sie außerdem eine Abfrage für die Benutzer-Ressource durchführen, können Sie $expand zum Abrufen der Eigenschaften von jeweils nur einem untergeordneten Objekt oder einer Auflistung verwenden.

Das folgende Beispiel ruft Benutzer-Objekte ab, jeweils mit bis zu 20 erweiterten directReport-Objekten in der directReports-Auflistung:

GET https://graph.microsoft.com/v1.0/users?$expand=directReports

Einige andere Ressourcen haben möglicherweise ebenfalls einen Höchstwert, führen Sie daher immer eine Überprüfung auf mögliche Fehler durch.

$orderby

Verwenden Sie zum Festlegen der Sortierreihenfolge der aus der Microsoft Graph-API zurückgegebenen Elemente die $orderby-Abfrageoption.

Wenn die zurückgegebenen Benutzer in der Organisation nach dem Anzeigenamen sortiert werden sollen, lautet die Syntax hierfür wie folgt:

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

Sie können auch nach komplexen Typentitäten sortieren. Im folgenden Beispiel werden Nachrichten abgerufen und nach dem Adresse-Feld der from-Eigenschaft sortiert, 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 an den Namen des Felds getrennt durch ein Leerzeichen an, z. B. ?$orderby=name%20desc.

Hinweis: Bei Abfragen zur user-Ressource kann $orderby nicht zusammen mit Filterausdrücken verwendet werden.

$filter

Wenn Sie die zurückgegebenen Daten anhand bestimmter Kriterien filtern möchten, verwenden Sie die $filter-Abfrageoption. Wenn die zurückgegebenen Benutzer in der Organisation anhand des Anzeigenamens gefiltert werden sollen, der mit „Garth“ beginnt, lautet die Syntax hierfür wie folgt:

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

Sie können auch nach komplexen Typentitäten filtern. Das folgende Beispiel gibt Nachrichten zurück, bei denen das Feld address der from-Eigenschaft gleich „jon@contoso.com“ ist. Die from-Eigenschaft hat den komplexen Typ emailAddress.

GET https://graph.microsoft.com/v1.0/me/messages?$filter=from/emailAddress/address eq 'jon@contoso.com'

$top

Verwenden Sie zum Festlegen der maximalen Anzahl der in einem Resultset zurückzugebenden Elemente die $top-Abfrageoption. Die $top-Abfrageoption ermittelt eine Teilmenge in der Sammlung. Diese Teilmenge setzt sich aus den festgelegten ersten N Elementen zusammen, wobei N eine positive ganze Zahl ist, die durch diese Abfrageoption angegeben ist. Wenn beispielsweise die ersten fünf Nachrichten im Postfach des Benutzers zurückgegeben werden sollen, lautet die Syntax wie folgt:

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

$skip

Verwenden Sie zum Festlegen der Anzahl der Elemente, die vor dem Abrufen von Elementen in einer Sammlung übersprungen werden sollen, die $skip-Abfrageoption. Wenn die zurückgegebenen Ereignisse nach Erstellungsdatum sortiert werden, wobei mit dem 21. Ereignis begonnen wird, lautet die Syntax wie folgt.

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

$skipToken

Verwenden Sie zur Anforderung der zweiten und nachfolgender Seiten mit Graph-Daten die Abfrageoption $skipToken. Die $skipToken-Abfrageoption ist eine Option, die in URLs bereitgestellt wird, die von Graph übergeben werden, wenn Graph, in der Regel aufgrund von serverseitigem Paging, einen Teil einer Teilmenge der Ergebnisse zurückgibt. Sie nennt den Punkt in einer Sammlung, an dem der Server das Senden der Ergebnisse beendet hat, und wird zu Graph zurückgegeben, um anzugeben, von wo aus das Senden der Ergebnisse wieder aufgenommen werden sollte. Der Wert einer $skipToken-Abfrageoption könnte z. B. das zehnte Element in einer Sammlung oder das 20. Element in einer Sammlung mit 50 Elementen oder eine andere Position in der Sammlung angeben.

In einigen Fällen wird ein @odata.nextLink-Wert angezeigt. Manchmal ist ein $skipToken-Wert enthalten. Der $skipToken-Wert stellt eine Markierung für den Dienst dar, die angibt, an welcher Stelle das nächste Resultset beginnen soll. Nachfolgend ein Beispiel für einen @odata.nextLink-Wert aus einer Antwort, in der Benutzer sortiert nach displayName angefordert werden:

"@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$orderby=displayName&$skiptoken=X%2783630372100000000000000000000%27"

Um die nächste Seite der Benutzer in Ihrer Organisation zurückzugeben, lautet die Syntax wie folgt.

GET  https://graph.microsoft.com/v1.0/users?$orderby=displayName&$skiptoken=X%2783630372100000000000000000000%27

$count

Verwenden Sie $count als Abfrageparameter, um die Gesamtzahl der Elemente in einer Sammlung zusammen mit der Seite der Datenwerte anzugeben, die von Graph zurückgegeben werden (siehe folgendes Beispiel):

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

Zurückgegeben werden sowohl die Kontakte-Sammlung als auch die Anzahl der Elemente in der Kontakte-Sammlung in der Eigenschaft @odata.count.

Hinweis: Dies wird für directoryObject-Sammlungen nicht unterstützt.