Partilhar via


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 permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
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

Este método suporta os $selectparâmetros de consulta , $expande $topOData 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 este cabeçalho do pedido estiver incluído, a resposta inclui os itens que foram alterados e não os itens principais 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 incluirá uma das seguintes propriedades:

Nome Valor Descrição
@odata.nextLink url Um URL para obter a página de alterações seguinte disponível, se existirem 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

Eis um exemplo de como chamar esta API para estabelecer o seu estado local.

Solicitação

Eis um exemplo do pedido 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

Eis um exemplo de como chamar esta API para atualizar o seu estado local.

Solicitação

Eis um pedido de exemplo após o pedido 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 última página de itens inclui a propriedade @odata.deltaLink , que fornece o URL que pode ser utilizado mais tarde para obter 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). Nestes casos, o serviço devolve um HTTP 410 Gone erro com uma resposta de erro que contém um dos códigos de erro abaixo e um Location cabeçalho que contém uma nova 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 quaisquer itens locais pela versão do servidor (incluindo eliminações) se tiver a certeza de que o serviço estava atualizado com as alterações locais da última vez que sincronizou. Carregar alterações locais que o servidor não conhece.
resyncChangesUploadDifferences Carregue quaisquer itens locais que o serviço não tenha devolvido e carregue quaisquer ficheiros que sejam diferentes da versão do servidor (mantendo ambas as cópias se não tiver a certeza de qual delas está mais atualizada).

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ção children de uma pasta, não têm garantia de retornar todos os itens se alguma gravação ocorrer durante a enumeração. Usar o delta é 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. Neste caso, o cliente pode chamar delta com um carimbo de data/hora codificado por URL para o valor do parâmetro da token cadeia de 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 caminho. Isto ocorre porque mudar o nome de uma pasta não resulta na devolução de descendentes da pasta do delta. Ao usar delta, você sempre deve controlar itens por id.

  • A consulta Delta não devolverá algumas propriedades do DriveItem, consoante a operação e o tipo de serviço, conforme mostrado nas tabelas seguintes.

    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 predefinição, a resposta da consulta delta inclui a partilha de informações para todos os itens na consulta que foram alterados, mesmo que herdem as respetivas permissões do encarregado de educação e não tenham feito alterações diretas à partilha. Normalmente, isto resulta numa chamada de seguimento para obter os detalhes de permissão de cada item, em vez de apenas aqueles cujas informações de partilha 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 Prefer: hierarchicalsharing cabeçalho é fornecido, as informações de partilha são devolvidas para a raiz da hierarquia de permissões e itens que têm explicitamente alterações de partilha. Nos casos em que a alteração de partilha é para remover a partilha de um item, encontra uma faceta de partilha vazia para diferenciar entre os itens que herdam do respetivo elemento principal e os que são exclusivos, mas que não têm ligações de partilha. Também verá esta faceta de partilha vazia na raiz de uma hierarquia de permissões que não é partilhada para estabelecer o âmbito 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 este cabeçalho é fornecido, todos os itens que aparecem na resposta da 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

  • A utilização do Prefer: deltashowsharingchanges cabeçalho requer que utilize Prefer: deltashowremovedasdeleted e Prefer: deltatraversepermissiongaps. Esses valores de cabeçalho podem ser agrupados em um único cabeçalho: Prefer: deltashowremovedasdeleted, deltatraversepermissiongaps, deltashowsharingchanges.

  • Para processar as permissões corretamente, a sua aplicação terá de pedir permissões Sites.FullControl.All .

Para obter mais informações sobre cenários de análise, veja Melhores práticas para detetar ficheiros e detetar 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.

Utilizar a consulta delta para registar alterações nos dados do Microsoft GraphMelhores práticas para detetar ficheiros e detetar alterações em escala