Usar a consulta delta para controlar alterações nos dados do Microsoft GraphUse delta query to track changes in Microsoft Graph data

A consulta delta permite que aplicativos localizem 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.Delta query enables applications to discover newly created, updated, or deleted entities without performing a full read of the target resource with every request. Microsoft Graph applications can use delta query to efficiently synchronize changes with a local data store.

Usar solicitação delta para rastrear alterações em uma coleção resourceUse delta query to track changes in a resource collection

O padrão típico de chamada corresponde ao que segue:The typical call pattern is as follows:

  1. O aplicativo começa chamando uma solicitação GET com a função delta no recurso desejado.The application begins by calling a GET request with the delta function on the desired resource.

  2. O Microsoft Graph envia uma resposta que contém o recurso solicitado e um token de estado.Microsoft Graph sends a response containing the requested resource and a state token.

    a. Se uma URL nextLink é retornada, poderá haver páginas de dados adicionais a serem recuperadas na sessão. O aplicativo continua fazendo solicitações usando a URL nextLink para recuperar todas as páginas de dados até que uma URL deltaLink seja retornada na resposta.a. If a nextLink URL is returned, there may be additional pages of data to be retrieved in the session. The application continues making requests using the nextLink URL to retrieve all pages of data until a deltaLink URL is returned in the response.

    b. Se uma URL deltaLink é retornada, não há mais nenhum dado sobre o estado do recurso a ser retornado. Em solicitações futuras, o aplicativo usa a URL deltaLink para inteirar-se das alterações feitas no recurso.b. If a deltaLink URL is returned, there is no more data about the existing state of the resource to be returned. For future requests, the application uses the deltaLink URL to learn about changes to the resource.

  3. Quando o aplicativo precisa saber das alterações no recurso, ele faz uma nova solicitação usando a URL deltaLink recebida na etapa 2. Esta solicitação pode ser feita imediatamente após concluir a etapa 2 ou quando o aplicativo verifica as alterações.When the application needs to learn about changes to the resource, it makes a new request using the deltaLink URL received in step 2. This request may be made immediately after completing step 2 or when the application checks for changes.

  4. O Microsoft Graph retorna uma resposta, descrevendo alterações no recurso desde a solicitação anterior e em uma URL nextLink ou uma URL deltaLink.Microsoft Graph returns a response describing changes to the resource since the previous request, and either a nextLink URL or a deltaLink URL.

