listItem: delta
Namespace: microsoft.graph
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 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 $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 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/v1.0/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/v1.0/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/v1.0/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/v1.0/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: solicitação de link delta
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=latest
de cadeia de caracteres de consulta .
Solicitação
O exemplo a seguir mostra uma solicitação.
GET https://graph.microsoft.com/v1.0/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/v1.0/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
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de