driveItem: delta

Artículo
10/02/2023

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.

Permisos

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 es un token delta anterior, devuelve el estado nuevo 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.

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	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. 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/v1.0/me/drive/root/delta


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Delta.GetAsDeltaGetResponseAsync();


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items delta get --drive-id {drive-id} --drive-item-id {driveItem-id}



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Delta().GetAsDeltaGetResponse(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").delta().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->delta()->get()->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveItemDelta -DriveId $driveId -DriveItemId $driveItemId


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').delta.get()

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

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

Solicitud

Esta es una solicitud de ejemplo después de la solicitud inicial.

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].DeltaWithToken("{token}").GetAsDeltaWithTokenGetResponseAsync();


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items delta-with-token get --token {token-id} --drive-id {drive-id} --drive-item-id {driveItem-id}



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



token := "{token}"
delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").DeltaWithToken(&token).GetAsDeltaWithTokenGetResponse(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").deltaWithToken("{token}").get();


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta(token='MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM3OTQzNzQwODQ3NTcwMDAwOzU4NTk2OTY0NDslMjM7JTIzOyUyMzA')')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->deltaWithToken('{token}', )->get()->wait();

Snippet not available


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').delta_with_token("{token}").get()

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

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.

En algunos casos, puede que el servicio no pueda proporcionar una lista de cambios de un token determinado (por ejemplo, si un cliente intenta volver a usar 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 devuelve un HTTP 410 Gone error con una respuesta de error que contiene uno de los códigos de error siguientes 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).

Ejemplo 3: Recuperar el deltaLink actual

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.

Solicitud

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Token = "latest";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items delta get --drive-id {drive-id} --drive-item-id {driveItem-id}



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestToken := "latest"

requestParameters := &graphdrives.DriveItemItemItemDelta()RequestBuilderGetQueryParameters{
	Token: &requestToken,
}
configuration := &graphdrives.DriveItemItemItemDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Delta().GetAsDeltaGetResponse(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.token = "latest";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta?token=latest')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->token = "latest";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->delta()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveItemDelta -DriveId $driveId -DriveItemId $driveItemId -Token "latest"


from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		token = "latest",
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').delta.get(request_configuration = request_configuration)

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.

Solicitud

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Drives["{drive-id}"].Items["{driveItem-id}"].Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Token = "2021-09-29T20:00:00Z";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives items delta get --drive-id {drive-id} --drive-item-id {driveItem-id}



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphdrives "github.com/microsoftgraph/msgraph-sdk-go/drives"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestToken := "2021-09-29T20:00:00Z"

requestParameters := &graphdrives.DriveItemItemItemDelta()RequestBuilderGetQueryParameters{
	Token: &requestToken,
}
configuration := &graphdrives.DriveItemItemItemDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

delta, err := graphClient.Drives().ByDriveId("drive-id").Items().ByDriveItemId("driveItem-id").Delta().GetAsDeltaGetResponse(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.drives().byDriveId("{drive-id}").items().byDriveItemId("{driveItem-id}").delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.token = "2021-09-29T20:00:00Z";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/drive/root/delta?token=2021-09-29T20:00:00Z')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Items\Item\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->token = "2021-09-29T20:00:00Z";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->items()->byDriveItemId('driveItem-id')->delta()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveItemDelta -DriveId $driveId -DriveItemId $driveItemId -Token "2021-09-29T20:00:00Z"


from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		token = "2021-09-29T20:00:00Z",
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').items.by_drive_item_id('driveItem-id').delta.get(request_configuration = request_configuration)

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 incluirá un valor para la ruta de acceso. Esto ocurre porque el cambio de nombre de una carpeta no da lugar a que ningún descendiente de la carpeta se devuelva de delta. Cuando utilice delta, debe hacer siempre un seguimiento de los elementos mediante id.
La consulta delta no devolverá algunas propiedades DriveItem, según 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

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

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. Esto suele dar lugar a 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 verá esta faceta de uso compartido vacío 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 que se han mostrado anteriormente, vea Respuestas de error para obtener información sobre cómo se devuelven los errores.

Uso de una consulta delta para realizar un seguimiento de los cambios en los procedimientos recomendados de datos de Microsoft Graph para detectar archivos y detectar cambios a escala

driveItem: delta

Permisos

Solicitud HTTP

Parámetros de función

Parámetros de consulta opcionales

Encabezados de solicitud

Cuerpo de la solicitud

Respuesta

Ejemplos

Ejemplo 1: Solicitud inicial

Solicitud

Respuesta

Ejemplo 2: Última página de un conjunto

Solicitud

Respuesta

Ejemplo 3: Recuperar el deltaLink actual

Solicitud

Respuesta

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

Solicitud

Respuesta

Comentarios

Analizar las jerarquías de permisos

Respuestas de error

Contenido relacionado

Comentarios

Comentarios

Recursos adicionales