driveItem: delta
Namespace: microsoft.graph
Importante
As APIs na versão /beta
no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.
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 um @odata.deltaLink
.
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.
Depois de concluir o recebimento de todas as alterações, você poderá 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ê só deve excluir uma pasta localmente se ela estiver vazia depois de sincronizar 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. Se um token delta anterior retornar um novo estado desde esse 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. |
deltaExcludeParent | Cadeia de caracteres. Se esse cabeçalho de solicitação for incluído, a resposta inclui os itens que foram alterados e não os itens pai na hierarquia. |
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 inclui 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 em vez de @odata.nextLink depois que todas as alterações atuais forem retornadas. 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/beta/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 solicitando o valor de URL de @odata.nextLink até que todas as páginas de itens sejam recuperadas.
Exemplo 2: última página em um conjunto
O exemplo a seguir mostra como chamar essa API para atualizar seu estado local.
Solicitação
O exemplo a seguir mostra uma solicitação após a solicitação inicial.
GET https://graph.microsoft.com/beta/me/drive/root/delta(token='1230919asd190410jlka')
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='1230919asd190410jlka')"
}
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 ser desconectado por um longo tempo ou se o estado do servidor for alterado e um novo token for necessário).
Nesses casos, o serviço retorna um HTTP 410 Gone
erro com uma resposta de erro contendo códigos de erro 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.
Pode ser útil se seu aplicativo quiser saber apenas sobre alterações e não precisar saber sobre 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
O exemplo a seguir mostra uma solicitação.
GET /me/drive/root/delta?token=latest
Resposta
O exemplo a seguir mostra a 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
O exemplo a seguir mostra uma solicitação.
GET /me/drive/root/delta?token=2021-09-29T20%3A00%3A00Z
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='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 inclui 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 acompanhar itens por ID.A consulta Delta não retorna 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 os que são exclusivos, mas não têm links de compartilhamento. Você também pode 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, confira Respostas de erro para obter detalhes sobre como os erros são retornados.
Conteúdo relacionado
Usar a consulta delta para controlar alterações nos dados do Microsoft Graph. Prá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