Поделиться через


contactFolder: delta

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

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

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

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

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

Разрешения

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

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

HTTP-запрос

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

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

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

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

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

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

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

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

Отклик

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

Пример

Запрос

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

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

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

GET https://graph.microsoft.com/v1.0/me/contactFolders/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/contactfolders/delta?$skiptoken={_skipToken_}",
  "value": [
    {
     "parentFolderId": "parentFolderId-value",
      "displayName": "displayName-value",
      "id": "id-value"
    }
  ]
}