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

driveItem: delta

  • Статья

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

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Отслеживание изменений в элементе driveItem и его дочерних компонентах с течением времени.

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

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

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

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

Разрешения

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

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) Files.Read Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Делегированные (личная учетная запись Майкрософт) Files.Read Files.Read.All, Files.ReadWrite, 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

Параметры функции

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

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

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

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

Имя Описание
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
deltaExcludeParent Строка. Если этот заголовок запроса включен, ответ включает измененные элементы, а не родительские элементы в иерархии.

Текст запроса

Не указывайте текст запроса для этого метода.

Отклик

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

Помимо коллекции DriveItems, ответ также включает одно из следующих свойств:

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

Примеры

Пример 1. Исходный запрос

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

Запрос

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

GET https://graph.microsoft.com/beta/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 , пока не будут извлечены все страницы элементов.

Пример 2. Последняя страница в наборе

В следующем примере показано, как вызвать этот API для обновления локального состояния.

Запрос

В следующем примере показан запрос после первоначального запроса.

GET https://graph.microsoft.com/beta/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, который запускает новое разностное перечисление с нуля. По завершении полного перечисления сравните возвращенные элементы с локальным состоянием и выполните указанные ниже действия.

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

В некоторых случаях может быть удобно запросить текущее значение 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"
}

Пример 4: Получение результатов delta с использованием метки времени

В некоторых сценариях клиент может знать состояние диска до определенного момента времени, но не иметь deltaLink для этого момента времени. В этом случае клиент может вызвать delta , используя метку времени в кодировке URL-адреса для значения token параметра строки запроса, например, ?token=2021-09-29T20%3A00%3A00Z или '?token=2021-09-29T12%3A00%3A00%2B8%3A00'.

Использование метки времени вместо токена поддерживается только в OneDrive для бизнеса и SharePoint.

Примечание. Клиенты должны по возможности использовать deltaLink, что предоставляется запросами delta, а не создавать собственный токен. Эту возможность следует использовать, только если элемент deltaLink неизвестен.

Запрос

Ниже показан пример запроса.

GET /me/drive/root/delta?token=2021-09-29T20%3A00%3A00Z

Отклик

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

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')"
}

Замечания

  • В разностном канале показано последнее состояние каждого элемента, а не каждое изменение. Если элемент был переименован дважды, он будет указан только один раз, но с последним именем.

  • По ряду причин один и тот же элемент может отображаться в разностном канале несколько раз. Следует использовать последний представленный вариант.

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

  • Разностный запрос не возвращает некоторые свойства DriveItem в зависимости от операции и типа службы, как показано в следующих таблицах.

    OneDrive для бизнеса

    Тип операции Свойства, опущенные запросом изменений
    Создание или изменение ctag
    Удаление ctag, name

    OneDrive (для потребителей)

    Тип операции Свойства, опущенные запросом изменений
    Создание или изменение н/д
    Удаление ctag, size

Сканирование иерархии разрешений

По умолчанию ответ разностного запроса включает общий доступ ко всем измененным элементам в запросе, даже если они наследуют свои разрешения от родительского элемента и не имеют изменений прямого общего доступа. Обычно это приводит к последующему вызову для получения сведений о разрешениях для каждого элемента, а не только для тех, чьи сведения о совместном доступе изменились. Чтобы получить более детальные сведения о произошедших изменениях разрешений, добавьте в запрос заголовок Prefer: hierarchicalsharing.

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

Во многих сценариях сканирования интерес представляют именно изменения разрешений. Чтобы получить сведения о том, какие изменения являются следствием изменений разрешений, можно использовать в запросе заголовок Prefer: deltashowsharingchanges. При указании этого заголовка все элементы, которые отображаются в ответе разностного запроса из-за изменения разрешений, имеют заметку @microsoft.graph.sharedChanged":"True" OData. Эта функция применима к SharePoint и OneDrive для бизнеса, но не к личным учетным записям OneDrive.

Примечание.

  • Для использования заголовка Prefer: deltashowsharingchanges требуется использовать Prefer: deltashowremovedasdeleted и Prefer: deltatraversepermissiongaps. Эти значения заголовка можно объединить в один общий заголовок: Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges.

  • Чтобы правильно обрабатывать разрешения, приложению потребуется запросить разрешения Sites.FullControl.All .

Дополнительные сведения о сценариях сканирования см. в статье Рекомендации по обнаружению файлов и обнаружению изменений в большом масштабе.

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

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

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

Отслеживание изменений в данных Microsoft Graph с помощью разностного запроса. Рекомендации по обнаружению файлов и обнаружению изменений в большом масштабе.