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


contact: 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/{id}/contacts/delta
GET /users/{id}/contactFolders/{id}/contacts/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 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 и объект коллекции contact в теле отклика.

Пример

Запрос

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

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

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

GET https://graph.microsoft.com/v1.0/me/contactFolders/{id}/contacts/delta?$select=displayName
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/{id}/contacts/delta?$skiptoken={_skipToken_}",
  "value": [
    {
      "parentFolderId": "parentFolderId-value",
      "birthday": "2016-10-19T10:37:00Z",
      "fileAs": "fileAs-value",
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "initials": "initials-value"
    }
  ]
}