Feedback Bearbeiten

Verwenden von Abfrageparametern zum Anpassen von Antworten

  • Artikel
  • 13 Minuten Lesedauer

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.

Hinweis

RFC 3986 erfordert, dass reservierte Zeichen in URLs als Prozentwert codiert sind. In diesem Dokument werden zur besseren Lesbarkeit jedoch möglicherweise keine als Prozentwert codierten Zeichen angezeigt. Die reservierten Zeichen, z. B. das Komma (,) in einem startsWith-Ausdruck, sollten jedoch in Ihren Anforderungen als Prozentwert codiert werden.

OData-System-Abfrageoptionen

Ein Microsoft Graph-API-Vorgang kann eine oder mehrere der folgenden OData-System-Abfrageoptionen unterstützen. Diese Abfrageparameter sind mit der OData V4-Abfragesprache kompatibel.

Hinweis

OData 4.0 unterstützt Systemabfrageoptionen nur in GET-Vorgängen.

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 Dient zum Indizieren in einem Resultset. Wird auch von einigen APIs zum Implementieren von Paging verwendet und kann zusammen mit $top zum manuellen Auslagern von Ergebnissen verwendet werden. /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 stattdessen $skip.) /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 als Prozentwert codiert werden. 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.

Eine nicht codierte URL sieht folgendermaßen aus:

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

Eine korrekt codierte URL sieht folgendermaßen aus:

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

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 Abfrage-String-Parameter mit der Syntax,$count=trueum eine Zählung der Gesamtzahl der Elemente in einer Sammlung neben der Seite der von Microsoft Graph zurückgegebenen Datenwerte einzuschließen. Zum 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. Sehen Sie sich die folgenden Beispiele unten an.

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 Azure AD-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 die gleiche Abfrage wie im vorherigen Beispiel ausgeführt, hier wird jedoch eine $select-Anweisung verwendet, um die für die erweiterten untergeordneten Elemente zurückgegebenen Eigenschaften auf die id- und name-Eigenschaften einzuschrä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 Beziehungen directReports, manager und memberOf für einen Benutzer erweitern, aber Sie können nicht seine Beziehungen events, messages oder photo erweitern. Nicht alle Ressourcen oder Beziehungen unterstützen die Verwendung von $select in erweiterten Elementen.

  • Bei Azure AD-Ressourcen, die von directoryObject abgeleitet werden, z. B. user und group, gibt $expand maximal 20 Elemente für die erweiterte Beziehung zurück und verfügt über kein @odata.nextLink-Element. Weitere Informationen finden Sie unter Bekannte Probleme.

  • $expand wird derzeit nicht mit erweiterten Abfragenunterstützt.

filter-Parameter

Verwenden Sie den $filter-Abfrageparameter, um nur eine Teilmenge einer Sammlung abzurufen. Der Abfrageparameter $filter kann auch verwendet werden, um Beziehungen wie members, memberOf, transitiveMembers und transitiveMemberOf abzurufen. Rufen Sie beispielsweise alle Sicherheitsgruppen ab, in denen ich Mitglied bin.

Im folgenden Beispiel werden Benutzer gefunden, deren Anzeigename mit dem Buchstaben „J“ beginnt:

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

Die Unterstützung für $filter-Operatoren variiert je nach Microsoft Graph-API. Im Allgemeinen werden die folgenden logischen Operatoren unterstützt:

Operatortyp Operator
Gleichheitsoperatoren
  • Gleich (eq)
  • Ungleich (ne)
  • Logische Negation (not)
  • In (in)
Relationaler Operator
  • Kleiner als (lt)
  • Größer als (gt)
  • Kleiner oder gleich (le)
  • Größer oder gleich (ge)
Lambda-Operatoren
  • Beliebig (any)
  • Alle (all)
Bedingte Operatoren
  • Und (and)
  • Oder (or)
Funktionen
  • Beginnt mit (startsWith)
  • Endet mit (endsWith)
  • Enthält (contains)

Hinweis

