Отслеживание изменений для Drive

Статья
04/08/2023

С помощью этого метода приложение может отслеживать изменения drive и соответствующих дочерних элементов.

Для начала приложение вызывает delta без параметров. Служба начинает перечислять иерархию диска, возвращая страницы элементов и @odata.nextLink или @odata.deltaLink, как показано ниже. Приложению следует выполнять вызовы с использованием @odata.nextLink, пока не будет возвращен отклик без @odata.nextLink или с пустым набором изменений.

Завершив получать изменения, вы можете применить их к локальному состоянию. Для проверки наличия изменений в будущем снова вызовите delta с использованием @odata.deltaLink из предыдущего отклика.

Удаленные элементы возвращаются с аспектом deleted. Элементы с этим набором свойств следует удалить из локального состояния.

Примечание. Локально удалять папку следует, только если после синхронизации всех изменений она пуста.

Разрешения

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

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

HTTP-запрос

GET /drives/{drive-id}/root/delta
GET /groups/{groupId}/drive/root/delta
GET /me/drive/root/delta
GET /sites/{siteId}/drive/root/delta
GET /users/{userId}/drive/root/delta

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

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

Параметры

Имя	Значение	Описание
token	string	Необязательный параметр. Если не указан, перечисляет текущее состояние иерархии. Если используется значение `latest`, возвращает пустой ответ с последним разностным маркером. Если используется предыдущий разностный маркер, возвращает новое состояние с момента того маркера.

Отклик

В случае успеха этот метод возвращает код отклика 200 OK и коллекцию ресурсов DriveItem в теле отклика.

Помимо коллекции ресурсов DriveItem, отклик также включает одно из указанных ниже свойств.

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

Пример (первоначальный запрос)

Ниже приведен пример вызова этого API для определения локального состояния.

Запрос

Ниже приведен пример первоначального запроса.

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

Отклик

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

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

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        },
        {
            "id": "2353010204ddgg",
            "name": "file5.txt",
            "deleted": { }
        }
    ],
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/delta(token=1230919asd190410jlka)"
}

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

Пример (последняя страница в наборе)

Ниже приведен пример вызова этого API для обновления локального состояния.

Запрос

Ниже приведен пример запроса, выполненного после первоначального.

GET https://graph.microsoft.com/v1.0/me/drive/root/delta(token='1230919asd190410jlka')

Отклик

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

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

{
    "value": [
        {
            "id": "0123456789abc",
            "name": "folder2",
            "folder": { },
            "deleted": { }
        },
        {
            "id": "123010204abac",
            "name": "file.txt",
            "file": { }
        }
    ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?(token='1230919asd190410jlka')"
}

Такой отклик означает, что между отправками первоначального запроса и данного запроса (на обновление локального состояния) был удален элемент folder2, а элемент file.txt был добавлен или изменен.

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

В некоторых случаях службе не удается предоставить список изменений для определенного маркера (например, если клиент пытается повторно использовать старый маркер после долгого отключения, а также если из-за измененного состояния сервера требуется новый маркер). В таких случаях служба возвращает ошибку HTTP 410 Gone с откликом, содержащим один из представленных ниже кодов ошибок, и заголовком Location, содержащим новый аргумент nextLink, который начинает новое перечисление delta. По завершении полного перечисления сравните возвращенные элементы с локальным состоянием и выполните указанные ниже действия.

Тип ошибки Инструкции

resyncChangesApplyDifferences Замените все локальные элементы (в том числе удаленные) соответствующими элементами с сервера, если вы уверены, что при последней синхронизации в службу были внесены все локальные изменения. Отправьте все локальные изменения, не загруженные на сервер.

resyncChangesUploadDifferences Отправьте все локальные элементы, не возвращенные службой, и все файлы, отличающиеся от соответствующих файлов на сервере (сохраняйте обе копии, если вы не знаете, какая из них более актуальна).

Тип ошибки	Инструкции
`resyncChangesApplyDifferences`	Замените все локальные элементы (в том числе удаленные) соответствующими элементами с сервера, если вы уверены, что при последней синхронизации в службу были внесены все локальные изменения. Отправьте все локальные изменения, не загруженные на сервер.
`resyncChangesUploadDifferences`	Отправьте все локальные элементы, не возвращенные службой, и все файлы, отличающиеся от соответствующих файлов на сервере (сохраняйте обе копии, если вы не знаете, какая из них более актуальна).

Получение текущего значения deltaLink

В некоторых случаях может быть удобно запросить текущее значение deltaLink, не перечисляя перед этим все элементы, уже хранящиеся в объекте drive.

Это может быть полезно, если приложению достаточно узнать об изменениях и ему не нужны сведения о существующих элементах. Чтобы получить последнее значение deltaLink, вызовите функцию delta с параметром ?token=latest в строке запроса.

Примечание. Если вы пытаетесь поддерживать полное локальное представление элементов в папке или на диске, необходимо использовать delta для исходного перечисления. Другие подходы, например постраничный просмотр коллекции children для папки, не гарантируют возврата всех элементов, если во время перечисления выполняются операции записи. Только с помощью функции delta можно гарантировать, что считываются все необходимые данные.

Запрос

GET /me/drive/root/delta?token=latest

Отклик

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

{
    "value": [ ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?token=1230919asd190410jlka"
}

Заметки

В разностном канале показано последнее состояние каждого элемента, а не каждое изменение. Если элемент был переименован дважды, он будет указан только один раз, но с последним именем.
По ряду причин один и тот же элемент может отображаться в разностном канале несколько раз. Следует использовать последний представленный вариант.
Свойство parentReference элементов не включает значение path. Это вызвано тем, что при переименовании папки ее потомки не возвращаются с помощью delta. При использовании delta следует всегда отслеживать элементы по идентификатору.
Для общих папок, добавленных на диск, разностный вызов не возвращает никаких сведений об изменениях внутри общей папки. Вместо этого необходимо создать другой разностный вызов, обращающийся непосредственно к общей папке.
Разностный вызов содержит дополнительные ограничения в OneDrive для бизнеса. Дополнительные сведения см. в заметках о выпуске.

Ответы с ошибками

Помимо вышеописанных ошибок повторной синхронизации, в статье Ответы с ошибками представлены сведения о том, как возвращаются ошибки.

Отслеживание изменений для Drive

Разрешения

HTTP-запрос

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

Параметры

Отклик

Пример (первоначальный запрос)

Запрос

Отклик

Пример (последняя страница в наборе)

Запрос

Отклик

Получение текущего значения deltaLink

Запрос

Отклик

Заметки

Ответы с ошибками

Дополнительные ресурсы