listItem: delta

  • Статья

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

Важно!

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

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

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

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

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

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

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

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

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

Разрешения

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

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

HTTP-запрос

GET /sites/{siteId}/lists/{listId}/items/delta

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

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

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

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

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

Заголовок Значение
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.

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

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

Отклик

В случае успеха этот метод возвращает код отклика 200 OK и совокупность объектов listItem в тексте отклика.

Помимо коллекции объектов listItem , ответ также включает одно из следующих свойств.

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

В некоторых случаях служба возвращает 410 Gone код ответа с ответом об ошибке, содержащим один из следующих кодов ошибок, и Location заголовок, содержащий новый nextLink , который запускает новое разностное перечисление. Это происходит, когда служба не может предоставить список изменений для заданного маркера; Например, если клиент пытается повторно использовать старый маркер после длительного отключения или состояние сервера изменилось и требуется новый маркер.

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

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

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

Примеры

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

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

Запрос

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

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta

Отклик

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

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

{
  "value": [
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
      "id": "1",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "1",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Folder"
      }
    },
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC067},756\"",
      "id": "2",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemA.txt",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "2",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      }
    },
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC068},756\"",
      "id": "3",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemB.txt",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "3",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      }
    }
  ],
  "@odata.nextLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

Пример 2. Запрос последней страницы

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

Запрос

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

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka

Отклик

В следующем примере показан ответ, указывающий, что элемент с именем TestItemB.txt был удален, а элемент TestFolder был добавлен или изменен между первоначальным запросом и этим запросом для обновления локального состояния.

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

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

{
  "value": [
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
      "id": "1",
      "lastModifiedDateTime": "2016-03-21T20:01:37Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "1",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Folder"
      }
    },
    {
      "id": "3",
      "parentReference": {
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      },
      "deleted": {
        "state": "deleted"
      }
    }
  ],
  "@odata.deltaLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

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

Запрос

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

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=latest

Отклик

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

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

{
  "value": [ ],
  "@odata.deltaLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

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