Compartir a través de

driveItem: 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.

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 a enumerar la jerarquía de la unidad, devolviendo páginas de elementos y o @odata.nextLink .@odata.deltaLink 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 haya terminado 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 localmente si está vacía después de sincronizar todos los cambios.

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) Files.Read Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft) Files.Read Files.Read.All, Files.ReadWrite, 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 un token delta anterior devuelve un nuevo estado desde ese token.

Parámetros de consulta opcionales

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

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
deltaExcludeParent Cadena. Si se incluye este encabezado de solicitud, la respuesta incluye los elementos que han cambiado y no los elementos primarios de la jerarquía.

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 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 Dirección URL devuelta en lugar de @odata.nextLink después de que se devuelvan todos los cambios actuales. Se utiliza para leer el siguiente conjunto de cambios en el futuro.

Ejemplos

Ejemplo 1: Solicitud inicial

Este es un ejemplo de cómo llamar a esta API para establecer el estado local.

Solicitud

Este es un ejemplo de la solicitud inicial.

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

Respuesta

En el ejemplo siguiente se muestra 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. La aplicación debe seguir solicitando el valor de dirección URL de @odata.nextLink hasta que se recuperen todas las páginas de elementos.

Ejemplo 2: Última página de un conjunto

En el ejemplo siguiente se muestra 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/me/drive/root/delta(token='1230919asd190410jlka')

Respuesta

En el ejemplo siguiente se muestra 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 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.

Puede haber casos en los que el servicio no pueda 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). En estos casos, el servicio devuelve un HTTP 410 Gone error con una respuesta de error que contiene un código de error y un Location encabezado que contiene un nuevo nextLink que inicia una enumeración delta nueva 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 los elementos locales por la versión 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 archivos que difieren de la versión del servidor (manteniendo ambas copias si no está seguro de cuál está más actualizado).

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

Puede ser útil si la aplicación solo quiere saber sobre los cambios y no necesita saber sobre los 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

En el ejemplo siguiente se muestra la solicitud.

GET /me/drive/root/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/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 mediante delta una marca de tiempo codificada en URL para el valor del parámetro de cadena de token consulta, 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

En el ejemplo siguiente se muestra la solicitud.

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

Respuesta

En el ejemplo siguiente se muestra 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')"
}

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 usar la última repetición que vea.

  • La parentReference propiedad de los elementos no incluye un valor para path. Se produce porque el cambio de nombre de una carpeta no da lugar a que ningún descendiente de la carpeta se devuelva de delta. Al usar delta, siempre debe realizar un seguimiento de los elementos por identificador.

  • La consulta delta no devuelve algunas propiedades DriveItem, en función de la operación y el tipo de servicio, 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, la respuesta de consulta delta incluye el uso compartido de información para todos los elementos de la consulta que cambiaron incluso si heredan sus permisos de su elemento primario y no tenían cambios de uso compartido directo por sí mismos. Normalmente, se produce una llamada de seguimiento para obtener los detalles del permiso de cada elemento en lugar de solo los que han cambiado la información de uso compartido. 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 Prefer: hierarchicalsharing encabezado, se devuelve información de uso compartido para la raíz de la jerarquía de permisos y los elementos que tienen cambios de uso compartido explícitamente. En los casos en los que el cambio de uso compartido consiste en quitar el uso compartido de un elemento, encontrará una faceta de uso compartido vacía para diferenciar entre los elementos que heredan de su elemento primario y los que son únicos pero no tienen vínculos de uso compartido. También puede 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 de consulta delta debido a cambios de permisos tienen 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 del Prefer: deltashowsharingchanges encabezado requiere que use Prefer: deltashowremovedasdeleted y Prefer: deltatraversepermissiongaps. Estos valores de encabezado se pueden combinar en un único encabezado: Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges.

  • Para procesar los permisos correctamente, la aplicación tendrá que solicitar permisos Sites.FullControl.All .

Para obtener más información sobre los escenarios de examen, consulte Procedimientos recomendados para detectar archivos y detectar cambios a escala.

Respuestas de error

Además de los errores de resincronización detallados , consulte Respuestas de error para obtener más información sobre cómo se devuelven los errores.

Contenido relacionado

Usar la consulta delta para realizar el seguimiento de los cambios en datos de Microsoft Graph. Procedimientos recomendados para detectar archivos y detectar cambios a escala.