Observação: recursos armazenados no Azure Active Directory (por exemplo, usuários e grupos) dão suporte a cenários do tipo "sincronizar a partir de agora".Note: Resources stored in Azure Active Directory (such as users and groups) support "sync from now" scenarios. 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 deltaLink em vez disso.This allows you to skip steps 1 and 2 (if you're not interested in retrieving the full state of the resource) and ask for the latest deltaLink instead. Acrescente $deltaToken=latest à função delta, e a resposta conterá um deltaLink e nenhum dado do recurso.Append $deltaToken=latest to the delta function and the response will contain a deltaLink and no resource data. Os recursos do OneDrive e do Microsoft Office SharePoint Online também oferecem suporte a esse recurso.Resources in OneDrive and SharePoint also support this feature. Para recursos no OneDrive e no Microsoft Office SharePoint Online, anexe token=latest em vez disso.For resources in OneDrive and SharePoint, append token=latest instead.

Observação: a função de consulta Delta geralmente é referida ao acrescentar /delta ao nome do recurso.Note: The delta query function is generally referred to by appending /delta to the resource name. No entanto, /delta é um atalho para o nome totalmente qualificado /microsoft.graph.delta que você vê em solicitações geradas pelos SDKs do Microsoft Graph.However, /delta is a shortcut for the fully qualified name /microsoft.graph.delta that you see in requests generated by the Microsoft Graph SDKs.

Observação: a solicitação inicial para a função de consulta delta (nenhum token delta ou skip) retornará os recursos existentes na coleção.Note: The initial request to the delta query function (no delta or skip token) will return the resources that currently exist in the collection. Os recursos que foram criados e excluídos antes da consulta delta inicial não serão retornados.Resources that have been created and deleted prior to the initial delta query won't be returned. As atualizações feitas antes da solicitação inicial são resumidas no recurso retornado como seu estado mais recente.Updates made before the initial request are summarized on the resource returned as its latest state.

Tokens de estadoState tokens

Um GET de consulta delta sempre inclui uma URL especificada em um cabeçalho de resposta nextLink ou deltaLink. A URL nextLink inclui um skipToken e uma URL deltaLink inclui um deltaToken .A delta query GET response always includes a URL specified in a nextLink or deltaLink response header. The nextLink URL includes a skipToken , and a deltaLink URL includes a deltaToken .

Esses tokens são opacos para o cliente. Os seguintes detalhes são o que você precisa saber sobre eles:These tokens are opaque to the client. The following details are what you need to know about them:

  • Cada token reflete o estado e representa um instantâneo do recurso dessa fase do controle de alterações.Each token reflects the state and represents a snapshot of the resource in that round of change tracking.

  • Os tokens de estado também codificam e incluem outros parâmetros da consulta (como $select) especificados na solicitação de consulta delta inicial. Portanto, ele não é necessário repeti-los em solicitações de consulta delta subsequentes.The state tokens also encode and include other query parameters (such as $select) specified in the initial delta query request. Therefore, it's not required to repeat them in subsequent delta query requests.

  • Ao realizar a consulta delta, você pode copiar e aplicar a URL nextLink ou deltaLink à próxima chamada de função delta sem precisar inspecionar o conteúdo da URL, incluindo seu token de estado.When carrying out delta query, you can copy and apply the nextLink or deltaLink URL to the next delta function call without having to inspect the contents of the URL, including its state token.

Parâmetros de consulta opcionaisOptional query parameters

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 especificado em nextLink ou deltaLink fornecidos na resposta. O aplicativo de chamada só precisa especificar os parâmetros de consulta desejados uma vez antecipados. O Microsoft Graph adiciona os parâmetros especificados automaticamente para todas as solicitações subsequentes.If a client uses a query parameter, it must be specified in the initial request. Microsoft Graph automatically encodes the specified parameter into the nextLink or deltaLink provided in the response. The calling application only needs to specify the query parameters once upfront. Microsoft Graph adds the specified parameters automatically for all subsequent requests.

Observe o suporte geral limitado dos seguintes parâmetros de consulta opcionais:Note the general limited support of the following optional query parameters:

  • $orderby

    Não assuma que uma sequência específica das respostas tenha retornado de uma consulta delta.Do not assume a specific sequence of the responses returned from a delta query. Suponha que o mesmo item possa aparecer em qualquer lugar na sequência do nextLink e leve isso em conta em sua lógica de mesclagem.Assume that the same item can show up anywhere in the nextLink sequence and handle that in your merge logic.

  • $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.The number of objects in each page can vary depending on the resource type and the type of changes made to the resource.

Para obter o recursomensagem, consulte os detalhes do suporte aos parâmetros de consulta em uma consulta delta.For the message resource, see details for query parameters support in a delta query.

Para os recursos de usuário e grupo, há restrições no uso de alguns parâmetros de consulta:For the user and group resources, there are restrictions on using some query parameters:

  • Não há suporte para $expand.$expand is not supported.

  • Não há suporte para $top.$top is not supported.

  • Não há suporte para $orderby.$orderby is not supported.

  • Se um parâmetro de consulta $select for usado, isso indica que o cliente prefere somente controlar alterações nas propriedades ou relações especificadas na instrução $select. Se ocorrer uma alteração em uma propriedade que não esteja selecionada, o recurso por meio do qual essa propriedade foi alterada não aparecerá na resposta delta após uma solicitação subsequente.If a $select query parameter is used, the parameter indicates that the client prefers to only track changes on the properties or relationships specified in the $select statement. If a change occurs to a property that is not selected, the resource for which that property changed does not appear in the delta response after a subsequent request.

  • O $select também tem suporte para manager e members propriedade de navegação para usuários e grupos, respectivamente.$select also supports manager and members navigational property for users and groups respectively. A seleção dessas propriedades permite controlar as alterações feitas no gerenciador de usuário e nas associações de grupo.Selecting those properties allows tracking of changes to user's manager and group memberships.

  • Os filtros de escopo permitem controlar alterações para um ou mais usuários ou grupos específicos por ID de objeto.Scoping filters allow you to track changes to one or more specific users or groups by object ID. Por exemplo, a solicitação a seguir retorna alterações para os grupos que correspondem às IDs especificadas no filtro de consulta.For example, the following request returns changes for the groups matching the IDs specified in the query filter.

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 deltaResource representation in the delta query response

  • 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.Newly created instances of a supported resource are represented in the delta query response using their standard representation.

  • Instâncias atualizadas são representadas por seus id com pelo menos as propriedades que foram atualizadas, mas podem ser incluídas propriedades adicionais.Updated instances are represented by their id with at least the properties that have been updated, but additional properties may be included.

  • Relações entre os usuários e os grupos são representadas como anotações na representação do 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 inicial delta.Relationships on users and groups are represented as annotations on the standard resource representation. These annotations use the format propertyName@delta. The annotations are included in the response of the initial delta query request.

As instâncias removidas são representadas por sua id e um objeto @removed.Removed instances are represented by their id and an @removed object. O objeto @removed pode incluir informações adicionais sobre o porquê de a instância ter sido removida.The @removed object may include additional information about why the instance was removed. Por exemplo, "@removido": {"motivo": “alterado”}.For example, "@removed": {"reason": "changed"}.

Possíveis motivos @removed podem ser changed ou deleted .Possible @removed reasons can be changed or deleted .

  • Alterado indica que o item foi excluído e poderá ser restaurado de deletedItems.Changed indicates the item was deleted and can be restored from deletedItems.

  • Deleted indica que o item foi excluído e não pode ser restaurado.Deleted indicates the item is deleted and cannot be restored.

O objeto @removed pode ser retornado na resposta de consulta delta inicial e nas respostas rastreadas (deltaLink). Os clientes que usam solicitações de consulta delta devem ser designados para lidar com esses objetos nas respostas.The @removed object can be returned in the initial delta query response and in tracked (deltaLink) responses. Clients using delta query requests should be designed to handle these objects in the responses.

Observação: é possível que uma única entidade seja incluída várias vezes na resposta, caso essa entidade tenha sido alterada várias vezes e sob determinadas condições.Note: It's possible that a single entity will be contained multiple times in the response, if that entity was changed multiple times and under certain conditions. As consultas Delta permitem aos aplicativos listar todas as alterações, mas não garantem que as entidades sejam unificadas em uma única resposta.Delta queries enable your application to list all the changes, but can't ensure that entities are unified in a single response.

Recursos com suporteSupported resources

A consulta delta é compatível atualmente com os seguintes recursos.Delta query is currently supported for the following resources. Observe que alguns recursos que estão disponíveis na versão 1.0 têm suas funções delta correspondente ainda em estado de visualização prévia, como indicado.Note that some resources which are available in v1.0 have their corresponding delta functions still in preview status, as indicated.

Coleção de recursosResource collection APIAPI
AplicativosApplications Função delta do recurso aplicativodelta function of the application resource
Unidades administrativas (visualização)Administrative units (preview) Função delta (visualização) do recurso administrativeUnitdelta function (preview) of the administrativeUnit resource
Mensagens de chat em um canal.Chat messages in a channel Função delta (visualização) do chatMessagedelta function (preview) of the chatMessage
AulasClasses Função delta (visualização) do recurso educationClassdelta function (preview) of the educationClass resource
Objetos de diretórioDirectory objects Função delta (visualização) do recurso directoryObjectsdelta function (preview) of the directoryObject resource
Funções de diretórioDirectory roles Função delta do recurso directoryRoledelta function of the directoryRole resource
Itens de unidade*Drive items* Função delta do recurso driveItemdelta function of the driveItem resource
Usuários da educaçãoEducation users Função delta (visualização) do recurso educationUserdelta function (preview) of the educationUser resource
Eventos em um modo de exibição de calendário (intervalo de datas) do calendário principalEvents in a calendar view (date range) of the primary calendar função delta do recurso eventodelta function of the event resource
GruposGroups Função delta do recurso groupdelta function of the group resource
Pastas de emailMail folders função delta do recurso mailFolder delta function of the mailFolder resource
Mensagens de uma pastaMessages in a folder função delta do recurso mensagem delta function of the message resource
Contatos organizacionaisOrganizational contacts função delta do recurso orgContactdelta function of the orgContact resource
OAuth2PermissionGrantsOAuth2PermissionGrants Função delta do recurso oauth2permissiongrant delta function of the oauth2permissiongrant resource
Pastas de contatos pessoaisPersonal contact folders função delta do recurso contactFolderdelta function of the contactFolder resource
Contatos pessoais em uma pastaPersonal contacts in a folder Função delta do recurso contatodelta function of the contact resource
Itens do Planner** (pré-visualização)Planner items** (preview) Função delta (visualização) de todos os segmentos do recurso plannerUserdelta function (preview) of the all segment of plannerUser resource
EscolasSchools Função delta (visualização) do recurso educationSchooldelta function (preview) of the educationSchool resource
Entidades de serviçoService principals Função delta do recurso servicePrincipaldelta function of the servicePrincipal resource
Tarefas em uma lista de tarefasTasks in a task list Função delta do recurso todoTaskdelta function of the todoTask resource
Listas de tarefasTask lists Função delta do recurso todoTaskListdelta function of the todoTaskList resource
UsuáriosUsers função delta do recurso usuáriodelta function of the user resource

* O padrão de uso dos recursos do OneDrive é semelhante a outros recursos compatíveis com algumas pequenas diferenças de sintaxe.* The usage pattern for OneDrive resources is similar to the other supported resources with some minor syntax differences. A consulta delta para unidades será atualizada no futuro para serem consistentes com outros tipos de recursos.Delta query for drives will be updated in the future to be consistent with other resource types. Confira mais detalhes sobre a sintaxe atual em Controlar alterações para uma unidade.For more detail about the current syntax, see Track changes for a drive.

** O padrão de uso dos recursos do Planner é semelhante a outros recursos compatíveis, mas com algumas diferenças.** The usage pattern for Planner resources is similar to other supported resources with a few differences. Para saber mais, consulte Controlar alterações para o Planner.For details, see Track changes for Planner.

LimitaçõesLimitations

Propriedades armazenadas fora do repositório de dados principalProperties stored outside of the main data store

Alguns recursos contêm propriedades armazenadas fora do repositório de dados principal do recurso (por exemplo, o recurso de usuário é armazenado no sistema Azure AD, enquanto algumas propriedades, como skills , são armazenadas no SharePoint Online).Some resources contain properties that are stored outside of the main data store for the resource (for example, the user resource is mostly stored in the Azure AD system, while some properties, like skills , are stored in SharePoint Online). Atualmente, não há suporte para essas propriedades como parte do controle de alterações; uma alteração em uma dessas propriedades não resultará em um objeto aparecendo na resposta de consulta Delta.Currently, those properties are not supported as part of change tracking; a change to one of those properties will not result in an object showing up in the delta query response. Atualmente, apenas as propriedades armazenadas no repositório de dados principal disparam alterações na consulta Delta.Currently, only the properties stored in the main data store trigger changes in the delta query.

Para verificar se uma propriedade pode ser usada na consulta Delta, experimente executar uma operação de GET regular na coleção de recursos e selecione a propriedade que você está interessado.To verify that a property can be used in delta query, try to perform a regular GET operation on the resource collection, and select the property you're interested in. Por exemplo, você pode usar a propriedade skills na coleção de usuários.For example, you can try the skills property on the users collection.

GET https://graph.microsoft.com/v1.0/users/?$select=skills

Como a propriedade skills é armazenada fora do Azure AD, a seguinte é a resposta.Because the skills property is stored outside of Azure AD, the following is the response.

HTTP/1.1 501 Not Implemented
Content-type: application/json

{
    "error": {
        "code": "NotImplemented",
        "message": "This operation target is not yet supported.",
        "innerError": {
            "request-id": "...",
            "date": "2019-09-20T21:47:50"
        }
    }
}

Isso informa que não há suporte para a propriedade skills para a consulta Delta no recurso user .This tells you that the skills property is not supported for delta query on the user resource.

Não há suporte para propriedades de navegação.Navigation properties are not supported. Por exemplo, você não pode controlar alterações na coleção de usuários que incluiriam alterações na propriedade photo ; photo é uma propriedade de navegação armazenada fora da entidade do usuário, e as alterações feitas nela não fazem com que o objeto de usuário seja incluído na resposta Delta.For example, you cannot track changes to the users collection that would include changes to their photo property; photo is a navigation property stored outside of the user entity, and changes to it do not cause the user object to be included in the delta response.

Atrasos de processamentoProcessing delays

Esperar atrasos variáveis entre o tempo que uma alteração é feita em uma instância de recurso, que pode ser por meio de uma interface de aplicativo ou API, e o tempo em que a alteração controlada é refletida em uma resposta de consulta Delta.Expect varying delays between the time a change is made to a resource instance, which can be through an app interface or API, and the time the tracked change is reflected in a delta query response.

Nuvens nacionaisNational clouds

As consultas Delta estão disponíveis para os clientes hospedados na nuvem pública e o Microsoft Graph na China operado apenas pela 21Vianet.Delta queries are available for customers hosted on the public cloud and Microsoft Graph China operated by 21Vianet only.

RepetiçõesReplays

O aplicativo deve estar preparado para repetições, que ocorrem quando a mesma alteração aparece nas respostas subsequentes.Your application must be prepared for replays, which occur when the same change appears in subsequent responses. Embora a consulta delta se esforce ao máximo para reduzir as repetições, elas ainda são possíveis.While delta query makes a best effort to reduce replays, they are still possible.

Sincronização redefinidaSynchronization reset

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 token delta vazio (igual à consulta inicial).Delta query can return a response code of 410 (gone) and a Location header containing a request URL with an empty delta token (same as the initial query). Isso é uma indicação de que o aplicativo deve reiniciar com uma sincronização completa do locatário de destino.This is an indication that the application must restart with a full synchronization of the target tenant. Isso geralmente acontece para evitar inconsistência de dados devido à manutenção interna ou migração do locatário de destino.This usually happens to prevent data inconsistency due to internal maintenance or migration of the target tenant.

Duração do tokenToken duration

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.Delta tokens are only valid for a specific period before the client application needs to run a full synchronization again. Para objetos de diretório ( application , administrativeUnit , directoryObject , directoryRole , group , orgContact , oauth2permissiongrant , servicePrincipal , and user ), o limite é de 7 dias.For directory objects ( application , administrativeUnit , directoryObject , directoryRole , group , orgContact , oauth2permissiongrant , servicePrincipal , and user ), the limit is 7 days. Para objetos de formação educacional ( educationSchool , educationUser e educationClass ), o limite é de 7 dias.For education objects ( educationSchool , educationUser , and educationClass ), the limit is 7 days. Para entidades do Outlook ( message , mailFolder , event , contact , contactFolder , todoTask , and todoTaskList ), o limite superior não é corrigido; depende do tamanho do cache de tokens do delta interno.For Outlook entities ( message , mailFolder , event , contact , contactFolder , todoTask , and todoTaskList ), the upper limit is not fixed; it's dependent on the size of the internal delta token cache. 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.While new delta tokens are continuously added in the cache, after the cache capacity is exceeded, the older delta tokens are deleted.

Pré-requisitosPrerequisites

As mesmas permissões necessárias para ler um recurso específico também são necessárias para executar a consulta delta nesse recurso.The same permissions that are required to read a specific resource are also required to perform delta query on that resource.

Exemplos de solicitação de consulta deltaDelta query request examples