Usar a consulta delta para controlar alterações nos dados do Microsoft Graph

  • Artigo

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.

Usar solicitação delta para rastrear alterações em uma coleção resource

O padrão típico de chamada corresponde ao que segue:

  1. 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.deltacompletamente qualificado . Os pedidos gerados pelos SDKs do Microsoft Graph utilizam o nome completamente qualificado.

  2. 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.

    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.

  3. 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.

  4. 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 ID do Microsoft Entra (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ção delta, 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 exigem token=latest .
  • $select E $deltaLink os parâmetros de consulta são suportados para alguns recursos do Microsoft Entra 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.

Tokens de estado

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 $skiptokene 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.

Parâmetros de consulta opcionais

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'

Representação de recurso na resposta da consulta delta

  • 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 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 ser changed ou deleted.

    • 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.

      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.

  • 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.

Recursos com suporte

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 no estado de pré-visualização, conforme indicado.

Nota: a função delta para recursos marcados com um asterisco (*) só está disponível no /beta ponto final.

Coleção de recursos API
application aplicação: função delta
administrativeUnit administrativeUnit: função delta
callRecording callRecording: função delta
callTranscript callTranscript: função delta
chatMessage chatMessage: função delta
device device: função delta
directoryRole directoryRole: função delta
directoryObject directoryObject: função delta
driveItem1 driveItem: função delta
educationAssignment educationAssignment: função delta
educationCategory educationCategory: função delta
educationClass educationClass: função delta
educationSchool educationSchool: função delta
educationUser educationUser: função delta
event evento: função delta
group grupo: função delta
listItem1 listItem: função delta
mailFolder mailFolder: função delta
message mensagem: função delta
orgContact orgContact: função delta
oAuth2PermissionGrant oAuth2PermissionGrant: função delta
contactFolder contactFolder: função delta
contactar recurso contacto: função delta
plannerBucket * plannerBucket: função delta
plannerUser2 plannerUser: função delta
sites função delta do recurso do site
servicePrincipal servicePrincipal: função delta
todoTask todoTask: função delta
todoTaskList todoTaskList: função delta
user utilizador: função delta

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 dos recursos do Planner é semelhante a outros recursos suportados com algumas diferenças. Para obter mais informações, consulte Planner: delta.

Nuvens nacionais

As consultas Delta para recursos suportados estão disponíveis para clientes alojados na cloud pública, Microsoft Cloud para US Government e Microsoft Cloud China operado pela 21Vianet.

Limitações

As alterações às propriedades armazenadas fora do arquivo de dados principal não são registadas

Alguns recursos contêm propriedades armazenadas fora do arquivo de dados principal do recurso. Por exemplo, os dados de recursos do utilizador são armazenados principalmente no ID do Microsoft Entra, mas algumas das respetivas propriedades, como competências, são armazenadas no SharePoint Online. Atualmente, apenas as propriedades armazenadas no arquivo de dados principal acionam alterações na consulta delta; as propriedades armazenadas fora do arquivo de dados principal 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 principal, veja a documentação de utilizadores e grupos .

Atrasos de processamento

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.

Repetições

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.

Sincronização redefinida

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). Normalmente, este estado 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.

Duração do token

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.

Combinar consultas delta e alterar notificações

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.

Conteúdo relacionado

Saiba mais sobre a consulta delta nos seguintes tutoriais: