driveItem: delta

Espacio de nombres: microsoft.graph

Controle los cambios en un driveItem y sus elementos secundarios a lo largo del tiempo.

La aplicación comienza llamando a delta sin ningún parámetro. El servicio comienza enumerando la jerarquía de la unidad, devuelve páginas de elementos y también @odata.nextLink o @odata.deltaLink, tal y como se describe a continuación. La aplicación debe continuar la llamada con @odata.nextLink hasta que ya no se devuelva @odata.nextLink o hasta que la respuesta contenga un conjunto de cambios vacío.

Una vez que termine de recibir todos los cambios, puede aplicarlos a su estado local. Para comprobar si hay cambios en el futuro, llame a delta con el @odata.deltaLink de la respuesta anterior.

Los elementos eliminados se devuelven con la deletedfaceta. Los elementos con este conjunto de propiedades deben ser eliminados de su estado local.

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

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
Aplicación Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Solicitud 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

Parámetros de función

Parámetro Tipo Descripción
token cadena Opcional. 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 el estado nuevo desde ese token.

Parámetros de consulta opcionales

Este método admite los parámetros de consulta OData $select, $expand y $top para personalizar la respuesta.

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio.

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 recursos DriveItem en el cuerpo de la respuesta.

Además de la colección de DriveItems, la respuesta también incluirá una de las siguientes propiedades:

Nombre Valor Description
@odata.nextLink url Una dirección URL que recupera la siguiente página de cambios disponible, si hay cambios adicionales 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. Se utiliza para leer el siguiente conjunto de cambios en el futuro.

Ejemplos

Ejemplo 1: Solicitud inicial

Aquí tiene un ejemplo de cómo llamar a esta API para establecer su estado local.

Solicitud

Aquí tiene un ejemplo de la solicitud inicial.

GET https://graph.microsoft.com/v1.0/me/drive/root/delta

Respuesta

Aquí tiene un ejemplo de la respuesta.

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

Esta respuesta incluye la primera página de cambios y la propiedad @odata.nextLink indica que 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.

Ejemplo 2: Última página de un conjunto

Aquí tiene un ejemplo de cómo llamar a esta API para actualizar su estado local.

Solicitud

Aquí tiene un ejemplo después de la solicitud inicial.

GET https://graph.microsoft.com/v1.0/me/drive/root/delta(token='1230919asd190410jlka')

Respuesta

Aquí tiene un ejemplo de la respuesta.

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

Esta respuesta indica que el elemento llamado folder2 se ha eliminado y el elemento file.txt se ha agregado o se ha modificado entre la solicitud inicial y esta solicitud para actualizar el estado local.

La última página de elementos incluirá la propiedad @odata.deltaLink, que proporciona la dirección URL que se puede usar posteriormente para recuperar los cambios desde el conjunto de elementos actual.

En algunos casos, puede que el servicio no pueda proporcionar una lista de cambios de un token determinado (por ejemplo, si un cliente intenta reutilizar un token anterior después de haber estado desconectado durante mucho tiempo o si ha cambiado el estado del servidor y se requiere un nuevo token). En estos casos, el servicio devolverá un error HTTP 410 Gone con una respuesta de error que contiene uno de los códigos de error siguientes y un encabezado Location con un nuevo nextLink que comienza una nueva enumeración delta desde cero. Cuando finalice la enumeración completa, compare los elementos devueltos con su estado local y siga estas instrucciones.

Tipo de error Instrucciones
resyncChangesApplyDifferences Reemplace cualquier elemento local con la versión del servidor (incluyendo eliminaciones) si está seguro de que el servicio estaba actualizado con sus cambios locales cuando lo sincronizó por última vez. Cargue cualquier cambio local que no conozca el servidor.
resyncChangesUploadDifferences Cargue cualquier elemento local que el servicio no devolvió y cargue cualquier archivo que difiera de la versión del servidor (mantenga ambas copias si no está seguro de cuál está más actualizada).

En algunos casos, puede ser útil solicitar el valor deltaLink actual sin enumerar primero todos los elementos que ya hay en la unidad.

Esto puede ser útil si su aplicación solo quiere conocer los cambios y no necesita saber si hay elementos existentes. Para recuperar el último valor deltaLink, llame a delta con un parámetro de cadena de consulta ?token=latest.

