Nachrichten auflisten

  • Artikel

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

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 die Nachrichten abrufen, die eine Erwähnung des angemeldeten Benutzers enthalten. Unten sehen Sie ein Beispiel. Standardmäßig gibt der GET /me/messages Vorgang die Mentions-Eigenschaft nicht zurück. Verwenden Sie den $expand Abfrageparameter, um Details zu den einzelnen 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 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

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 Meldungen abzurufen, die den angemeldeten Benutzer Erwähnung.

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

Bei erfolgreicher Ausführung gibt die Methode einen Antwortcode und eine 200 OK Auflistung von Nachrichtenobjekten im Antworttext zurück.

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

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/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 nachrichten gefiltert, die den Benutzer Erwähnung. Außerdem wird 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

Das folgende Beispiel zeigt die 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 die Kopfzeile bevorzugen, um den Nachrichtentext abzurufen, und uniqueBody ist das Textformat.

Anforderung

Im dritten Beispiel wird gezeigt, wie sie eine Prefer: outlook.body-content-type="text" Kopfzeile verwenden, um die Body - und uniqueBody-Eigenschaften jeder Nachricht im Textformat abzurufen.

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

Antwort

Das folgende Beispiel zeigt die 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"
      }
    }
  ]
}