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 $select
parâmetros de consulta ,$expand
e $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"
}
Exemplo 3: pedido de ligação Delta
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=latest
de 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"
}