Nota: si está intentando mantener una representación local completa de los elementos de una carpeta o una unidad, debe usar delta para la enumeración inicial. Otros enfoques, como la paginación mediante la colección children de una carpeta, no se garantizan para devolver cada elemento único si se produce una escritura durante la enumeración. Usar delta es la única manera de garantizar que ha leído todos los datos que necesita.

Solicitud

GET /me/drive/root/delta?token=latest

Respuesta

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

{
    "value": [ ],
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?token=1230919asd190410jlka"
}

Ejemplo 4: Recuperación de resultados diferenciales mediante una marca de tiempo

En algunos escenarios, el cliente puede conocer el estado de una unidad hasta un momento específico, pero no tener un deltaLink para ese momento dado. En este caso, el cliente puede llamar a delta usando una marca de tiempo con codificación URL para el valor del parámetro de cadena de consulta token, por ejemplo, ?token=2021-09-29T20%3A00%3A00Z o '?token=2021-09-29T12%3A00%3A00%2B8%3A00'.

El uso de una marca de tiempo en lugar de un token solo se admite en OneDrive para la Empresa y SharePoint.

Nota: los clientes deben usar el deltaLink proporcionado por consultas delta siempre que sea posible, en lugar de generar su propio token. Esta funcionalidad solo debería usarse cuando no se conoce deltaLink.

Solicitud

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

Respuesta

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

Comentarios

  • 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 aparecerá una vez con el nombre más reciente.

  • El mismo elemento puede aparecer más de una vez en una fuente delta por diversas razones. Debe utilizar la última repetición que vea.

  • La propiedad parentReference de los elementos no incluirá un valor de ruta de acceso. Esto ocurre porque el cambio de nombre de una carpeta no devuelve los descendientes de la carpeta desde delta. Cuando utilice delta, debe hacer siempre un seguimiento de los elementos mediante id.

  • La consulta delta no devolverá algunas propiedades DriveItem, según el tipo de servicio y la operación, como se muestra en las tablas siguientes.

    OneDrive para la Empresa

    Tipo de operación Propiedades omitidas por la consulta delta
    Crear y modificar ctag
    Eliminar ctag, name

    OneDrive (consumidor)

    Tipo de operación Propiedades omitidas por la consulta delta
    Crear y modificar n/a
    Eliminar ctag, size

Analizar las jerarquías de permisos

De forma predeterminada, en la respuesta de la consulta de diferencias se incluirá la información de uso compartido para todos los elementos de la consulta que cambien aunque hereden sus permisos de su elemento primario y que no tengan cambios en el uso compartido directo. Por lo general, esto hace que se haga una llamada de seguimiento para obtener los detalles de los permisos de cada elemento, en lugar de solo los de aquellos cuya información compartida ha cambiado. Puede optimizar su comprensión de cómo se producen los cambios de permisos agregando el encabezado Prefer: hierarchicalsharing a la solicitud de consulta diferencial.

Cuando se proporciona el encabezado Prefer: hierarchicalsharing, se devolverá información de uso compartido para la raíz de la jerarquía de permisos, así como los elementos que tienen explícitamente cambios compartidos. En los casos en los que el cambio de uso compartido se vaya a quitar el uso compartido de un elemento, encontrará una faceta de aspecto compartido vacío para diferenciar entre los elementos que heredan de su primario y los que son únicos, pero que no tienen vínculos para compartir. También verá esta faceta de uso compartido vacía en la raíz de una jerarquía de permisos que no se comparte para establecer el ámbito inicial.

En la mayoría de los escenarios de análisis, es posible que esté interesado específicamente en los cambios en los permisos. Para que quede claro en la respuesta a la consulta diferencial los cambios que se producen al cambiar los permisos, puede proporcionar el encabezado Prefer: deltashowsharingchanges. Cuando se proporciona este encabezado, todos los elementos que aparecen en la respuesta a la consulta diferencial debido a cambios en los permisos tendrán la @microsoft.graph.sharedChanged":"True" anotación OData. Esta característica se aplica a SharePoint y OneDrive para la Empresa, pero no a las cuentas de OneDrive de usuario.

Nota: El uso de Prefer: deltashowsharingchanges encabezado requiere el uso de Prefer: deltashowremovedasdeleted y Prefer: deltatraversepermissiongaps. Estos valores de encabezado se pueden combinar en un único encabezado: Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges.

Respuestas de error

Además de los errores de resincronización que se han mostrado anteriormente, vea Respuestas de error para obtener información sobre cómo se devuelven los errores.