Die Unterstützung für diese Operatoren variiert je nach Entität, und einige Eigenschaften unterstützen $filter nur in erweiterten Abfragen. Ausführliche Informationen finden Sie in der Dokumentation zu einer bestimmten Entität.

Filtern mit Lambdaoperatoren

OData definiert die Operatoren any und all, um Übereinstimmungen für mehrwertige Eigenschaften auszuwerten, d. h. entweder eine Sammlung von primitiven Werten wie String-Typen oder eine Sammlung von Entitäten.

any-Operator

Der Operator any wendet iterativ einen booleschen Ausdruck auf jedes Element einer Sammlung an und gibt true zurück, wenn der Ausdruck für ein beliebiges Element der Sammlung true ist, andernfalls wird false zurückgegeben. So sieht die Syntax des any-Operators aus:

$filter=param/any(var:var/subparam eq 'value-to-match')

Dabei gilt:

  • param ist die Eigenschaft, die eine Sammlung von Werten oder Entitäten enthält.
  • var:var ist eine Bereichsvariable, die das aktuelle Element der Sammlung während der Iteration enthält. Diese Variable kann im Prinzip einen beliebigen Namen erhalten, z. B. adele:adele oder x:x.
  • subparam ist erforderlich, wenn die Abfrage auf eine Sammlung von Entitäten angewendet wird. Dieser Parameter stellt die Eigenschaft des komplexen Typs dar, dessen Wert wir abgleichen.
  • value-to-match stellt das Element der Sammlung dar, mit dem der Abgleich erfolgt.

Beispielsweise enthält die Eigenschaft imAddresses der Benutzerressource eine Auflistung des primitiven „String“-Typs. Die folgende Abfrage ruft nur Benutzer mit einem „imAddress“-Wert von admin@contoso.com ab.

GET https://graph.microsoft.com/v1.0/users?$filter=imAddresses/any(s:s eq 'admin@contoso.com')

Die assignedLicenses-Eigenschaft der Benutzerressource enthält eine Auflistung von assignedLicense-Objekten, einen komplexen Typ mit zwei Eigenschaften, skuId und disabledPlans. Die folgende Abfrage ruft nur Benutzer mit einer zugewiesenen Lizenz ab, die durch die skuId 184efa21-98c3-4e5d-95ab-d07053a96e67 identifiziert wird.

GET https://graph.microsoft.com/v1.0/users?$filter=assignedLicenses/any(s:s/skuId eq 184efa21-98c3-4e5d-95ab-d07053a96e67)

Um das Ergebnis des Ausdrucks innerhalb der any-Klausel zu negieren, verwenden Sie den Operator not, nicht den Operator ne. Die folgende Abfrage ruft zum Beispiel nur Benutzer ab, denen nicht die imAddress admin@contoso.com zugewiesen ist.

Hinweis

Für Verzeichnisobjekte wie Benutzer werden die Operatoren not und ne nur in erweiterten Abfragen unterstützt.

GET https://graph.microsoft.com/v1.0/users?$filter=NOT(imAddresses/any(s:s eq 'admin@contoso.com'))&$count=true
ConsistencyLevel: eventual

all-Operator

Der Operator all wendet einen booleschen Ausdruck auf jedes Element einer Sammlung an und gibt true zurück, wenn der Ausdruck für alle Elemente der Sammlung true ist, andernfalls wird false zurückgegeben. Sie wird von keiner Eigenschaft unterstützt.

Beispiele für die Verwendung des Filterabfrageoperators

Die folgende Tabelle enthält einige Beispiele, welche die $filter-Abfrageparameter verwenden. Weitere Informationen zur $filter-Syntax finden Sie im OData-Protokoll.

Hinweis

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

