mailFolder: delta

  • Статья

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

Получение набора папок почты, которые были добавлены в почтовый ящик пользователя или удалены из него.

Вызов разностной функции для почтовых папок в почтовом ящике аналогичен запросу GET, за исключением того, что, применяя маркеры состояния в одном или нескольких из этих вызовов, можно запросить добавочные изменения в почтовых папках. Это позволяет поддерживать и синхронизировать локальное хранилище почтовых папок пользователя без необходимости каждый раз получать все почтовые папки этого почтового ящика с сервера.

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

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

Разрешения

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

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

HTTP-запрос

GET /me/mailFolders/delta
GET /users/{id}/mailFolders/delta

Параметры запроса

При отслеживании изменений в почтовых папках выполняется цикл из одного или нескольких вызовов разностной функции. Если вы используете параметры запроса, отличные от $deltatoken и $skiptoken, их необходимо указать в начальном запросе delta. Microsoft Graph автоматически кодирует указанные параметры в маркере, входящем в состав URL-адреса @odata.nextLink или @odata.deltaLink, включенного в отклик. Параметры запроса нужно указать только один раз в первом запросе. В последующих запросах просто скопируйте и примените @odata.nextLink URL-адрес или @odata.deltaLink из предыдущего ответа, так как этот URL-адрес уже содержит закодированные требуемые параметры.

Параметр запроса Тип Описание
$deltatoken string Маркер состояния, возвращенный в @odata.deltaLink URL-адресе предыдущего вызова функции delta для той же коллекции папок почты, что указывает на завершение этого цикла отслеживания изменений. Сохраните URL-адрес @odata.deltaLink с этим токеном и примените его в первом запросе следующего цикла отслеживания изменений для этой коллекции.
$skiptoken строка Этот токен состояния возвращается в URL-адресе @odata.nextLink предыдущего вызова функции delta и указывает, что из коллекции почтовых папок получены не все изменения.

Параметры запросов OData

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

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

Имя Тип Описание
Authorization string Bearer {token}. Обязательно.
Content-Type string application/json. Обязательный параметр.
Prefer string odata.maxpagesize={x}. Необязательный параметр.

Отклик

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

Пример

Запрос

В следующем примере показано, как выполнить один вызов функции delta и ограничить максимальное количество папок почты в тексте ответа до 2.

Чтобы отследить изменения в почтовых папках почтового ящика, выполните один или несколько вызовов функции delta с правильными токенами состояния, чтобы получить набор изменений с момента последнего запроса.

Вы можете найти аналогичный пример, показывающий, как использовать маркеры состояния для отслеживания изменений в сообщениях почтовой папки: Получение добавочных изменений в сообщениях в папке. Различия main между почтовыми папками отслеживания и отслеживанием сообщений в папке — в URL-адресах запросов разностного запроса, а ответы запросов возвращают mailFolder, а не коллекции сообщений.

GET https://graph.microsoft.com/v1.0/me/mailFolders/delta

Prefer: odata.maxpagesize=2
Отклик

Если запрос выполнен успешно, ответ будет включать маркер состояния, который представляет собой skipToken (в заголовке ответа @odata.nextLink ) или deltaToken (в заголовке ответа @odata.deltaLink ). Соответственно, они указывают, следует ли продолжить цикл или вы завершили получение всех изменений для этого раунда.

Ниже показан отклик с маркером состояния skipToken в заголовке отклика @odata.nextLink.

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

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

{
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/mailFolders/delta?$skiptoken={_skipToken_}",
  "value": [
    {
      "displayName": "displayName-value",
      "parentFolderId": "parentFolderId-value",
      "childFolderCount": 99,
      "unreadItemCount": 99,
      "totalItemCount": 99
    }
  ]
}

Связанные материалы