listItem: delta

  • Artigo

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 recém-criados, atualizados ou excluídos sem precisar executar 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, retornando páginas de itens e um @odata.nextLink ou um @odata.deltaLink. Seu aplicativo deve continuar chamando com o @odata.nextLink até ver um @odata.deltaLink retornado.

Depois de receber todas as alterações, você poderá aplicá-las ao seu estado local. Para marcar para alterações no futuro, chame delta novamente 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 um item foi 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.

Os itens excluídos são retornados com a faceta excluída . Deleted indica que o item é excluído e não pode ser restaurado. Os itens com essa propriedade devem ser removidos do seu estado local.

Nota: Você só deve excluir uma pasta localmente se ela estiver vazia depois de sincronizar todas as alterações.

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global Governo dos EUA L4 GOVERNO DOS EUA L5 (DOD) China operada pela 21Vianet
✅ ✅ ✅ ✅

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

Na URL de solicitação, você pode incluir o seguinte parâmetro de consulta opcional.

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

Esse método também dá suporte aos $selectparâmetros de consulta , $expande $topOData 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 propriedades a seguir.

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 no lugar de @odata.nextLink após o retorno de todas as alterações atuais. Use essa propriedade para ler o próximo conjunto de alterações no futuro.

Em alguns casos, o serviço retorna 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. Isso ocorre quando 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 tiver sido alterado e um novo token for necessário.

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

Tipo de erro Instruções
resyncChangesApplyDifferences Substitua todos os itens locais pelas versões do servidor (incluindo exclusões) se você tiver certeza de que o serviço estava atualizado com suas alterações locais quando você foi 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 quaisquer itens que diferem das versões do servidor. Mantenha as duas cópias se não tiver certeza de qual delas está mais atualizada.

Além dos erros de ressincronização e para obter mais detalhes sobre como os erros são retornados, confira Respostas de erro e tipos de recursos do Microsoft Graph.

Exemplos

Exemplo 1: solicitação inicial

O exemplo a seguir mostra uma solicitação inicial e como chamar essa API para estabelecer seu estado local.

Solicitação

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

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: Última solicitação de página

O exemplo a seguir mostra uma solicitação que obtém a última página em um conjunto e 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/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 a seguir mostra a resposta que indica que o item nomeado TestItemB.txt foi excluído e o item TestFolder 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.

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, talvez você queira solicitar o valor atual deltaLink sem enumerar primeiro todos os itens da lista. Isso pode ser útil se seu aplicativo quiser saber apenas sobre alterações e não precisar saber sobre itens existentes. Para recuperar o mais recente deltaLink, chame delta com o parâmetro ?token=latestde cadeia de caracteres 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"
}

Conteúdo relacionado