Partilhar via


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, devolvendo 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 terminar de receber todas as alterações, 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.

Nota: só deve eliminar uma pasta localmente se estiver vazia depois de sincronizar 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. Se um token delta anterior devolver um novo estado desde esse 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 inclui 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 Um URL devolvido em vez de @odata.nextLink depois de todas as alterações atuais serem devolvidas. 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/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. A sua aplicação deve continuar a pedir o valor de URL de @odata.nextLink até que todas as páginas de itens sejam obtidas.

Exemplo 2: última página em um conjunto

O exemplo seguinte mostra como chamar esta API para atualizar o seu estado local.

Solicitação

O exemplo seguinte mostra um pedido após o pedido 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 ú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.

Podem existir casos em que o serviço não consegue fornecer uma lista de alterações para um determinado token (por exemplo, se um cliente tentar reutilizar um token antigo depois de ter sido desligado durante muito tempo ou se o estado do servidor tiver sido alterado e for necessário um novo token). Nestes casos, o serviço devolve um HTTP 410 Gone erro com uma resposta de erro que contém códigos de erro 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.

Pode ser útil se a sua aplicação apenas quiser saber sobre as alterações e não precisar de saber mais 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

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

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 caminho. Ocorre porque mudar o nome de uma pasta não resulta na devolução de descendentes da pasta do delta. Ao utilizar o delta, deve sempre controlar os itens por ID.

  • A consulta Delta não devolve 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, 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 pode 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

Para além dos erros de ressincronização detalhados, veja Respostas de erro para obter detalhes sobre como os erros são devolvidos.

Usar a consulta delta para controlar alterações nos dados do Microsoft Graph. Melhores práticas para detetar ficheiros e detetar alterações em escala.