Beschreibung Beispiel
In mehreren Eigenschaften alle Benutzer mit dem Namen „Mary“ abrufen. GET ../users?$filter=startswith(displayName,'mary') or startswith(givenName,'mary') or startswith(surname,'mary') or startswith(mail,'mary') or startswith(userPrincipalName,'mary')
Alle Benutzer mit der E-Mail-Domäne gleich „hotmail.com“ abrufen. GET ../users?$count=true&$filter=endsWith(mail,'@hotmail.com'). Dies ist eine erweiterte Abfrage.
Alle Benutzer ohne zugewiesene Lizenzen anzeigen GET ../users?$filter=assignedLicenses/$count eq 0&$count=true. Dies ist eine erweiterte Abfrage.
Alle Ereignisse des angemeldeten Benutzers abrufen, die nach dem 01.07.2017 beginnen.
GET ../me/events?$filter=start/dateTime ge '2017-07-01T08:00'.
HINWEIS: dateTime ist eine Eigenschaft vom Typ „String“.
Alle E-Mails von einer bestimmten Adresse abrufen, die der angemeldete Benutzer erhalten hat. GET ../me/messages?$filter=from/emailAddress/address eq 'someuser@example.com'
Alle E-Mails abrufen, die der angemeldete Benutzer im April 2017 erhalten hat. GET ../me/mailFolders/inbox/messages?$filter=ReceivedDateTime ge 2017-04-01 and receivedDateTime lt 2017-05-01
Alle ungelesenen E-Mails im Postfach des angemeldeten Benutzers abrufen. GET ../me/mailFolders/inbox/messages?$filter=isRead eq false
Alle Benutzer in den Abteilungen „Einzelhandel“ und „Vertrieb“ abrufen.
GET ../users?$filter=department in ('Retail', 'Sales')
Benutzer mit einem bestimmten Serviceplan auflisten, der sich in einem angehaltenen Zustand befindet. GET ../users?$filter=assignedPlans/any(a:a/servicePlanId eq 2e2ddb96-6af9-4b1d-a3f0-d6ecfd22edb2 and a/capabilityStatus eq 'Suspended')&$count=true. Dies ist eine erweiterte Abfrage.
Alle Microsoft 365-Gruppen in einer Organisation auflisten. GET ../groups?$filter=NOT groupTypes/any(c:c eq 'Unified')&$count=true. Dies ist eine erweiterte Abfrage.
Alle Benutzer auflisten, deren Unternehmensname nicht undefiniert (d. h. kein null Wert) oder Microsoft ist. GET ../users?$filter=companyName ne null and NOT(companyName eq 'Microsoft')&$count=true. Dies ist eine erweiterte Abfrage.
Alle Benutzer auflisten, deren Unternehmensname entweder undefiniert oder Microsoft ist. GET ../users?$filter=companyName in (null, 'Microsoft')&$count=true. Dies ist eine erweiterte Abfrage.
Verwenden Sie die CAST-Funktion von OData, um transitive Mitgliedschaften in Gruppen mit einem Anzeigenamen zu erhalten, der mit „A“ beginnt, einschließlich der Anzahl der zurückgegebenen Objekte. GET ../me/transitiveMemberOf/microsoft.graph.group?$count=true&$filter=startswith(displayName, 'a'). Dies ist eine erweiterte Abfrage.

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. In der folgenden Anforderung 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 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 für Azure AD-Verzeichnisobjekte.

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 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.0 geben einige Azure AD-Ressourcen, die von directoryObject abgeleitet werden, z.B. Benutzer und Gruppe eine begrenzte, standardmäßige Untermenge von Eigenschaften für Lesevorgänge zurück. Für diese Ressourcen müssen Sie $select verwenden, um Eigenschaften außerhalb des Standardsatzes zurückzugeben.

skip-Parameter

Verwenden Sie den $skip-Abfrageparameter zum Festlegen der Anzahl der Elemente, die am Anfang einer Sammlung übersprungen werden sollen. Die folgende Anforderung gibt beispielsweise Ereignisse für den Benutzer sortiert nach Erstellungsdatum zurück, beginnend mit dem 21. Ereignis in der Sammlung:

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

Hinweis

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.

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.

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 Seitengröße des Resultsets anzugeben.

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. $expand kann zum Beispiel nicht in der user/photo-Beziehung verwendet werden.

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.

Weitere Artikel