Control de cambios de una unidadTrack changes for a Drive

Espacio de nombres: microsoft.graphNamespace: microsoft.graph

Este método permite que su aplicación realice el control de cambios de una unidad y de sus elementos secundarios con el tiempo.This method allows your app to track changes to a drive and its children over time.

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.Your app begins by calling delta without any parameters. The service starts enumerating the drive's hierarchy, returning pages of items and either an @odata.nextLink or an @odata.deltaLink, as described below. Your app should continue calling with the @odata.nextLink until you no longer see an @odata.nextLink returned, or you see a response with an empty set of changes.

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.After you have finished receiving all the changes, you may apply them to your local state. To check for changes in the future, call delta again with the @odata.deltaLink from the previous response.

Los elementos eliminados se devuelven con la deletedfaceta. Los elementos con este conjunto de propiedades deben ser eliminados de su estado local.Deleted items are returned with the deleted facet. Items with this property set should be removed from your local state.

Nota: Solo debe eliminar una carpeta de forma local si está vacía después de sincronizar todos los cambios.Note: you should only delete a folder locally if it is empty after syncing all the changes.

PermisosPermissions

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.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Tipo de permisoPermission type Permisos (de menos a más privilegiados)Permissions (from least to most privileged)
Delegado (cuenta profesional o educativa)Delegated (work or school account) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegado (cuenta personal de Microsoft)Delegated (personal Microsoft account) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.AllFiles.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
AplicaciónApplication Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.AllFiles.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All

Solicitud HTTPHTTP request

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ónFunction parameters

ParámetroParameter TipoType DescripciónDescription
tokentoken cadenastring Opcional.Optional. Si no se especifica, enumera el estado actual de la jerarquía.If unspecified, enumerates the hierarchy's current state. Si latest, devuelve una respuesta vacía con el token delta más reciente.If latest, returns empty response with latest delta token. Si es un token delta anterior, devuelve el estado nuevo desde ese token.If a previous delta token, returns new state since that token.

Parámetros de consulta opcionalesOptional query parameters

Este método admite los parámetros de consulta OData $select, $expand y $top para personalizar la respuesta.This method supports the $select, $expand, and $top OData query parameters to customize the response.

RespuestaResponse

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.If successful, this method returns a 200 OK response code and a collection of DriveItem resources in the response body.

Además de la colección de DriveItems, la respuesta también incluirá una de las siguientes propiedades:In addition to the collection of DriveItems, the response will also include one of the following properties:

NombreName ValorValue DescriptionDescription
@odata.nextLink@odata.nextLink urlurl Una dirección URL que recupera la siguiente página de cambios disponible, si hay cambios adicionales en el conjunto actual.A URL to retrieve the next available page of changes, if there are additional changes in the current set.
@odata.deltaLink@odata.deltaLink URLurl Una dirección URL que se devuelve en lugar de @odata.nextLink después de que se hayan devuelto todos los cambios actuales.A URL returned instead of @odata.nextLink after all current changes have been returned. Se utiliza para leer el siguiente conjunto de cambios en el futuro.Used to read the next set of changes in the future.

Ejemplo (solicitud inicial)Example (Initial Request)

Aquí tiene un ejemplo de cómo llamar a esta API para establecer su estado local.Here is an example of how to call this API to establish your local state.

SolicitudRequest

Aquí tiene un ejemplo de la solicitud inicial.Here is an example of the initial request.

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

RespuestaResponse

Aquí tiene un ejemplo de la respuesta.Here is an example of the response.

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 de elementos actual.This response includes the first page of changes, and the @odata.nextLink property indicates that there are more items available in the current set of items. Su aplicación debe seguir solicitando el valor URL de @odata.nextLink hasta recuperar todas las páginas de artículos.Your app should continue to request the URL value of @odata.nextLink until all pages of items have been retrieved.

Ejemplo (última página de un conjunto)Example (Last page in a set)

Aquí tiene un ejemplo de cómo llamar a esta API para actualizar su estado local.Here is an example of how to call this API to update your local state.

SolicitudRequest

Aquí tiene un ejemplo después de la solicitud inicial.Here is an example request after the initial request.

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

RespuestaResponse

Aquí tiene un ejemplo de la respuesta.Here is an example of the response.

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.This response indicates that the item named folder2 was deleted and the item file.txt was either added or modified between the initial request and this request to update the local state.

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.The final page of items will include the @odata.deltaLink property, which provides the URL that can be used later to retrieve changes since the current set of items.

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.There may be cases when the service can't provide a list of changes for a given token (for example, if a client tries to reuse an old token after being disconnected for a long time, or if server state has changed and a new token is required). In these cases the service will return an HTTP 410 Gone error with an error response containing one of the error codes below, and a Location header containing a new nextLink that starts a fresh delta enumeration from scratch. After finishing the full enumeration, compare the returned items with your local state and follow these instructions.

