Share via

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

  • Artigo

A consulta Delta, também chamada de controle de alterações, permite que os aplicativos descubram entidades recém-criadas, atualizadas ou excluídas sem executar uma leitura completa do recurso de destino a cada solicitação. Os aplicativos do Microsoft Graph podem usar consulta delta para sincronizar, com eficiência, alterações com armazenamento de dados local.

O uso de consulta delta ajuda você a evitar sondar constantemente o Microsoft Graph, pois o aplicativo solicita apenas dados que foram alterados desde a última solicitação. Esse padrão permite que o aplicativo reduza a quantidade de dados que solicita, reduzindo assim o custo da solicitação e, como tal, provavelmente limite as chances de as solicitações serem limitadas.

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. O aplicativo faz uma solicitação GET com a função delta no recurso desejado. Por exemplo, GET https://graph.microsoft.com/v1.0/users/delta.

    Dica

    /delta é um atalho para o nome /microsoft.graph.deltatotalmente qualificado . As solicitações geradas pelos SDKs do Microsoft Graph usam o nome totalmente qualificado.

  2. O Microsoft Graph responde com o recurso solicitado e um token de estado.

    a. Se o Microsoft Graph retornar uma @odata.nextLink URL, haverá mais páginas de dados a serem recuperadas na sessão, mesmo que a resposta atual contenha um resultado vazio. O aplicativo usa a @odata.nextLink URL para continuar fazendo solicitações para recuperar todas as páginas de dados até que o Microsoft Graph retorne uma @odata.deltaLink URL na resposta.

    b. Se o Microsoft Graph retornar uma @odata.deltaLink URL, não haverá mais dados sobre o estado existente do recurso a ser retornado 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 na Etapa 2 inclui os recursos existentes atualmente na coleção. Os recursos que foram excluídos antes da consulta delta inicial não são retornados. As atualizações feitas antes da solicitação inicial são resumidas no recurso retornado como seu estado mais recente.

  3. Quando o aplicativo precisa aprender sobre alterações no recurso, ele usa a @odata.deltaLink URL recebida na etapa 2 para fazer solicitações. O aplicativo pode fazer essa solicitação imediatamente após a conclusão da etapa 2 ou quando ele verifica se há 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 em Microsoft Entra ID (como usuários e grupos) dão suporte a 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 dão suporte a esse recurso, mas exigem token=latest .
  • $selecte $deltaLink há suporte para parâmetros de consulta para alguns recursos Microsoft Entra para que os clientes possam alterar as propriedades que desejam rastrear para um existente @odata.deltaLink. Consultas delta com ambos $select e $skiptoken não têm suporte.

Tokens de estado

Um GET de consulta delta sempre inclui uma URL especificada em um cabeçalho de resposta @odata.nextLink ou @odata.deltaLink. A @odata.nextLink URL inclui um $skiptokene uma @odata.deltaLink URL inclui um $deltatoken.

Esses tokens são opacos para o aplicativo cliente, mas importantes da seguinte maneira:

  • 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 na solicitação de consulta delta inicial. Portanto, não modifique as solicitações de consulta delta subsequentes para repetir esses 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 usa um parâmetro de consulta, ele deve ser especificado na solicitação inicial. O Microsoft Graph codifica automaticamente o parâmetro @odata.nextLink de consulta especificado no ou @odata.deltaLink na resposta e em todas as URLs ou @odata.deltaLink subsequentes@odata.nextLink.

