driveItem: delta
Namespace: microsoft.graph
Acompanhe as alterações em um driveItem e seus filhos ao longo do tempo.
Seu aplicativo começa chamando delta
sem parâmetros.
O serviço começa a enumerar a hierarquia da unidade, retornando páginas de itens e um @odata.nextLink
ou @odata.deltaLink
, conforme descrito abaixo.
Seu aplicativo deve continuar chamando com o @odata.nextLink
até que você não veja mais um @odata.nextLink
retornado ou até que você veja uma resposta com um conjunto vazio de alterações.
Quando terminar de receber todas as alterações, você pode aplicá-las ao seu estado local.
Para verificar se há alterações no futuro, chame delta
novamente com o @odata.deltaLink
da resposta anterior.
Itens excluídos são retornados com a faceta deleted
.
Itens com esse conjunto de propriedades devem ser removidos do seu estado local.
Observação: você apenas deverá excluir uma pasta localmente se ela ficar vazia após a sincronização de todas as alterações.
Permissões
Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.
Tipo de permissão | Permissões menos privilegiadas | Permissões privilegiadas mais altas |
---|---|---|
Delegado (conta corporativa ou de estudante) | Files.Read | Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
Delegado (conta pessoal da Microsoft) | Files.Read | Files.Read.All, Files.ReadWrite, Files.ReadWrite.All |
Application | Files.Read.All | Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
Solicitação 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 função
Parâmetro | Tipo | Descrição |
---|---|---|
token | string | Opcional. Quando não é especificado, enumera o estado da hierarquia atual. Quando é latest , retorna uma resposta vazia com o token delta mais recente. Quando é um token delta anterior, retorna o novo estado após o token. |
Parâmetros de consulta opcionais
Esse método dá suporte aos $select
parâmetros de consulta , $expand
e $top
OData para personalizar a resposta.
Cabeçalhos de solicitação
Nome | Descrição |
---|---|
Autorização | {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização. |
Corpo da solicitação
Não forneça um corpo de solicitação para esse método.
Resposta
Se for bem-sucedido, esse método retornará um código de resposta 200 OK
e uma coleção de recursos Driveitem no corpo da resposta.
Além da coleção de DriveItems, a resposta também incluirá uma das seguintes propriedades:
Nome | Valor | Descrição |
---|---|---|
@odata.nextLink | url | Uma URL para recuperar a próxima página disponível de alterações, se houver mais alterações no conjunto atual. |
@odata.deltaLink | url | Uma URL retornada no lugar de @odata.nextLink após o retorno de todas as alterações atuais. Usada para ler o próximo conjunto de alterações no futuro. |
Exemplos
Exemplo 1: solicitação inicial
Aqui está um exemplo de como chamar essa API para estabelecer seu estado local.
Solicitação
Aqui está um exemplo da solicitação inicial.
GET https://graph.microsoft.com/v1.0/me/drive/root/delta
Resposta
O exemplo a seguir mostra a resposta.
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)"
}
Essa resposta inclui a primeira página de alterações, e a propriedade @odata.nextLink indica que há mais itens disponíveis no conjunto atual de itens. Seu aplicativo deve continuar a solicitar o valor de URL de @odata.nextLink até que todas as páginas de itens tenham sido recuperadas.
Exemplo 2: última página em um conjunto
Aqui está um exemplo de como chamar essa API para atualizar seu estado local.
Solicitação
Aqui está uma solicitação de exemplo após a solicitação inicial.
GET https://graph.microsoft.com/v1.0/me/drive/root/delta(token='MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM3OTQzNzQwODQ3NTcwMDAwOzU4NTk2OTY0NDslMjM7JTIzOyUyMzA')
Resposta
O exemplo a seguir mostra a resposta.
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')"
}
Essa resposta indica que o item denominado folder2
foi excluído e que o item file.txt
foi adicionado ou modificado entre a solicitação inicial e essa solicitação para atualizar o estado local.
A página final dos itens inclui a propriedade @odata.deltaLink , que fornece a URL que pode ser usada posteriormente para recuperar alterações desde o conjunto atual de itens.
Pode haver casos em que o serviço não pode fornecer uma lista de alterações para um determinado token (por exemplo, se um cliente tentar reutilizar um token antigo depois de ter permanecido desconectado por um longo período, ou se o estado do servidor tiver mudado e um novo token for obrigatório).
Nesses casos, o serviço retorna um HTTP 410 Gone
erro com uma resposta de erro contendo um dos códigos de erro abaixo e um Location
cabeçalho contendo um novo nextLink que inicia uma nova enumeração delta do zero.
Depois de concluir a enumeração completa, compare os itens retornados com seu estado local e siga estas instruções.
Tipo de erro | Instruções |
---|---|
resyncChangesApplyDifferences |
Substitua todos os itens locais pela versão do servidor (incluindo exclusões) se você tiver certeza de que o serviço estava atualizado com suas alterações locais quando você sincronizado pela última vez. Carregar alterações locais que o servidor não conhece. |
resyncChangesUploadDifferences |
Carregue todos os itens locais que o serviço não retornou e carregue todos os arquivos que diferem da versão do servidor (mantendo ambas as cópias se você não tiver certeza de qual está mais atualizado). |
Exemplo 3: recuperando o deltaLink atual
Em alguns cenários, pode ser útil solicitar o valor do deltaLink atual sem primeiro enumerar todos os itens que já estão na unidade.
Isso poderá ser útil se o seu aplicativo quiser saber apenas sobre as alterações, e não quiser saber sobre os itens existentes.
Para recuperar o deltaLink mais recente, chame delta
com um parâmetro de cadeia de caracteres de consulta ?token=latest
.
Observação: se estiver tentando manter uma representação local completa dos itens em uma pasta ou unidade, você deve usar
delta
para a enumeração inicial. Outras abordagens, como percorrer a coleçãochildren
de uma pasta, não têm garantia de retornar todos os itens se alguma gravação ocorrer durante a enumeração. Usar odelta
é a única maneira de garantir que você leu todos os dados de que precisa.
Solicitação
GET /me/drive/root/delta?token=latest
Resposta
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [ ],
"@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?token=1230919asd190410jlka"
}
Exemplo 4: recuperando resultados delta usando um carimbo de data/hora
Em alguns cenários, o cliente pode saber o estado de uma unidade até um momento específico, mas não tem um deltaLink para esse momento. Nesse caso, o cliente pode chamar delta
usando um carimbo de data/hora codificado por URL para o valor do parâmetro de cadeia de caracteres de token
consulta, por exemplo, ?token=2021-09-29T20%3A00%3A00Z
ou '?token=2021-09-29T12%3A00%3A00%2B8%3A00'.
O uso de um carimbo de data/hora no lugar de um token é compatível apenas com OneDrive for Business e Microsoft Office SharePoint Online.
Observação: Os clientes devem usar o deltaLink fornecido por
delta
consultas quando possível, em vez de gerar seu próprio token. Esse recurso só deve ser utilizado quando o deltaLink não for conhecido.
Solicitação
GET /me/drive/root/delta?token=2021-09-29T20%3A00%3A00Z
Resposta
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')"
}
Comentários
O feed delta mostra o estado mais recente de cada item, e não cada alteração. Se um item tiver sido renomeado duas vezes, ele só aparecerá uma vez, com seu nome mais recente.
O mesmo item pode aparecer mais de uma vez em um feed delta, por vários motivos. Você deve usar a última ocorrência que visualizar.
A
parentReference
propriedade em itens não incluirá um valor para o caminho. Isso ocorre porque renomear uma pasta não resulta em nenhum descendente da pasta sendo retornado do delta. Ao usar delta, você sempre deve controlar itens por id.A consulta Delta não retornará algumas propriedades do DriveItem, dependendo da operação e do tipo de serviço, conforme mostrado nas tabelas a seguir.
OneDrive for Business
Tipo de operação Propriedades omitidas pela consulta delta Criar/Modificar ctag
Excluir ctag
,name
OneDrive (consumidor)
Tipo de operação Propriedades omitidas pela consulta delta Criar/Modificar n/d Excluir ctag
,size
Hierarquias de permissões de verificação
Por padrão, a resposta de consulta delta inclui o compartilhamento de informações para todos os itens na consulta que foram alterados mesmo que herdem suas permissões de seus pais e não tenham alterações diretas de compartilhamento por conta própria. Normalmente, isso resulta em uma chamada de acompanhamento para obter os detalhes de permissão para cada item, em vez de apenas os cujas informações de compartilhamento foram alteradas. Você pode otimizar sua compreensão de como as alterações de permissão acontecem adicionando o cabeçalho Prefer: hierarchicalsharing
à sua solicitação de consulta delta.
Quando o cabeçalho é fornecido, o Prefer: hierarchicalsharing
compartilhamento de informações é retornado para a raiz da hierarquia de permissões e itens que têm alterações de compartilhamento explicitamente. Nos casos em que a alteração de compartilhamento é remover o compartilhamento de um item, você encontrará uma faceta de compartilhamento vazia para diferenciar os itens que herdam de seus pais e aqueles que são exclusivos, mas não têm links de compartilhamento. Você também verá essa faceta de compartilhamento vazia na raiz de uma hierarquia de permissão que não é compartilhada para estabelecer o escopo inicial.
Em muitos cenários de verificação, você pode estar interessado, especificamente, em alterações nas permissões. Para deixar claro na resposta da consulta delta quais alterações são resultados de alterações nas permissões, você pode fornecer o cabeçalho Prefer: deltashowsharingchanges
. Quando esse cabeçalho é fornecido, todos os itens que aparecem na resposta de consulta delta devido a alterações de permissão têm a @microsoft.graph.sharedChanged":"True"
anotação OData. Esse recurso é aplicável ao SharePoint e ao OneDrive for Business, mas não às contas de consumidor do OneDrive.
Observação
O uso do
Prefer: deltashowsharingchanges
cabeçalho exige que você usePrefer: deltashowremovedasdeleted
ePrefer: deltatraversepermissiongaps
. Esses valores de cabeçalho podem ser agrupados em um único cabeçalho:Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges
.Para processar as permissões corretamente, seu aplicativo precisará solicitar permissões Sites.FullControl.All .
Para obter mais informações sobre cenários de verificação, confira Melhores práticas para descobrir arquivos e detectar alterações em escala.
Respostas de erros
Além dos erros de ressincronização detalhados acima, confira os detalhes sobre como os erros são retornados em Respostas de Erros.
Conteúdo relacionado
Usar a consulta delta para acompanhar as alterações nos dados do Microsoft GraphPráticas recomendadas para descobrir arquivos e detectar alterações em escala
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de