Usar a consulta delta para controlar alterações nos dados do Microsoft Graph
A consulta Delta, também denominada controlo de alterações, permite que as aplicações descubram entidades recentemente criadas, atualizadas ou eliminadas sem efetuar uma leitura completa do recurso de destino a cada pedido. Os aplicativos do Microsoft Graph podem usar consulta delta para sincronizar, com eficiência, alterações com armazenamento de dados local.
A utilização da consulta delta ajuda-o a evitar consultar constantemente o Microsoft Graph, uma vez que a aplicação pede apenas os dados que foram alterados desde o último pedido. Este padrão permite que a aplicação reduza a quantidade de dados pedidos, reduzindo assim o custo do pedido e, como tal, limite provavelmente as hipóteses de limitação dos pedidos.
O padrão típico de chamada corresponde ao que segue:
A aplicação faz um pedido GET com a função delta no recurso pretendido. Por exemplo,
GET https://graph.microsoft.com/v1.0/users/delta
.Dica
/delta
é um atalho para o nome/microsoft.graph.delta
completamente qualificado . Os pedidos gerados pelos SDKs do Microsoft Graph utilizam o nome completamente qualificado.O Microsoft Graph responde com o recurso pedido e um token de estado.
a. Se o Microsoft Graph devolver um
@odata.nextLink
URL, existem mais páginas de dados a obter na sessão, mesmo que a resposta atual contenha um resultado vazio. A aplicação utiliza o@odata.nextLink
URL para continuar a fazer pedidos para obter todas as páginas de dados até que o Microsoft Graph devolva um@odata.deltaLink
URL na resposta.b. Se o Microsoft Graph devolver um
@odata.deltaLink
URL, não existem mais dados sobre o estado existente do recurso a devolver na sessão atual. Em solicitações futuras, o aplicativo usa a URL@odata.deltaLink
para inteirar-se das alterações feitas no recurso.c. Uma página não pode conter e
@odata.deltaLink
@odata.nextLink
.Observação
A resposta do Microsoft Graph no Passo 2 inclui os recursos que existem atualmente na coleção. Os recursos que foram eliminados antes da consulta delta inicial não são devolvidos. As atualizações feitas antes da solicitação inicial são resumidas no recurso retornado como seu estado mais recente.
Quando a aplicação precisa de saber mais sobre as alterações ao recurso, utiliza o
@odata.deltaLink
URL que recebeu no passo 2 para fazer pedidos. A aplicação pode fazer este pedido imediatamente após concluir o passo 2 ou quando verifica a existência de alterações.O Microsoft Graph retorna uma resposta, descrevendo alterações no recurso desde a solicitação anterior e em uma URL
@odata.nextLink
ou uma URL@odata.deltaLink
.
Observação
- Os recursos armazenados no Microsoft Entra ID (como utilizadores e grupos) suportam cenários de "sincronização a partir de agora". Isso permite que você ignore as etapas 1 e 2 acima (se você não está interessado em recuperar o estado completo do recurso) e peça para conferir o último
@odata.deltaLink
em vez disso. Acrescente$deltatoken=latest
à funçãodelta
, e a resposta conterá um@odata.deltaLink
e nenhum dado do recurso. Os recursos no OneDrive e no SharePoint também suportam esta funcionalidade, mas exigemtoken=latest
. -
$select
E$deltaLink
os parâmetros de consulta são suportados para alguns Microsoft Entra recursos para que os clientes possam alterar as propriedades que pretendem controlar para um existente@odata.deltaLink
. As consultas Delta com e$select
$skiptoken
não são suportadas.
Um GET de consulta delta sempre inclui uma URL especificada em um cabeçalho de resposta @odata.nextLink
ou @odata.deltaLink
.
O @odata.nextLink
URL inclui um $skiptoken
e um @odata.deltaLink
URL inclui um $deltatoken
.
Estes tokens são opacos para a aplicação cliente, mas são importantes da seguinte forma:
- Cada token reflete o estado e representa um instantâneo do recurso dessa fase do controle de alterações.
- Os tokens de estado codificam e incluem parâmetros de consulta (como
$select
) especificados no pedido de consulta delta inicial. Por conseguinte, não modifique os pedidos de consulta delta subsequentes para repetir estes parâmetros de consulta. - Ao realizar a consulta delta, você pode copiar e aplicar a URL
@odata.nextLink
ou@odata.deltaLink
à próxima chamada de função delta sem precisar inspecionar o conteúdo da URL, incluindo seu token de estado.
Se um cliente utilizar um parâmetro de consulta, tem de ser especificado no pedido inicial. O Microsoft Graph codifica automaticamente o parâmetro de consulta especificado no @odata.nextLink
ou @odata.deltaLink
na resposta e em todos os URLs ou @odata.deltaLink
subsequentes@odata.nextLink
.
Observe o suporte geral limitado dos seguintes parâmetros de consulta opcionais:
$orderby
Não assuma uma sequência específica das respostas devolvidas a partir de uma consulta delta. Suponha que o mesmo item possa aparecer em qualquer lugar na sequência do
@odata.nextLink
e leve isso em conta em sua lógica de mesclagem.$top
O número de objetos em cada página pode variar dependendo do tipo de recurso e do tipo de alterações feitas no recurso.
Para obter o recursomensagem, consulte os detalhes do suporte aos parâmetros de consulta em uma consulta delta.
Para os recursos de usuário e grupo, há restrições no uso de alguns parâmetros de consulta:
$expand
não é compatível.$top
não é compatível.$orderby
não é compatível.Se for utilizado um
$select
parâmetro de consulta, o parâmetro indica que o cliente prefere apenas registar alterações nas propriedades ou relações especificadas na$select
instrução . Se ocorrer uma alteração numa propriedade que não está selecionada, o recurso para o qual essa propriedade foi alterada não aparecerá na resposta delta após um pedido subsequente.$select
também suporta às propriedades de navegação do gerente e membros para usuários e grupos, respectivamente. A seleção dessas propriedades permite controlar as alterações feitas no gerenciador de usuário e nas associações de grupo.Os filtros de âmbito permitem-lhe registar alterações a um ou mais utilizadores ou grupos específicos, filtrando apenas por ID de objeto. Por exemplo, a solicitação a seguir retorna alterações para os grupos que correspondem às IDs especificadas no filtro de consulta.
https://graph.microsoft.com/beta/groups/delta/?$filter=id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e'
Instâncias de um recurso recém-criadas de um recurso para o qual há suporte são representadas na resposta da consulta delta usando sua representação-padrão.
As instâncias atualizadas são representadas pelo respetivo ID com , pelo menos , as propriedades atualizadas, mas outras propriedades podem ser incluídas.
As relações entre utilizadores e grupos são representadas como anotações na representação de recursos padrão. Estas anotações utilizam o formato propertyName@delta. As anotações estão incluídas na resposta do pedido de consulta delta inicial.
- As alterações às relações armazenadas fora do arquivo de dados main não são suportadas como parte do controlo de alterações. Para obter mais informações, veja Alterações às propriedades armazenadas fora do arquivo de dados main não são controladas.
As instâncias removidas são representadas pelo respetivo ID e um objeto @removed . O objeto @removed pode incluir informações adicionais sobre o motivo pelo qual a instância foi removida. Por exemplo,
"@removed": {"reason": "changed"}
. Os possíveis motivos de ser @removido podem serchanged
oudeleted
.changed
indica que o item foi excluído e poderá ser restaurado de deletedItems.deleted
indica que o item foi eliminado e não pode ser restaurado.- Os itens eliminados do arquivo deletedItems também são apresentados como
deleted
.
O objeto @removed pode ser devolvido na resposta inicial da consulta delta e nas respostas controladas (
@odata.nextLink
). Por exemplo, um objeto de diretório eliminado que ainda pode ser restaurado a partir de itens eliminados aparece como"@removed": {"reason": "changed"}
. Os clientes que utilizam pedidos de consulta delta devem ser concebidos para processar estes objetos nas respostas.- Os itens eliminados do arquivo deletedItems também são apresentados como
As instâncias restauradas a partir de deletedItems são apresentadas como instâncias recentemente criadas na resposta da consulta delta.
Observação
Uma única entidade pode ser contida várias vezes na resposta, se essa entidade tiver sido alterada várias vezes e em determinadas condições. As consultas Delta permitem aos aplicativos listar todas as alterações, mas não garantem que as entidades sejam unificadas em uma única resposta.
A consulta delta é compatível atualmente com os seguintes recursos. Alguns recursos que estão disponíveis na v1.0 têm as funções delta correspondentes ainda em pré-visualização status, conforme indicado.
Nota: a função delta para recursos marcados com um asterisco (*) só está disponível no
/beta
ponto final.
Observação
1 O padrão de utilização dos recursos do OneDrive e do SharePoint é semelhante aos outros recursos suportados com algumas pequenas diferenças de sintaxe. Para obter mais informações sobre a sintaxe atual, veja driveItem: delta e listItem: delta.
2 O padrão de utilização para Planner recursos é semelhante a outros recursos suportados com algumas diferenças. Para obter mais informações, consulte Planner: delta.
As consultas Delta para recursos suportados estão disponíveis para clientes alojados na cloud pública, Microsoft Cloud for US Government e Microsoft Cloud China operados pela 21Vianet.
Alguns recursos contêm propriedades armazenadas fora do arquivo de dados main do recurso. Por exemplo, os dados de recursos do utilizador são armazenados principalmente em Microsoft Entra ID, mas algumas das suas propriedades, como competências, são armazenadas no SharePoint Online. Atualmente, apenas as propriedades armazenadas no arquivo de dados main acionam alterações na consulta delta; as propriedades armazenadas fora do arquivo de dados main não são suportadas como parte do controlo de alterações. Por conseguinte, uma alteração a qualquer uma destas propriedades não resulta na apresentação de um objeto na resposta da consulta delta.
Para obter mais informações sobre as propriedades armazenadas fora do arquivo de dados main, veja a documentação de utilizadores e grupos.
Espere atrasos variados entre o momento em que uma instância de recurso é alterada e o tempo em que a alteração registada é refletida numa resposta de consulta delta.
Por vezes, devido a atrasos de replicação, as alterações ao objeto podem não aparecer imediatamente quando seleciona o @odata.nextLink
ou o @odata.deltaLink
. Repita @odata.nextLink
ou @odata.deltaLink
depois de algum tempo para recuperar as alterações mais recentes.
O aplicativo deve estar preparado para repetições, que ocorrem quando a mesma alteração aparece nas respostas subsequentes. Embora a consulta delta faça o melhor esforço para reduzir as repetições, estas continuam a ser possíveis.
A consulta Delta pode retornar um código de resposta de 410 Gone
e um cabeçalho de Localização contendo um URL de solicitação com um $deltatoken
vazio (o mesmo que a consulta inicial). Este status geralmente impede a inconsistência de dados devido à manutenção interna ou migração do inquilino de destino e é uma indicação de que a aplicação tem de ser reiniciada com uma sincronização completa do inquilino de destino.
Os tokens Delta só são válidos para um período específico, antes que o aplicativo cliente precise executar uma sincronização total novamente.
- Para objetos de diretório, o limite é de sete dias.
- Para objetos educacionais (educationSchool, educationUser e educationClass), o limite é de sete dias.
- Para entidades do Outlook (mensagem, mailFolder, evento, contacto, contactFolder, todoTask e todoTaskList), o limite superior não é fixo; depende do tamanho da cache de token delta interna. Enquanto os novos tokens delta são adicionados ao cache, após a capacidade do cache ser excedida, os tokens delta mais antigos são excluídos.
Caso o token expire, o serviço deve responder com um erro da série 40X com códigos de erro como syncStateNotFound
. Para obter mais informações, consulte Códigos de erro no Microsoft Graph.
Uma aplicação pode utilizar notificações de alteração do Microsoft Graph para subscrever a notificação quando um recurso específico é alterado. Assim, o aplicativo poderá usar a consulta delta para solicitar todas as alterações desde a última vez que fez a solicitação.
As aplicações podem utilizar esta estratégia para quase eliminar (apenas para recursos suportados) a necessidade de consultar frequentemente o Microsoft Graph e processar essas alterações para manter um arquivo de dados local sincronizado, reduzindo consideravelmente as possibilidades de limitação dos pedidos.
Saiba mais sobre a consulta delta nos seguintes tutoriais: