Obter as alterações incrementais para usuáriosGet incremental changes for users

A consulta delta permite que você consulte adições, exclusões ou atualizações de usuários, por meio de uma série de chamadas de função delta. A consulta Delta permite que você descubra alterações em usuários sem ter que buscar todo o conjunto de usuários do Microsoft Graph e comparar as alterações.Delta query lets you query for additions, deletions, or updates to users, by way of a series of delta function calls. Delta query enables you discover changes to users without having to fetch the entire set of users from Microsoft Graph and compare changes.

Clientes que sincronizam usuários com um repositório de perfil local podem usar a Consulta Delta para a sincronização completa inicial juntamente com as sincronizações incrementais no futuro. Normalmente, um cliente faria uma sincronização completa inicial de todos os usuários em um locatário e, logo após, obteria alterações incrementais para esses usuários periodicamente.Clients using synchronizing users with a local profile store can use Delta Query for both their initial full synchronization along with incremental synchronizations in the future. Typically, a client would do an initial full synchronization of all the users in a tenant, and subsequently, get incremental changes to users periodically.

Controle de alterações de usuáriosTracking user changes

O controle de alterações de usuários corresponde a uma série de uma ou mais solicitações GET com a função delta. Criar uma solicitação GET é muito parecido com a forma de listar usuários, exceto se você incluir o seguinte:Tracking user changes is a round of one or more GET requests with the delta function. You make a GET request much like the way you list users, except that you include the following:

  • A função delta.The delta function.
  • Um token de estado (deltaToken ou skipToken) da chamada de função GET delta anterior.A state token (deltaToken or skipToken) from the previous GET delta function call.

ExemploExample

O exemplo a seguir mostra uma série de solicitações para rastrear as alterações nos usuários:The following example shows a series requests to track changes to users:

  1. Solicitação inicial e respostaInitial request and response
  2. solicitação nextLink e respostanextLink request and response
  3. Solicitação final nextLink e respostaFinal nextLink request and response
  4. Solicitação deltaLink e resposta deltaLinkdeltaLink request and deltaLink response

Solicitação inicialInitial request

Para iniciar o controle das alterações no recurso de usuário, faça uma solicitação incluindo a função delta do recurso de usuário.To begin tracking changes in the user resource, you make a request including the delta function on the user resource.

Observe o seguinte:Note the following:

  • O parâmetro de consulta $select opcional está incluído na solicitação para demonstrar como os parâmetros de consulta são automaticamente incluídos nas futuras solicitações.The optional $select query parameter is included in the request to demonstrate how query parameters are automatically included in future requests.
  • A solicitação inicial não inclui um token de estado. Os tokens de estado serão usados nas solicitações subsequentes.The initial request does not include a state token. State tokens will be used in subsequent requests.
GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,givenName,surname

Resposta inicialInitial response

Se bem-sucedido, este método retorna o código de resposta 200 OK e o objeto da coleção user no corpo da resposta. Pressupondo que todo o conjunto de usuários é muito grande, a resposta também incluirá um token de estado nextLink.If successful, this method returns 200 OK response code and user collection object in the response body. Assuming the entire set of users is too large, the response will also include a nextLink state token.

Neste exemplo, uma URL nextLink é retornada indicando que não há páginas adicionais de dados a serem recuperados na sessão. O parâmetro de consulta $select da solicitação inicial é codificado na URL nextLink.In this example, a nextLink URL is returned indicating there are additional pages of data to be retrieved in the session. The $select query parameter from the initial request is encoded into the nextLink URL.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users(displayName,givenName,surname)",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa",
  "value": [
    {
      "displayName":"Testuser1",
      "givenName":"John",
      "surname":"Doe",
      "id":"ffff7b1a-13b6-477b-8c0c-380905cd99f7"
    },
    {
      "displayName":"Testuser2",
      "givenName":"Jane",
      "surname":"Doe",
      "id":"605d1257-ffff-40b6-8e6f-528a53f5dc55"
    }
  ]
}

A segunda solicitação especifica o skipToken retornado da resposta anterior. Observe que o parâmetro $select não é obrigatório, pois o skipToken codifica e o inclui.The second request specifies the skipToken returned from the previous response. Notice the $select parameter is not required, as the skipToken encodes and includes it.

GET https://graph.microsoft.com/v1.0/users/delta?$skiptoken=oEBwdSP6uehIAxQOWq_3Ksh_TLol6KIm3stvdc6hGhZRi1hQ7Spe__dpvm3U4zReE4CYXC2zOtaKdi7KHlUtC2CbRiBIUwOxPKLa

A resposta contém outro nextLink com outro valor de skipToken, indicando que há mais grupos disponíveis.The response contains another nextLink with a new skipToken value, which indicates that more groups are available. Você deve continuar criando solicitações usando a nextLink URL até que uma deltaLink URL seja retornada na resposta final, mesmo que o valor seja uma matriz vazia (isso pode ocorrer em determinadas circunstâncias).You should continue making requests using the nextLink URL until a deltaLink URL is returned in the final response, even if the value is an empty array (this can happen under certain circumstances).

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"Testuser3",
      "givenName":"Pat",
      "surname":"Doe",
      "id":"d8c37826-ffff-4cae-b348-e2725b1e814b"
    },
    {
      "displayName":"Testuser4",
      "givenName":"Meghan",
      "surname":"Doe",
      "id":"8b1ee412-cd8f-4d59-ffff-24010edb9f1f"
    }
  ]
}

A terceira solicitação continua a usar os últimos skipToken retornados da última solicitação de sincronização.The third request continues to use the latest skipToken returned from the last sync request.

GET https://graph.microsoft.com/v1.0/users/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7

Quando a 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 se inteirar das alterações feitas no recurso. Salve o deltaToken e use-o na solicitação da URL para descobrir as alterações feitas nos usuários.When the 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. Save the deltaToken and use it in the request URL to discover changes to users.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460",
  "value": [
    {
      "displayName":"Testuser5",
      "givenName":"Al",
      "surname":"Doe",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "displayName":"Testuser6",
      "givenName":"Sam",
      "surname":"Doe",
      "id":"f6ede700-27d0-4c42-bfb9-4dffff43c74a"
    }
  ]
}

Usando o deltaToken da última resposta, você poderá obter usuários alterados (ao ser adicionado, excluído ou atualizado) desde o último pedido.Using the deltaToken from the last response, you will be able to get changed (by being added, deleted, or updated) users since the last request.

GET https://graph.microsoft.com/v1.0/users/delta?$deltatoken=oEcOySpF_hWYmTIUZBOIfPzcwisr_rPe8o9M54L45qEXQGmvQC6T2dbL-9O7nSU-njKhFiGlAZqewNAThmCVnNxqPu5gOBegrm1CaVZ-ZtFZ2tPOAO98OD9y0ao460

Se não houve alterações, uma diferente deltatoken é retornada com nenhum resultado.If no changes have occurred, a different deltatoken is returned with no results.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=MF1LuFYbK6Lw4DtZ4o9PDrcGekRP65WEJfDmM0H26l4v9zILCPFiPwSAAeRBghxgiwsXEfywcVQ9R8VEWuYAB50Yw3KvJ-8Z1zamVotGX2b_AHVS_Z-3b0NAtmGpod",
  "value": []
}

Se houve alterações, uma diferente deltatoken é retornada incluindo um conjunto de usuários alterados.If changes have occurred, a different deltatoken is returned including a collection of changed users.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/users/delta?$deltatoken=MF1LuFYbK6Lw4DtZ4o9PDrcGekRP65WEJfDmM0H26l4v9zILCPFiPwSAAeRBghxgiwsXEfywcVQ9R8VEWuYAB50Yw3KvJ-8Z1zamVotGX2b_AHVS_Z-3b0NAtmGpod",
  "value": [
    {
      "displayName":"Testuser7",
      "givenName":"Joe",
      "surname":"Doe",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "id":"8ffff70c-1c63-4860-b963-e34ec660931d",
      "@removed": {
         "reason": "changed"
      }
    }
  ]
}

Alguns aspectos a observar sobre a resposta do exemplo acima:Some things to note about the example response above:

  • Quando o usuário é excluído, o item contém uma anotação: @removed com valor de "reason": "changed".When the user is deleted, the item contains an annotation: @removed with value of "reason": "changed".

  • Quando o usuário é excluído permanentemente, o item contém uma anotação: @removed com valor de "reason": "deleted".When the user is permanently deleted, the item contains an annotation: @removed with value of "reason": "deleted".

  • Quando o usuário é criado ou restaurado, não há nenhuma anotação.When the user is created, or restored, there is no annotation.

Confira tambémSee also

Visão geral da consulta delta do Microsoft Graph.Microsoft Graph delta query overview.