Verwenden von Abfrageparametern zum Anpassen von Antworten
Artikel
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.
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.
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.
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.
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.
GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "startswith(givenName, 'J')";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "startswith(givenName, 'J')";
});
GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "startswith(givenName, 'J')";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "startswith(givenName, 'J')";
});
GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "startswith(givenName, 'J')";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "startswith(givenName, 'J')";
});
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?'
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "subject eq 'let''s meet for lunch?'";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "subject eq 'let''s meet for lunch?'";
});
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "subject eq 'let''s meet for lunch?'"
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:
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.
Kann auch als URL-Segment verwendet werden, um die ganzzahlige Summe der Sammlung abzurufen. Beispiel: users/$count.
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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Contacts.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Count = true;
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ContactCollectionResponse result = graphClient.me().contacts().get(requestConfiguration -> {
requestConfiguration.queryParameters.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:
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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Root.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Expand = new string []{ "children" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
requestConfiguration.queryParameters.expand = new String []{"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)
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Root.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Expand = new string []{ "children($select=id,name)" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
requestConfiguration.queryParameters.expand = new String []{"children($select=id,name)"};
});
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.
GET https://graph.microsoft.com/v1.0/users?$format=json
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Format = "json";
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.format = "json";
});
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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/address" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.MailFolders["{mailFolder-id}"].Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/name desc","subject" };
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users mail-folders messages list --user-id {user-id} --mail-folder-id {mailFolder-id} --orderby "from/emailAddress/name desc,subject"
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().mailFolders().byMailFolderId("{mailFolder-id}").messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"from/emailAddress/name desc", "subject"};
});
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMailFolderMessage -UserId $userId -MailFolderId $mailFolderId -Sort "from/emailAddress/name desc,subject"
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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "Subject eq 'welcome' and importance eq 'normal'";
requestConfiguration.QueryParameters.Orderby = new string []{ "subject","importance","receivedDateTime desc" };
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --filter "Subject eq 'welcome' and importance eq 'normal'" --orderby "subject,importance,receivedDateTime desc"
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "Subject eq 'welcome' and importance eq 'normal'";
requestConfiguration.queryParameters.orderby = new String []{"subject", "importance", "receivedDateTime desc"};
});
Import-Module Microsoft.Graph.Mail
# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "Subject eq 'welcome' and importance eq 'normal'" -Sort "subject,importance,receivedDateTime desc"
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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "from","subject" };
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"from", "subject"};
});
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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Events.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Orderby = new string []{ "createdDateTime" };
requestConfiguration.QueryParameters.Skip = 20;
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
EventCollectionResponse result = graphClient.me().events().get(requestConfiguration -> {
requestConfiguration.queryParameters.orderby = new String []{"createdDateTime"};
requestConfiguration.queryParameters.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
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Top = 5;
});
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.top = 5;
});
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.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.