listItem: delta

  • Artículo

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, a devolver páginas de elementos y a @odata.nextLink o a @odata.deltaLink. La aplicación debe seguir llamando con @odata.nextLink hasta que vea que se devuelve un @odata.deltaLink .

Después de recibir todos los cambios, puede aplicarlos a su estado local. Para comprobar si hay cambios en el futuro, vuelva a llamar a delta con @odata.deltaLink desde la respuesta anterior.

La fuente delta muestra el estado más reciente de cada elemento, no cada cambio. Si se cambió el nombre de un elemento dos veces, solo aparece una vez, con su nombre más reciente. El mismo elemento podría aparecer más de una vez en una fuente delta, por varias razones. Debe usar la última repetición que vea.

Los elementos eliminados se devuelven con la faceta eliminada . Deleted indica que el elemento se elimina y no se puede restaurar. Los elementos con esta propiedad deben quitarse del 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 nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores 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 latestes , devuelve una respuesta vacía con el token delta más reciente. Si un token delta anterior, devuelve un nuevo estado desde ese token.

Este método también admite los $selectparámetros de consulta , $expandy $top OData para personalizar la respuesta.

Encabezados de solicitud

Encabezado Valor
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la 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 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 enumeración delta nueva. 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 desconectarse 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 el 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 cuando se sincronizó por última vez. Cargar cualquier cambio local que no conoce el servidor.
resyncChangesUploadDifferences Cargue los elementos locales que el servicio no devolviera y cargue los elementos que difieren de las versiones del servidor. Mantenga 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 errores y tipos de recursos de Microsoft Graph.

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: Última solicitud de 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 el elemento denominado TestItemB.txt se eliminó y que el elemento TestFolder se agregó o modificó 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 adelante para recuperar los cambios desde el 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 saber sobre los cambios y no necesita saber sobre los elementos existentes. Para recuperar la versión más reciente deltaLink, llame a 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"
}

Contenido relacionado