Tipo de errorError Type InstruccionesInstructions
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.Replace any local items with the server's version (including deletes) if you're sure that the service was up to date with your local changes when you last sync'd. Upload any local changes that the server doesn't know about.
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).Upload any local items that the service did not return, and upload any files that differ from the server's version (keeping both copies if you're not sure which one is more up-to-date).

En algunos casos, puede ser útil solicitar el valor deltaLink actual sin enumerar primero todos los elementos que ya hay en la unidad.In some scenarios, it may be useful to request the current deltaLink value without first enumerating all of the items in the drive already.

Esto puede ser útil si su aplicación solo quiere conocer los cambios y no necesita saber si hay elementos existentes.This can be useful if your app only wants to know about changes, and doesn't need to know about existing items. Para recuperar el último valor deltaLink, llame a delta con un parámetro de cadena de consulta ?token=latest.To retrieve the latest deltaLink, call delta with a query string parameter ?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 en **.Note: If you are trying to maintain a full local representation of the items in a folder or a drive, you must use delta for the initial enumeration. Other approaches, such as paging through the children collection of a folder, are not guaranteed to return every single item if any writes take place during the enumeration. Using delta is the only way to guarantee that you've read all of the data you need to.

SolicitudRequest

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

RespuestaResponse

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

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

ComentariosRemarks

  • 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.The delta feed shows the latest state for each item, not each change. If an item were renamed twice, it would only show up once, with its latest name.

  • 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.The same item may appear more than once in a delta feed, for various reasons. You should use the last occurrence you see.

  • 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.The parentReference property on items will not include a value for path. This occurs because renaming a folder does not result in any descendants of the folder being returned from delta. When using delta you should always track items by id.

  • En OneDrive para la Empresa y SharePoint, solo se admite delta en la carpeta root, no en otras carpetas de una unidad.In OneDrive for Business and SharePoint, delta is only supported on the root folder, not on other folders within a drive.

  • 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.Delta query will not return some DriveItem properties, depending on the operation and service type, as shown in the following tables.

    OneDrive para la EmpresaOneDrive for Business

    Tipo de operaciónOperation type Propiedades omitidas por la consulta deltaProperties omitted by delta query
    Crear y modificarCreate/Modify ctag, lastModifiedByctag, lastModifiedBy
    EliminarDelete ctag, lastModifiedBy, namectag, lastModifiedBy, name

    OneDrive (consumidor)OneDrive (consumer)

    Tipo de operaciónOperation type Propiedades omitidas por la consulta deltaProperties omitted by delta query
    Crear y modificarCreate/Modify n/an/a
    EliminarDelete ctag, sizectag, size

Analizar las jerarquías de permisosScanning permissions hierarchies

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.By default, the delta query response will include sharing information for all items in the query that changed even if they inherit their permissions from their parent and did not have direct sharing changes themselves. 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.This typically then results in a follow up call to get the permission details for every item rather than just the ones whose sharing information changed. 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.You can optimize your understanding of how permission changes happen by adding the Prefer: hierarchicalsharing header to your delta query request.

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.When the Prefer: hierarchicalsharing header is provided, sharing information will be returned for the root of the permissions hierarchy, as well as items that explicitly have sharing changes. 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.In cases where the sharing change is to remove sharing from an item, you will find an empty sharing facet to differentiate between items that inherit from their parent and those that are unique but have no sharing links. 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.You will also see this empty sharing facet on the root of a permission hierarchy that is not shared to establish the initial scope.

En la mayoría de los escenarios de análisis, es posible que esté interesado específicamente en los cambios en los permisos.In many scanning scenarios, you might be interested specifically in changes to permissions. 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.To make it clear in the delta query response which changes are the result of permissions being changed, you can provide the Prefer: deltashowsharingchanges header. 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.When this header is provided, all items that appear in the delta query response due to permission changes will have the @microsoft.graph.sharedChanged":"True" OData annotation. Esta característica se aplica a SharePoint y OneDrive para la Empresa, pero no a las cuentas de OneDrive de usuario.This feature is applicable to SharePoint and OneDrive for Business but not consumer OneDrive accounts.

Nota: El uso de Prefer: deltashowsharingchanges encabezado requiere el uso de Prefer: deltashowremovedasdeleted y Prefer: deltatraversepermissiongaps.Note: The use of Prefer: deltashowsharingchanges header requires you to use Prefer: deltashowremovedasdeleted and Prefer: deltatraversepermissiongaps. Estos valores de encabezado se pueden combinar en un único encabezado: Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges.These header values can be joined together in a single header: Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges.

Respuestas de errorError responses

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.In addition to the resync errors detailed above, see Error Responses for details about how errors are returned.