Controlar alterações para uma unidade

  • Artigo

Esse método permite que o seu aplicativo controle alterações em uma unidade e seus filhos com o passar 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

Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All
Delegado (conta pessoal da Microsoft) Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All
Aplicativo 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 consulta opcionais

Este método suporta os $selectparâmetros de consulta , $expande $topOData para personalizar a resposta.

Parâmetros

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

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 alterações adicionais 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.

Exemplo (solicitação inicial)

Veja a seguir um exemplo de como chamar essa API para estabelecer seu estado local.

Solicitação

Veja a seguir um exemplo da solicitação inicial.

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

Resposta

Veja a seguir um exemplo da 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 (última página de um conjunto)

Veja a seguir um exemplo de como chamar essa API para atualizar seu estado local.

Solicitação

Veja a seguir um exemplo da solicitação após a solicitação inicial.

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

Resposta

Veja a seguir um exemplo da 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 de itens incluirá a propriedade @odata.deltaLink, que fornece a URL que poderá 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 retornará um erro HTTP 410 Gone com uma resposta de erro contendo um dos códigos de erro abaixo e um cabeçalho Location contendo um novo nextLink que inicia uma 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ê sincronizou pela última vez. Carregue alterações locais que o servidor não conhece.
resyncChangesUploadDifferences Carregue os itens locais que o serviço não retornou e carregue os arquivos que diferem da versão do servidor (mantendo ambas as cópias se você não tiver certeza de qual é a mais 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çã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"
}

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 propriedade parentReference em itens não incluirá um valor para path. Isso ocorre porque a renomeação de uma pasta não faz com que os descendentes dessa pasta sejam retornados de delta. Ao usar delta, você sempre deve controlar itens por id.

  • Para pastas compartilhadas adicionadas a uma unidade, o delta não retornará nenhuma informação sobre as alterações dentro da pasta compartilhada. Em vez disso, deve ser feita outra chamada delta que segmente a própria pasta compartilhada.

  • A Delta tem restrições adicionais para o Microsoft OneDrive for Business; consulte as notas de lançamento para obter detalhes.

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.