Observe o suporte geral limitado dos seguintes parâmetros de consulta opcionais:

  • $orderby

    Não suponha uma sequência específica das respostas retornadas 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 um $select parâmetro de consulta for usado, o parâmetro indica que o cliente prefere apenas acompanhar as alterações nas propriedades ou relações especificadas na $select instrução. Se ocorrer uma alteração em uma propriedade que não está selecionada, o recurso para o qual essa propriedade foi alterada não aparecerá na resposta delta após uma solicitação 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 escopo permitem que você acompanhe as alterações em um ou mais usuários ou grupos específicos, filtrando apenas pela ID do 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 por sua ID com pelo menos as propriedades atualizadas, mas outras propriedades podem ser incluídas.

  • As relações entre usuários e grupos são representadas como anotações na representação de recurso padrão. Essas anotações usam o formato propertyName@delta. As anotações são incluídas na resposta da solicitação de consulta delta inicial.

  • As instâncias removidas são representadas por sua ID e um objeto @removed . O objeto @removed pode incluir informações adicionais sobre por que 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 excluído e não pode ser restaurado.

      O objeto @removed pode ser retornado na resposta de consulta delta inicial e em respostas rastreadas (@odata.nextLink). Por exemplo, um objeto de diretório excluído que ainda pode ser restaurado de itens excluídos aparece como "@removed": {"reason": "changed"}. Os clientes que usam solicitações de consulta delta devem ser projetados para lidar com esses objetos nas respostas.

  • Instâncias restauradas de deletedItems aparecem como instâncias recém-criadas na resposta de consulta delta.

Observação

Uma única entidade pode ser contida várias vezes na resposta, se essa entidade foi 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 disponíveis no v1.0 têm suas funções delta correspondentes ainda em status de visualização, conforme indicado.

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

Coleção de recursos API
application aplicativo: função delta
administrativeUnit administrativeUnit: função delta
callRecording * callRecording: função delta
callTranscript * callTranscript: função delta
chatMessage chatMessage: função delta
device dispositivo: 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
recurso de contato contato: 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 usuário: função delta

Observação

1 O padrão de uso dos recursos do OneDrive e do SharePoint é semelhante aos outros recursos com suporte com algumas pequenas diferenças de sintaxe. Para obter mais informações sobre a sintaxe atual, consulte driveItem: delta e listItem: delta.

2 O padrão de uso para recursos Planner é semelhante a outros recursos com suporte com algumas diferenças. Para obter mais informações, consulte planejador: delta.

Nuvens nacionais

As consultas Delta para recursos com suporte estão disponíveis para clientes hospedados na nuvem pública, Microsoft Cloud for US Government e Microsoft Cloud China operados pela 21Vianet.

Limitações

As alterações nas propriedades armazenadas fora do repositório de dados main não são rastreadas

Alguns recursos contêm propriedades armazenadas fora do armazenamento de dados main para o recurso. Por exemplo, os dados de recurso do usuário são armazenados principalmente em Microsoft Entra ID, mas algumas de suas propriedades, como habilidades, são armazenadas no SharePoint Online. Atualmente, apenas as propriedades armazenadas no armazenamento de dados main disparam alterações na consulta delta; as propriedades armazenadas fora do armazenamento de dados main não têm suporte como parte do controle de alterações. Portanto, uma alteração em qualquer uma dessas propriedades não resulta em um objeto aparecendo na resposta de consulta delta.

Para obter mais informações sobre propriedades armazenadas fora do armazenamento de dados main, consulte a documentação de usuários e grupos.

Atrasos de processamento

Espere atrasos variados entre o tempo em que uma instância de recurso é alterada e a hora em que a alteração rastreada é refletida em uma resposta de consulta delta.

Às vezes, devido a atrasos de replicação, as alterações no objeto podem não aparecer imediatamente quando você selecionar 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 os replays, eles ainda são 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). Esse status geralmente acontece para evitar inconsistência de dados devido à manutenção interna ou migração do locatário de destino e é uma indicação de que o aplicativo deve ser reiniciado com uma sincronização completa do locatário 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, contato, contactFolder, todoTask e todoTaskList), o limite superior não é corrigido; depende do tamanho do cache de token delta interno. 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 notificações de alteração

Um aplicativo pode usar notificações de alteração do Microsoft Graph para assinar para ser notificado quando um recurso específico for alterado. Assim, o aplicativo poderá usar a consulta delta para solicitar todas as alterações desde a última vez que fez a solicitação.

Os aplicativos podem usar essa estratégia para quase eliminar (apenas para recursos com suporte) a necessidade de sondar com frequência o Microsoft Graph e processar essas alterações para manter um armazenamento de dados local em sincronização, reduzindo consideravelmente as chances de suas solicitações serem limitadas.

Conteúdo relacionado

Saiba mais sobre a consulta delta nos seguintes tutoriais: