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

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 com cada solicitação. Os aplicativos do Microsoft Graph podem usar consulta delta para sincronizar, com eficiência, alterações com armazenamento de dados local.

Usar a consulta delta ajuda a evitar pesquisar constantemente o Microsoft Graph, pois o aplicativo solicita somente dados que foram alterados desde a última solicitação. Esse padrão permite que o aplicativo reduza a quantidade de dados solicitados, reduzindo assim o custo da solicitação e, como tal, provavelmente limitará as chances de as solicitações serem limitadas.

A consulta Delta usa um modelo pull , em que o aplicativo solicita alterações do Microsoft Graph; enquanto as notificações de alteração usam um modelo de push , em que o Microsoft Graph notifica o aplicativo sobre alterações.

Importante

Não há suporte para o recurso de controle de alterações na ID externa do Microsoft Entra em locatários externos e locatários do Azure AD B2C.

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.

  1. 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 recuperados 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 serem retornados 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 ambos @odata.deltaLink e @odata.nextLink.

    Observação

    A resposta do Microsoft Graph na Etapa 2 inclui os recursos que existem 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.

  2. Quando o aplicativo precisa saber mais 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 concluir a etapa 2 ou quando verificar se há alterações.

  3. 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 do Microsoft Entra ID, como usuários e grupos, dão suporte a cenários de "sincronização a partir de agora". Esse recurso permite que você ignore as etapas 1 e 2 (se você não estiver interessado em recuperar o estado completo do recurso) e solicite a versão mais recente @odata.deltaLink . Acrescente $deltatoken=latest à delta função e a resposta conterá um @odata.deltaLink e nenhum dado de recurso. Os recursos no OneDrive e no SharePoint também dão suporte a esse recurso, mas exigem token=latest em vez disso.
  • $selecte $deltaLink parâmetros de consulta são compatíveis com alguns recursos do Microsoft Entra para que os clientes possam alterar as propriedades que desejam acompanhar para um arquivo .@odata.deltaLink As 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 $skiptoken, e 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 usar um parâmetro de consulta, ele deverá ser especificado na solicitação inicial. O Microsoft Graph codifica automaticamente o parâmetro de consulta especificado na @odata.nextLink resposta ou @odata.deltaLink na resposta e em todas as URLs subsequentes @odata.nextLink ou @odata.deltaLink .

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

  • $orderby

    Não presuma 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 indicará que o cliente prefere rastrear apenas as alterações nas propriedades ou relacionamentos especificados 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 rastrear as alterações para um ou mais usuários 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 por sua id com pelo menos as propriedades atualizadas, mas outras propriedades podem ser incluídas.

  • As relações com 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 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 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.

  • As 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 sob certas 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 suas funções delta correspondentes ainda no 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 Aplicação: Função DELTA
administrativeUnit administrativeUnit: função delta
agentIdentityBlueprint Aplicação: Função DELTA
callRecording callRecording: função delta
callTranscript callTranscript: função delta
chatMessage chatMessage: função delta
recurso de contato Contato: Função DELTA
contactFolder contactFolder: 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
pasta de caixa de correio mailboxFolder: função delta
mailboxItem mailboxItem: função delta
mailFolder mailFolder: função delta
message Mensagem: Função DELTA
orgContact orgContact: função delta
oAuth2PermissionGrant oAuth2PermissionGrant: função delta
plannerBucket * plannerBucket: função delta
plannerUser2 Função planUser: 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 dos recursos do Planner é semelhante a outros recursos com suporte, com algumas diferenças. Para obter mais informações, consulte planner: delta.

Nuvens nacionais

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

Limitações

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

Alguns recursos contêm propriedades armazenadas fora do repositório de dados principal do recurso. Por exemplo, algumas propriedades do recurso de usuário, como habilidades, são armazenadas no SharePoint e não no Microsoft Entra ID. Atualmente, apenas as propriedades armazenadas no armazenamento de dados principal disparam alterações na consulta delta; As propriedades armazenadas fora do repositório de dados principal 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 repositório de dados principal, consulte a documentação de usuários e grupos .

Atrasos de processamento

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

Às vezes, devido a atrasos de replicação, as alterações no objeto não aparecem imediatamente quando você seleciona o ou o @odata.nextLink .@odata.deltaLink Repita @odata.nextLink ou @odata.deltaLink depois de algum tempo para recuperar as alterações mais recentes. Saiba mais em Projetando para obter uma consistência eventual para o Microsoft Entra.

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 um melhor esforço para reduzir as reproduções, elas 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 ocorre para evitar a 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 reiniciar 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 é fixo; Depende do tamanho do cache interno de token Delta. 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.

Extensões de Diretório

Quando uma alteração é feita em uma propriedade de extensão de diretório, todas as propriedades de extensão de diretório do mesmo tipo de dados são retornadas, independentemente de terem sido alteradas ou não.

Combinar consulta delta e notificações de alteração

Um aplicativo pode usar as notificações de alteração do Microsoft Graph para se inscrever e 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 (somente para recursos com suporte) a necessidade de pesquisar frequentemente o Microsoft Graph e processar essas alterações para manter um armazenamento de dados local em sincronia, reduzindo consideravelmente as chances de suas solicitações serem limitadas.

Conteúdo relacionado

  • Last updated on