Список сообщений

  • Статья

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Получение сообщений в почтовом ящике пользователя, выполнившего вход (в том числе сообщений в папках "Удаленные" и "Несрочные").

В зависимости от размера страницы и данных почтового ящика получение сообщений из почтового ящика может повлечь множество запросов. По умолчанию страница содержит 10 сообщений. Используйте параметр $top, чтобы настроить размер страницы в диапазоне от 1 до 1000.

Чтобы сократить время отклика, используйте параметр $select для указания точных свойств, которые вам нужны. См. пример 1 ниже. Настройте значения для $select и $top, особенно при необходимости использовании большего размера страницы, так как возврат страницы с сотнями сообщений, каждое из которых содержит полные полезные данные отклика, может привести к истечению времени ожидания шлюза (HTTP 504).

Для получения следующей странице с сообщениями, просто примените весь URL-адрес, возвращаемый в @odata.nextLink, для другого запроса на получение сообщений. Этот URL-адрес включает любые параметры запроса, которые указаны в первоначальном запросе.

Не извлекайте значение $skip из URL-адреса @odata.nextLink для операций с ответами. Данный API использует значение $skip для учета всех элементов, просмотренных в почтовом ящике пользователя, и возврата элементов типа сообщение на странице. Таким образом, существует возможность, что даже в первоначальном ответе, значение $skip будет больше, чем размер страницы. Дополнительные сведения см. в статье Разбивка данных Microsoft Graph по страницам в приложении

Вы можете отфильтровать сообщения и получить только те, которые содержат упоминание вошедшего пользователя. См. пример ниже. По умолчанию GET /me/messages операция не возвращает свойство упоминания . $expand Используйте параметр запроса для поиска сведений о каждом упоминание в сообщении.

Существует два сценария, когда приложение может получить сообщения из папки почты другого пользователя:

  • У приложения есть разрешения для приложений; или
  • У приложения есть соответствующие делегированные разрешения от одного пользователя, а другой пользователь поделился с ним папкой почты или предоставил ему делегированный доступ. См. подробные сведения и пример.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet
✅ ✅ ✅ ✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) Mail.ReadBasic Mail.ReadWrite, Mail.Read
Делегированные (личная учетная запись Майкрософт) Mail.ReadBasic Mail.ReadWrite, Mail.Read
Приложение Mail.ReadBasic.All Mail.ReadWrite, Mail.Read

HTTP-запрос

Для получения всех сообщений в почтовом ящике пользователя:

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

Для получения сообщений из определенной папки в почтовом ящике пользователя:

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

Чтобы получить все сообщения в почтовом ящике пользователя, которые включают упоминание пользователя, выполните следующие действия:

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

Необязательные параметры запросов

Этот метод поддерживает параметры запросов OData для настройки ответа.

Параметр запроса в свойстве упоминанияPreview можно использовать $filter для получения сообщений, которые упоминание вошедшего пользователя.

Использование операторов filter и orderby в одном запросе

При использовании операторов $filter и $orderby в одном запросе на получение сообщений необходимо указать свойства, соблюдая указанные ниже условия.

  1. Свойства, используемые в операторе $orderby, также должны использоваться в операторе $filter.
  2. Свойства, используемые в операторе $orderby, представлены в том же порядке, что и для оператора $filter.
  3. Свойства, присутствующие в операторе $orderby, представлены в операторе $filter раньше всех остальных свойств.

В противном случае возникнет следующая ошибка:

  • Код ошибки: InefficientFilter
  • Сообщение об ошибке: The restriction or sort order is too complex for this operation.

Заголовки запросов

Имя Тип Описание
Authorization string Bearer {token}. Обязательно.
Prefer: outlook.body-content-type string Формат возвращаемых свойств body и uniqueBody. Возможные значения: "text" или "html". Если заголовок не указан, свойства body и uniqueBody возвращаются в формате HTML. Необязательный параметр.

Текст запроса

Не указывайте текст запроса для этого метода.

Отклик

В случае успешного 200 OK выполнения этот метод возвращает код отклика и коллекцию объектов сообщений в тексте ответа.

Примеры

Пример 1. Перечисление всех сообщений

Запрос

В первом примере по умолчанию возвращается 10 сообщений по умолчанию в почтовом ящике пользователя, выполнившего вход. $select используется для получения подмножества свойств каждого сообщения в ответе.

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

Отклик

Ниже показан пример отклика. Чтобы получить следующую страницу с сообщениями, примените URL-адрес, возвращенный в @odata.nextLink, для последующего запроса GET.

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

Пример 2. Использование $filter для получения всех сообщений, удовлетворяющих определенному условию

Запрос

В следующем примере фильтруется все сообщения в почтовом ящике пользователя, выполнившего вход, для тех, которые упоминание пользователя. Он также использует $select для возврата подмножества свойств каждого сообщения в ответе.

В следующем примере также включается кодировка URL-адреса для пробелов в строке параметра запроса.

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

Отклик

Ниже показан пример отклика.

Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

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

Пример 3. Использование предпочтительного заголовка для получения текста сообщения и uniqueBody имеет текстовый формат

Запрос

В третьем примере показано, как использовать Prefer: outlook.body-content-type="text" заголовок для получения свойств body и uniqueBody каждого сообщения в текстовом формате.

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

Отклик

Ниже приводится пример отклика.

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