Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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"
}
Ejemplo 3: Solicitud de vínculo delta
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"
}