Nachrichten auflistenList messages

• 01.04.2021
• 3 Minuten Lesedauer
• • a
  • o

Namespace: microsoft.graphNamespace: 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“).Get the messages in the signed-in user's mailbox (including the Deleted Items and Clutter folders).

Je nach Seitengröße und Postfachdaten kann das Abrufen von Nachrichten aus einem Postfach mehrere Anforderungen umfassen.Depending on the page size and mailbox data, getting messages from a mailbox can incur multiple requests. Die standardmäßige Seitengröße beträgt 10 Nachrichten.The default page size is 10 messages. Verwenden Sie $top, um die Seitengröße anzupassen, mit einem Bereich von 1 bis 1 000.Use $top to customize the page size, within the range of 1 and 1000.

Verwenden Sie $select, um die Reaktionszeit des Vorgangs zu verbessern und die genauen Eigenschaften anzugeben, die Sie benötigen. Siehe Beispiel 1 unten.To improve the operation response time, use $select to specify the exact properties you need; see example 1 below. 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).Fine-tune the values for $select and $top, especially when you must use a larger page size, as returning a page with hundreds of messages each with a full response payload may trigger the gateway timeout (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.To get the next page of messages, simply apply the entire URL returned in @odata.nextLink to the next get-messages request. Diese URL umfasst alle Abfrageparameter, die Sie möglicherweise in der anfänglichen Anforderung angegeben haben.This URL includes any query parameters you may have specified in the initial request.

Versuchen Sie nicht, den $skip-Wert aus der @odata.nextLink-URL zu extrahieren, um Antworten zu bearbeiten.Do not try to extract the $skip value from the @odata.nextLink URL to manipulate responses. 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.This API uses the $skip value to keep count of all the items it has gone through in the user's mailbox to return a page of message-type items. Daher kann es sein, dass auch in der ersten Antwort der $skip-Wert größer ist als die Seitengröße.It's therefore possible that even in the initial response, the $skip value is larger than the page size. Weitere Informationen finden Sie unter Paging der Microsoft Graph-Daten in Ihrer App.For more information, see Paging Microsoft Graph data in your app.

Zurzeit gibt dieser Vorgang Nachrichtentext ausschließlich im HTML-Format zurück.Currently, this operation returns message bodies in only HTML format.

Es gibt zwei Szenarien, in denen eine App Nachrichten im E-Mail-Ordner eines anderen Benutzers abrufen kann:There are two scenarios where an app can get messages in another user's mail folder:

• Wenn die App Anwendungsberechtigungen besitzt oderIf the app has application permissions, or,
• 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.If the app has the appropriate delegated permissions from one user, and another user has shared a mail folder with that user, or, has given delegated access to that user. Hier finden Sie weitere Informationen und ein Beispiel.See details and an example.

Hinweis Beachten Sie das bekannte Problem, dass dieser Vorgang Chatnachrichten von Microsoft Teams in ihre Antwort einschließt.Note Be aware of the known issue that this operation includes Microsoft Teams chat messages in its response.

BerechtigungenPermissions

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema Berechtigungen.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

HTTP-AnforderungHTTP request

So rufen Sie alle Nachrichten in einem Benutzerpostfach ab:To get all the messages in a user's mailbox:

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

So rufen Sie Nachrichten in einem spezifischen Ordner in einem Benutzerpostfach ab:To get messages in a specific folder in the user's mailbox:

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

Optionale AbfrageparameterOptional query parameters

Diese Methode unterstützt die OData-Abfrageparameter zur Anpassung der Antwort.This method supports the OData Query Parameters to help customize the response.

Verwenden von "filter" und "orderby" in derselben AbfrageUsing filter and orderby in the same query

Wenn Sie $filter und $orderby in derselben Abfrage verwenden, um Nachrichten abzurufen, stellen Sie sicher, dass Sie Eigenschaften auf folgende Weise angeben:When using $filter and $orderby in the same query to get messages, make sure to specify properties in the following ways:

1. Eigenschaften, die in $orderby verwendet werden, müssen auch in $filter enthalten sein.Properties that appear in $orderby must also appear in $filter.
2. Eigenschaften, die in $orderby verwendet werden, werden in der gleichen Reihenfolge wie in $filter angezeigt.Properties that appear in $orderby are in the same order as in $filter.
3. Eigenschaften, die in $orderby vorhanden sind, werden in $filter vor allen darin nicht vorhandenen Eigenschaften angezeigt.Properties that are present in $orderby appear in $filter before any properties that aren't.

Wird hiervon abgewichen, kann folgender Fehler auftreten:Failing to do this results in the following error:

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

AnforderungsheaderRequest headers

AnforderungstextRequest body

Geben Sie für diese Methode keinen Anforderungstext an.Do not supply a request body for this method.

AntwortResponse

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und eine Sammlung von Message-Objekten im Antworttext zurückgegeben.If successful, this method returns a 200 OK response code and collection of Message objects in the response body.

BeispieleExamples

Beispiel 1: Auflisten aller NachrichtenExample 1: List all messages

AnforderungRequest

In diesem Beispiel wird der Standard abgerufen, also die 10 wichtigsten Nachrichten im Postfach des angemeldeten Benutzers.This example gets the default, top 10 messages in the signed-in user's mailbox. Hierfür wird $select verwendet, um eine Teilmenge der Eigenschaften der einzelnen Nachrichten in der Antwort zurückzugeben.It uses $select to return a subset of the properties of each message in the response.

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

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var messages = await graphClient.Me.Messages
    .Request()
    .Select("sender,subject")
    .GetAsync();

const options = {
    authProvider,
};

const client = Client.init(options);

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

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/messages?$select=sender,subject"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        NSError *jsonError = nil;
        MSCollection *collection = [[MSCollection alloc] initWithData:data error:&jsonError];
        MSGraphMessage *message = [[MSGraphMessage alloc] initWithDictionary:[[collection value] objectAtIndex: 0] error:&nserror];

}];

[meDataTask execute];

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

MessageCollectionPage messages = graphClient.me().messages()
    .buildRequest()
    .select("sender,subject")
    .get();

AntwortResponse

Nachfolgend sehen Sie ein Beispiel der Antwort.Here is an example of the response. Um die nächste Seite von Nachrichten abzurufen, wenden Sie die in @odata.nextLink zurückgegebene URL auf eine nachfolgende GET-Anforderung an.To get the next page of messages, apply the URL returned in @odata.nextLink to a subsequent GET request.

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"
                }
            }
        }
    ]
}