Nachrichten auflistenList messages
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.
BerechtigungstypPermission type | Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)Permissions (from least to most privileged) |
---|---|
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) | Mail.ReadBasic, Mail.Read, Mail.ReadWriteMail.ReadBasic, Mail.Read, Mail.ReadWrite |
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) | Mail.ReadBasic, Mail.Read, Mail.ReadWriteMail.ReadBasic, Mail.Read, Mail.ReadWrite |
AnwendungApplication | Mail.ReadBasic.All, Mail.Read, Mail.ReadWriteMail.ReadBasic.All, Mail.Read, Mail.ReadWrite |
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:
- Eigenschaften, die in
$orderby
verwendet werden, müssen auch in$filter
enthalten sein.Properties that appear in$orderby
must also appear in$filter
. - 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
. - 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:
InefficientFilter
Error 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
NameName | TypType | BeschreibungDescription |
---|---|---|
AuthorizationAuthorization | stringstring | Bearer {token}. Erforderlich.Bearer {token}. Required. |
Besser: outlook.body-content-typePrefer: outlook.body-content-type | stringstring | Das Format, in der die body- und uniqueBody-Eigenschaften zurückgegeben werden sollen.The format of the body and uniqueBody properties to be returned in. Werte können „Text“ oder „html“ sein.Values can be "text" or "html". Wenn die Kopfzeile nicht angegeben ist, werden die body- und uniqueBody-Eigenschaften im HTML-Format zurückgegeben.If the header is not specified, the body and uniqueBody properties are returned in HTML format. Optional.Optional. |
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
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"
}
}
}
]
}