Feedback Bearbeiten

Nachrichten auflisten

  • Artikel
  • 13 Minuten Lesedauer

Namespace: microsoft.graph

Wichtig

APIs unter der /beta Version in Microsoft Graph können geändert werden. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in Version 1.0 verfügbar ist, verwenden Sie die Versionsauswahl .

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.

Sie können nach den Nachrichten filtern und nur diejenigen abrufen, die eine Erwähnung des angemeldeten Benutzers enthalten. Unten sehen Sie ein Beispiel. Standardmäßig gibt der GET /me/messages Vorgang die Erwähnungseigenschaft nicht zurück. Verwenden Sie den $expand Abfrageparameter, um Details zu jeder Erwähnung in einer Nachricht zu finden.

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 hat und ein anderer Benutzer einen Mail-Ordner für diesen Benutzer freigegeben hat oder diesem Benutzer delegierten Zugriff gewährt hat. Siehe Details und ein Beispiel.

Hinweis Beachten Sie das bekannte Problem, dass dieser Vorgang Chatnachrichten von Microsoft Teams in ihre Antwort einschließt.

Berechtigungen

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.

Berechtigungstyp Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto) Mail.ReadBasic, Mail.Read, Mail.ReadWrite
Delegiert (persönliches Microsoft-Konto) Mail.ReadBasic, Mail.Read, Mail.ReadWrite
Anwendung Mail.ReadBasic.All, Mail.Read, Mail.ReadWrite

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

So rufen Sie alle Nachrichten im Postfach des Benutzers ab, die eine Erwähnung des Benutzers enthalten:

GET /me/messages?$filter=mentionsPreview/isMentioned eq true
GET /users/{id | userPrincipalName}/messages?$filter=mentionsPreview/isMentioned eq true

Optionale Abfrageparameter

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

Sie können den $filter Abfrageparameter für die MentionsPreview-Eigenschaft verwenden, um die Nachrichten abzurufen, die den angemeldeten Benutzer erwähnen.

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 für diese Methode keinen Anforderungstext an.

Antwort

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

Beispiele

Beispiel 1: Auflisten aller Nachrichten

Anforderung

Im ersten Beispiel werden die standardmäßigen 10 wichtigsten Nachrichten im Postfach des angemeldeten Benutzers abgerufen. Hierfür wird $select verwendet, um eine Teilmenge der Eigenschaften der einzelnen Nachrichten in der Antwort zurückzugeben.

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

Antwort

Nachfolgend sehen Sie ein Beispiel der 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/beta/$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"
        }
      }
    }
  ]
}

Beispiel 2: Verwenden von $filter zum Abrufen aller Nachrichten, die eine bestimmte Bedingung erfüllen

Anforderung

Im nächsten Beispiel werden alle Nachrichten im Postfach des angemeldeten Benutzers nach den Nachrichten gefiltert, die den Benutzer erwähnen. Es wird auch verwendet $select , um eine Teilmenge der Eigenschaften jeder Nachricht in der Antwort zurückzugeben.

Das folgende Beispiel enthält auch die URL-Codierung für die Leerzeichen in der Abfrageparameterzeichenfolge.

GET https://graph.microsoft.com/beta/me/messages?$filter=MentionsPreview/IsMentioned%20eq%20true&$select=Subject,Sender,ReceivedDateTime,MentionsPreview

Antwort

Nachfolgend sehen Sie ein Beispiel der Antwort.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#me/messages(subject,sender,receivedDateTime,mentionsPreview)",
  "value":[
    {
      "@odata.id":"https://graph.microsoft.com/beta/users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/messages('AQMkADJmMTUAAAgVZAAAA')",
      "@odata.etag":"W/\"CQAAABYAAAAPFhK2FclcRbABBJhCde8iAAAAAATI\"",
      "id":"AQMkADJmMTUAAAgVZAAAA",
      "receivedDateTime":"2016-07-21T07:40:21Z",
      "subject":"Re: Start planning soon",
      "sender":{
        "emailAddress":{
          "name":"Adele Vance",
          "address":"AdeleV@contoso.com"
        }
      },
      "mentionsPreview":{
        "isMentioned":true
      }
    }
  ]
}

Beispiel 3: Verwenden sie "Prefer Header", um den Nachrichtentext abzurufen, und "uniqueBody" ist ein Textformat.

Anforderung

Das dritte Beispiel zeigt, wie Sie mithilfe einer Prefer: outlook.body-content-type="text" Kopfzeile die Eigenschaften "body " und "uniqueBody" jeder Nachricht im Textformat abrufen.

GET https://graph.microsoft.com/beta/me/messages?$select=subject,body,bodyPreview,uniqueBody
Prefer: outlook.body-content-type="text"

Antwort

Nachfolgend sehen Sie ein Beispiel der Antwort.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#users('cd209b0b-3f83-4c35-82d2-d88a61820480')/messages(subject,body,bodyPreview,uniqueBody)",
  "value":[
    {
      "@odata.type":"#microsoft.graph.eventMessageRequest",
      "@odata.etag":"W/\"CwAAABYAAABmWdbhEgBXTophjCWt81m9AAAoZYj5\"",
      "id":"AAMkAGIAAAoZCfIAAA=",
      "subject":"Orientation ",
      "bodyPreview":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.",
      "body":{
        "contentType":"text",
        "content":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.\r\n"
      },
      "uniqueBody":{
        "contentType":"text",
        "content":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.\r\n"
      }
    }
  ]
}