Nachrichten auflisten

Namespace: microsoft.graph

Mit dieser Methode können Sie die Nachrichten im Postfach des angemeldeten Benutzers abrufen (einschließlich der Nachrichten aus den Ordnern „Gelöschte Elemente“ und „Clutter“).

Je nach Seitengröße und Postfachdaten kann das Abrufen von Nachrichten aus einem Postfach mehrere Anforderungen umfassen. Die standardmäßige Seitengröße beträgt 10 Nachrichten. Verwenden Sie $top, um die Seitengröße anzupassen, mit einem Bereich von 1 bis 1 000.

Verwenden Sie $select, um die Reaktionszeit des Vorgangs zu verbessern und die genauen Eigenschaften anzugeben, die Sie benötigen. Siehe Beispiel 1 unten. Optimieren Sie die Werte für $select und $top, insbesondere wenn Sie eine größere Seitengröße verwenden müssen, da das Zurückgeben einer Seite mit Hunderten von Nachrichten mit jeweils vollständiger Antwortnutzlast eine Gateway-Zeitüberschreitung auslösen kann (HTTP 504).

Um die nächste Seite von Nachrichten abzurufen, wenden Sie einfach die in @odata.nextLink zurückgegebene gesamte URL auf die nächste get-messages-Anforderung an. Diese URL umfasst alle Abfrageparameter, die Sie möglicherweise in der anfänglichen Anforderung angegeben haben.

Versuchen Sie nicht, den $skip-Wert aus der @odata.nextLink-URL zu extrahieren, um Antworten zu bearbeiten. Diese API verwendet den $skip-Wert, um alle Elemente zu zählen, die sie im Postfach des Benutzers durchlaufen hat, um eine Seite von message-type-Elementen zurückzugeben. Daher kann es sein, dass auch in der ersten Antwort der $skip-Wert größer ist als die Seitengröße. Weitere Informationen finden Sie unter Paging der Microsoft Graph-Daten in Ihrer App.

Zurzeit gibt dieser Vorgang Nachrichtentext ausschließlich im HTML-Format zurück.

Es gibt zwei Szenarien, in denen eine App Nachrichten im E-Mail-Ordner eines anderen Benutzers abrufen kann:

• Wenn die App Anwendungsberechtigungen besitzt oder
• Wenn die App die entsprechenden delegierten Berechtigungen von einem Benutzer besitzt und ein anderer Benutzer einen E-Mail-Ordner für diesen Benutzer freigegeben hat oder diesem Benutzer delegierten Zugriff erteilt hat. Hier finden Sie weitere Informationen und ein Beispiel.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst	US Government L4	US Government L5 (DOD)	China, betrieben von 21Vianet
✅	✅	✅	✅

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp	Berechtigungen mit den geringsten Berechtigungen	Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto)	Mail.ReadBasic	Mail.ReadWrite, Mail.Read
Delegiert (persönliches Microsoft-Konto)	Mail.ReadBasic	Mail.ReadWrite, Mail.Read
App	Mail.ReadBasic.All	Mail.ReadWrite, Mail.Read

HTTP-Anforderung

So rufen Sie alle Nachrichten in einem Benutzerpostfach ab:

GET /me/messages
GET /users/{id | userPrincipalName}/messages

So rufen Sie Nachrichten in einem spezifischen Ordner in einem Benutzerpostfach ab:

GET /me/mailFolders/{id}/messages
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages

Optionale Abfrageparameter

Diese Methode unterstützt die OData-Abfrageparameter zur Anpassung der Antwort.

Verwenden von "filter" und "orderby" in derselben Abfrage

Wenn Sie $filter und $orderby in derselben Abfrage verwenden, um Nachrichten abzurufen, stellen Sie sicher, dass Sie Eigenschaften auf folgende Weise angeben:

1. Eigenschaften, die in $orderby verwendet werden, müssen auch in $filter enthalten sein.
2. Eigenschaften, die in $orderby verwendet werden, werden in der gleichen Reihenfolge wie in $filter angezeigt.
3. Eigenschaften, die in $orderby vorhanden sind, werden in $filter vor allen darin nicht vorhandenen Eigenschaften angezeigt.

Wird hiervon abgewichen, kann folgender Fehler auftreten:

• Fehlercode: InefficientFilter
• Fehlermeldung: The restriction or sort order is too complex for this operation.

Anforderungsheader

Name	Typ	Beschreibung
Authorization	string	Bearer {token}. Erforderlich.
Besser: outlook.body-content-type	string	Das Format, in der die body- und uniqueBody-Eigenschaften zurückgegeben werden sollen. Werte können „Text“ oder „html“ sein. Wenn die Kopfzeile nicht angegeben ist, werden die body- und uniqueBody-Eigenschaften im HTML-Format zurückgegeben. Optional.

Anforderungstext

Geben Sie keinen Anforderungstext für diese Methode an.

Antwort

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und eine Sammlung von Message-Objekten im Antworttext zurückgegeben.

Beispiele

Beispiel 1: Auflisten aller Nachrichten

Anforderung

In diesem Beispiel wird der Standard abgerufen, also die 10 wichtigsten Nachrichten im Postfach des angemeldeten Benutzers. Hierfür wird $select verwendet, um eine Teilmenge der Eigenschaften der einzelnen Nachrichten in der Antwort zurückzugeben.

HTTP

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

C#

// 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 []{ "sender","subject" };
});

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --select "sender,subject"

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Select: [] string {"sender","subject"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Java

// 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 []{"sender", "subject"};
});

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.select('sender,subject')
	.get();

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["sender","subject"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->messages()->get($requestConfiguration)->wait();

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

PowerShell

Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Property "sender,subject" 

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Python

from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		select = ["sender","subject"],
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Antwort

Das folgende Beispiel zeigt die Antwort. Um die nächste Seite von Nachrichten abzurufen, wenden Sie die in @odata.nextLink zurückgegebene URL auf eine nachfolgende GET-Anforderung an.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('bb8775a4-4d8c-42cf-a1d4-4d58c2bb668f')/messages(sender,subject)",
    "value": [
        {
            "@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAwR4Hg\"",
            "id": "AAMkAGUAAAwTW09AAA=",
            "subject": "You have late tasks!",
            "sender": {
                "emailAddress": {
                    "name": "Microsoft Planner",
                    "address": "noreply@Planner.Office365.com"
                }
            }
        }
    ]
}