Dient zum Abrufen inkrementeller Änderungen für Benutzer.Get incremental changes for users

Mit der Delta-Abfrage können Sie Ergänzungen, Löschungen oder Aktualisierungen an Benutzern anhand einer Serie von Delta-Funktionsaufrufen abfragen. Mit der Delta-Abfrage können Sie Änderungen an Benutzern ermitteln, ohne den gesamten Satz von Benutzern von Microsoft Graph abrufen und Änderungen vergleichen zu müssen.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.

Clients, die Benutzer mit einem lokalen Profilspeicher synchronisieren, können Delta Abfragen für die anfängliche vollständige Synchronisierung und für inkrementelle Synchronisierungen in der Zukunft verwenden. In der Regel führt ein Client eine anfängliche vollständige Synchronisierung aller Benutzer in einem Mandanten durch und ruft anschließend regelmäßig inkrementelle Änderungen an Benutzern ab.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.

Nachverfolgen von BenutzeränderungenTracking user changes

Das Nachverfolgen von Benutzeränderungen ist eine Runde aus einer oder mehreren GET-Anforderungen mit der Delta-Funktion. Eine GET-Anforderung wird ähnlich wie das Auflisten von Benutzern durchgeführt, außer dass Folgendes eingeschlossen wird: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:

  • Die Delta-Funktion.The delta function.
  • Ein Statustoken (deltaToken oder skipToken) aus dem vorherigen GET-Delta-Funktionsaufruf.A state token (deltaToken or skipToken) from the previous GET delta function call.

BeispielExample

Das folgende Beispiel zeigt eine Serienanforderung zum Nachverfolgen von Änderungen an Benutzern:The following example shows a series requests to track changes to users:

  1. Ursprüngliche Anforderung und AntwortInitial request and response
  2. nextLink-Anforderung und AntwortnextLink request and response
  3. Letzte nextLink-Anforderung und AntwortFinal nextLink request and response
  4. deltaLink-Anforderung und deltaLink-AntwortdeltaLink request and deltaLink response

Ursprüngliche AnforderungInitial request

Um Änderungen an der Benutzerressource nachzuverfolgen, nehmen Sie zunächst eine Anforderung einschließlich der Delta-Funktion für die Benutzerressource vor.To begin tracking changes in the user resource, you make a request including the delta function on the user resource.

Beachten Sie Folgendes:Note the following:

  • Der optionale Abfrageparameter „$select“ wird in die Anforderung eingeschlossen, um zu veranschaulichen, wie Abfrageparameter automatisch in zukünftige Anforderungen eingeschlossen werden.The optional $select query parameter is included in the request to demonstrate how query parameters are automatically included in future requests.
  • Die ursprüngliche Anforderung enthält kein Statustoken. Statustoken werden in nachfolgenden Anforderungen verwendet.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

Ursprüngliche AntwortInitial response

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und das Sammlungsobjekt user im Antworttext zurückgegeben. Wenn der ganze Satz von Benutzern zu groß ist, enthält die Antwort zudem ein nextLink-Statustoken.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.

In diesem Beispiel wird eine nextLink-URL zurückgegeben, die angibt, dass es zusätzliche Seiten mit Daten gibt, die in der Sitzung abgerufen werden müssen. Der Abfrageparameter „$select“ aus der ursprünglichen Anforderung wird in der nextLink-URL codiert.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"
    }
  ]
}

Die zweite Anforderung gibt das aus der vorherigen Antwort zurückgegebene skipToken an. Beachten Sie, dass der Parameter $select nicht erforderlich ist, da das skipToken ihn codiert und einschließt.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

Die Antwort enthält ein weiteres nextLink mit einem neuen skipToken-Wert, wodurch angegeben wird, dass weitere Gruppen verfügbar sind.The response contains another nextLink with a new skipToken value, which indicates that more groups are available. Sie sollten weiterhin Anforderungen mithilfe der nextLink-URL erstellen, bis eine deltaLink-URL in der endgültigen Antwort zurückgegeben wird, auch wenn der Wert ein leeres Array ist (dies kann unter bestimmten Umständen geschehen).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"
    }
  ]
}

Die dritte Anforderung verwendet weiterhin das neueste aus der letzten Synchronisierungsanforderung zurückgegebene skipToken.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

Wenn die deltaLink-URL zurückgegeben wird, gibt es keine weiteren Daten über den derzeitigen Status der zurückzugebenen Ressource. Für zukünftige Anforderungen verwendet die Anwendung die deltaLink-URL, um Informationen zu Änderungen an der Ressource zu erhalten. Speichern Sie das deltaToken, und verwenden Sie es in der Anforderungs-URL, um Änderungen an Benutzern zu ermitteln.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"
    }
  ]
}

Mit dem deltaToken aus der letzten Antwort können Sie seit der letzten Anforderung geänderte (hinzugefügte, gelöschte oder aktualisierte) Benutzer abrufen.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

Falls keine Änderungen vorgenommen wurden, wird ein anderes deltatoken ohne Ergebnisse zurückgegeben.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": []
}

Wenn Änderungen vorgenommen wurden, wird ein anderes deltatoken mit einer Sammlung der geänderten Benutzer zurückgegeben.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"
      }
    }
  ]
}

Einige Punkte, die Sie bei der oben aufgeführten Beispielantwort beachten sollten:Some things to note about the example response above:

  • Wenn der Benutzer gelöscht wurde, enthält das Element eine Anmerkung: @removed mit einem Wert von "reason": "changed".When the user is deleted, the item contains an annotation: @removed with value of "reason": "changed".

  • Wenn der Benutzer dauerhaft gelöscht wurde, enthält das Element eine Anmerkung: @removed mit einem Wert von "reason": "deleted".When the user is permanently deleted, the item contains an annotation: @removed with value of "reason": "deleted".

  • Wenn der Benutzer erstellt oder wiederhergestellt wird, gibt es keine Anmerkung.When the user is created, or restored, there is no annotation.

Siehe auchSee also

Microsoft Graph-Delta-Abfrage – Übersicht.Microsoft Graph delta query overview.