listItem: delta

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Obtenga elementos de lista recién creados, actualizados o eliminados sin tener que realizar una lectura completa de toda la colección de elementos.

La aplicación comienza llamando a delta sin ningún parámetro. El servicio comienza a enumerar la jerarquía de la lista, devolviendo páginas de elementos y un @odata.nextLink o un @odata.deltaLink. La aplicación debe seguir llamando con el @odata.nextLink hasta que vea un @odata.deltaLink devuelto.

Una vez recibidos todos los cambios, puedes aplicarlos en tu estado local. Para comprobar si hay cambios en el futuro, vuelva a llamar delta con el @odata.deltaLink de la respuesta anterior.

La fuente delta muestra el estado más reciente de cada elemento, no cada cambio. Si se ha cambiado el nombre de un elemento dos veces, solo se mostrará una vez, con su último nombre. El mismo artículo puede aparecer más de una vez en una fuente delta, por varios motivos. Debe usar la última repetición que vea.

Los elementos eliminados se devuelven con la faceta eliminada . Deleted Indica que el elemento se eliminó y no se pudo restaurar. Los elementos con esta propiedad deben quitarse de su estado local.

Nota: Solo debe eliminar una carpeta localmente si está vacía después de sincronizar todos los cambios.

Esta API está disponible en las siguientes implementaciones en la nube nacional.

Servicio global Administración pública de EE. UU. Gobierno de EE. UU. L5 (DOD) China operado por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use uno o varios permisos con privilegios más altos solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) Sites.Read.All Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación Sites.Read.All Sites.ReadWrite.All

Solicitud HTTP

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

Parámetros de consulta

En la dirección URL de la solicitud, puede incluir el siguiente parámetro de consulta opcional.

Parámetro Tipo Descripción
token Cadena Si no se especifica, enumera el estado actual de la jerarquía. Si latest, devuelve una respuesta vacía con el token delta más reciente. Si es un token delta anterior, devuelve un nuevo estado desde ese token.

Este método también admite los parámetros de $selectconsulta , $expandy $topOData para personalizar la respuesta.

Encabezados de solicitud

Encabezado Valor
Authorization {token} de portador. Obligatorio. Obtenga más información sobre autenticación y autorización.

Cuerpo de la solicitud

No proporcione un cuerpo de solicitud para este método.

Respuesta

Si se ejecuta correctamente, este método devuelve un código de respuesta 200 OK y una colección de objetos listItem en el cuerpo de la respuesta.

Además de una colección de objetos listItem , la respuesta también incluye una de las siguientes propiedades.

Nombre Valor Descripción
@odata.nextLink URL Una dirección URL para recuperar la siguiente página disponible de cambios, si hay más cambios en el conjunto actual.
@odata.deltaLink URL Una dirección URL que se devuelve en lugar de @odata.nextLink cuando se han devuelto todos los cambios actuales. Use esta propiedad para leer el siguiente conjunto de cambios en el futuro.

En algunos casos, el servicio devuelve un 410 Gone código de respuesta con una respuesta de error que contiene uno de los siguientes códigos de error y un Location encabezado que contiene un nuevo nextLink que inicia una nueva enumeración diferencial. Esto ocurre cuando el servicio no puede proporcionar una lista de cambios para un token determinado; Por ejemplo, si un cliente intenta reutilizar un token antiguo después de haber estado desconectado durante mucho tiempo, o si el estado del servidor ha cambiado y se requiere un nuevo token.

Una vez completada la enumeración completa, compare los elementos devueltos con su estado local y siga las instrucciones basadas en el tipo de error.

Tipo de error Instrucciones
resyncChangesApplyDifferences Reemplace los elementos locales por las versiones del servidor (incluidas las eliminaciones) si está seguro de que el servicio estaba actualizado con los cambios locales la última vez que realizó la sincronización. Cargar cualquier cambio local que no conoce el servidor.
resyncChangesUploadDifferences Cargue los elementos locales que el servicio no devolvió y cargue los elementos que difieran de las versiones del servidor. Guarde ambas copias si no está seguro de cuál está más actualizada.

Además de los errores de resincronización y para obtener más información sobre cómo se devuelven los errores, consulte Respuestas de error de Microsoft Graph y tipos de recursos.

Ejemplos

Ejemplo 1: Solicitud inicial

En el ejemplo siguiente se muestra una solicitud inicial y cómo llamar a esta API para establecer el estado local.

Solicitud

En el ejemplo siguiente se muestra una solicitud inicial.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta que incluye la primera página de cambios y la propiedad @odata.nextLink que indica que no hay más elementos disponibles en el conjunto actual de elementos. Su aplicación debe continuar solicitando el valor de dirección URL @odata.nextLink hasta que se recuperen todas las páginas de elementos.

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

Ejemplo 2: Solicitud de última página

En el ejemplo siguiente se muestra una solicitud que obtiene la última página de un conjunto y cómo llamar a esta API para actualizar el estado local.

Solicitud

En el ejemplo siguiente se muestra una solicitud después de la solicitud inicial.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta que indica que se eliminó el elemento TestItemB.txt con nombre y que se agregó o modificó el elemento TestFolder entre la solicitud inicial y esta solicitud para actualizar el estado local.

La página final de elementos incluye la propiedad @odata.deltaLink que proporciona la dirección URL que se puede usar más tarde para recuperar los cambios del conjunto actual de elementos.

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

En algunos escenarios, es posible que desee solicitar el valor actual deltaLink sin enumerar primero todos los elementos de la lista. Esto puede ser útil si la aplicación solo quiere conocer los cambios y no necesita conocer los elementos existentes. Para recuperar la última deltaLinkllamada delta , con el parámetro ?token=latestde cadena de consulta .

Solicitud

En el ejemplo siguiente se muestra la solicitud.

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

Respuesta

En el ejemplo siguiente se muestra la respuesta.

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