mailFolder: delta

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

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

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

[! Примечание. Дельта-обработка может создавать или обновлять состояние синхронизации, хранящееся в почтовом ящике. На эти записи распространяется принудительное применение квоты хранилища почтовых ящиков. Если почтовый ящик достиг своей применимой квоты хранилища, разностный запрос к папке почты может вернуть ошибку 403 ErrorQuotaExceeded, даже если обычные запросы на чтение папки продолжают завершаться успешно. Сократите использование почтового ящика ниже квоты и повторите разностный запрос. Приложения должны обработать эту ошибку и предоставить затронутым пользователям или администраторам указания для исправления использования хранилища почтовых ящиков.

Этот 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-адресе предыдущего вызова разностной функции для той же коллекции почтовых папок, указывает на завершение этого раунда отслеживания изменений. Сохраните 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 с правильными токенами состояния, чтобы получить набор изменений с момента последнего запроса.

В похожем примере показано, как использовать маркеры состояния для отслеживания изменений в сообщениях в почтовой папке: Получение добавочных изменений сообщений в папке. Основные различия между папками отслеживания почты и отслеживанием сообщений в папке заключаются в 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
    }
  ]
}

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

  • Последнее обновление: