Compartilhar via


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

Obtenha itens de lista recentemente criados, atualizados ou eliminados sem ter de efetuar uma leitura completa de toda a coleção de itens.

Seu aplicativo começa chamando delta sem parâmetros. O serviço começa a enumerar a hierarquia da lista, a devolver páginas de itens e um @odata.nextLink ou um @odata.deltaLink. A sua aplicação deve continuar a chamar com o @odata.nextLink até ver uma @odata.deltaLink devolvida.

Depois de receber todas as alterações, pode aplicá-las ao seu estado local. Para verificar a existência de alterações no futuro, volte a ligar delta com o @odata.deltaLink da resposta anterior.

O feed delta mostra o estado mais recente de cada item, e não cada alteração. Se o nome de um item tiver sido mudado duas vezes, só será apresentado uma vez, com o nome mais recente. O mesmo item pode aparecer mais do que uma vez num feed delta, por vários motivos. Você deve usar a última ocorrência que visualizar.

Os itens eliminados são devolvidos com a faceta eliminada . Deleted indica que o item foi eliminado e não pode ser restaurado. Os itens com esta propriedade devem ser removidos do seu estado local.

Nota: Só deve eliminar uma pasta localmente se estiver vazia depois de sincronizar todas as alterações.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global US Government L4 US Government L5 (DOD) China operada pela 21Vianet

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) Sites.Read.All Sites.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Aplicativo Sites.Read.All Sites.ReadWrite.All

Solicitação HTTP

GET /sites/{siteId}/lists/{listId}/items/delta

Parâmetros de consulta

No URL do pedido, pode incluir o seguinte parâmetro de consulta opcional.

Parâmetro Tipo Descrição
token Cadeia de caracteres Se não for especificado, enumera o estado atual da hierarquia. Se latest, devolve uma resposta vazia com o token delta mais recente. Se um token delta anterior, devolve um novo estado desde esse token.

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

Cabeçalhos de solicitação

Cabeçalho Valor
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 objetos listItem no corpo da resposta.

Além de uma coleção de objetos listItem , 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 Uma URL retornada no lugar de @odata.nextLink após o retorno de todas as alterações atuais. Utilize esta propriedade para ler o próximo conjunto de alterações no futuro.

Em alguns casos, o serviço devolve um 410 Gone código de resposta com uma resposta de erro que contém um dos seguintes códigos de erro e um Location cabeçalho que contém um novo nextLink que inicia uma nova enumeração delta. Isto ocorre quando 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.

Depois de concluída a enumeração completa, compare os itens devolvidos com o estado local e siga as instruções com base no tipo de erro.

Tipo de erro Instruções
resyncChangesApplyDifferences Substitua quaisquer itens locais pelas versões 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 itens que diferem das versões do servidor. Guarde ambas as cópias se não tiver a certeza de qual delas está mais atualizada.

Para além dos erros de ressincronização e para obter mais detalhes sobre a forma como os erros são devolvidos, veja Respostas de erro e tipos de recursos do Microsoft Graph.

Exemplos

Exemplo 1: solicitação inicial

O exemplo seguinte mostra um pedido inicial e como chamar esta API para estabelecer o seu estado local.

Solicitação

O exemplo seguinte mostra um pedido inicial.

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta

Resposta

O exemplo seguinte mostra a resposta que inclui a primeira página de alterações e a propriedade @odata.nextLink que indica que não existem 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.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
      "id": "1",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "1",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Folder"
      }
    },
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC067},756\"",
      "id": "2",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemA.txt",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "2",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      }
    },
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC068},756\"",
      "id": "3",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemB.txt",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "3",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      }
    }
  ],
  "@odata.nextLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

Exemplo 2: pedido da última página

O exemplo seguinte mostra um pedido que obtém a última página num conjunto e como chamar esta API para atualizar o estado local.

Solicitação

O exemplo seguinte mostra um pedido após o pedido inicial.

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka

Resposta

O exemplo seguinte mostra a resposta que indica que o item com o nome TestItemB.txt foi eliminado e que o item TestFolder foi adicionado ou modificado entre o pedido inicial e este pedido 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.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
      "id": "1",
      "lastModifiedDateTime": "2016-03-21T20:01:37Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "1",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Folder"
      }
    },
    {
      "id": "3",
      "parentReference": {
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      },
      "deleted": {
        "state": "deleted"
      }
    }
  ],
  "@odata.deltaLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

Em alguns cenários, poderá querer pedir o valor atual deltaLink sem enumerar primeiro todos os itens na lista. Isto 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 obter o mais recente deltaLink, chame delta com o parâmetro ?token=latestde cadeia de consulta .

Solicitação

O exemplo a seguir mostra uma solicitação.

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/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/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}