Freigeben über


Dient zum Abrufen inkrementeller Änderungen für Benutzer.

Mit der Delta-Abfrage in Microsoft Graph können Sie über eine Reihe von Deltaanforderungen Ergänzungen, Löschungen oder Updates für unterstützte Ressourcen abfragen. Bei Benutzern können Sie mit der Delta-Abfrage Änderungen feststellen, ohne den gesamten Satz von Benutzern abrufen zu müssen, um Änderungen zu vergleichen.

Clients, die Benutzer mit einem lokalen Profilspeicher synchronisieren, können die Delta-Abfrage sowohl für ihre anfängliche vollständige Synchronisierung als auch für nachfolgende schrittweise erfolgende Synchronisierungen verwenden. In der Regel führt ein Client eine anfängliche vollständige Synchronisierung aller Benutzer in einem Mandanten durch und ruft dann in regelmäßigen Abständen inkrementelle Änderungen an Benutzern ab.

Nachverfolgen von Änderungen an Benutzern

Nachverfolgen von Benutzeränderungen über eine oder mehrere GET-Anforderungen mit der Delta-Funktion. Die GET-Anforderung weist die folgenden Merkmale auf:

  • Die Delta-Funktion , die dem URL-Pfad vorangestellt ist.
  • Ein Zustandstoken (Deltatoken oder skipToken) aus dem vorherigen Aufruf der GET-Deltafunktion .
  • [Optional] Alle unterstützten Abfrageparameter

Beispiel

Dieser Artikel zeigt eine Reihe von Beispielanforderungen zum Nachverfolgen von Änderungen an Benutzern:

  1. Eine ursprüngliche Anforderung und Antwort
  2. Eine nextLink-Anforderung und Antwort
  3. Eine letzte nextLink-Anforderung und Antwort
  4. Eine deltaLink-Anforderung und deltaLink-Antwort

Ursprüngliche Anforderung

Um Änderungen in der Benutzerressource nachzuverfolgen, stellen Sie eine Anforderung, und schließen Sie die Delta-Funktion als URL-Segment ein.

Tipp

/delta ist eine Verknüpfung für den vollqualifizierten Namen /microsoft.graph.delta. Von Microsoft Graph SDKs generierte Anforderungen verwenden den vollqualifizierten Namen.

Beachten Sie die folgenden Elemente:

  • Der optionale $select-Abfrageparameter wird in die Anforderung eingeschlossen, um zu veranschaulichen, wie Abfrageparameter automatisch in zukünftige Anforderungen eingeschlossen werden. Falls erforderlich, müssen Abfrageparameter in der anfänglichen Anforderung angegeben werden.
    • Nur eigenschaften, die in $select enthalten sind, werden auf Änderungen nachverfolgt. Wenn $select nicht angegeben ist, werden alle Eigenschaften des Objekts auf Änderungen nachverfolgt.
  • Die ursprüngliche Anforderung enthält keinen Zustands-Token. Zustandstoken werden in nachfolgenden Anforderungen verwendet.
GET https://graph.microsoft.com/v1.0/users/delta?$select=displayName,givenName,surname

Ursprüngliche Antwort

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und das user-Sammlungsobjekt im Antworttext zurückgegeben. Wenn der gesamte Benutzersatz zu groß ist, enthält die Antwort ein @odata.nextLink Zustandstoken in einem @odata.nextLink Parameter.

In diesem Beispiel wird eine @odata.nextLink URL zurückgegeben, die angibt, dass in der Sitzung weitere Seiten mit Daten abgerufen werden müssen. Beachten Sie die $skiptoken in der URL. Der $select Abfrageparameter aus der ursprünglichen Anforderung wird in der @odata.nextLink URL codiert.

Die Antwort enthält auch eine @removed Anmerkung für einen Benutzer mit der ID 86462606-fde0-4fc4-9e0c-a20eb73e54c6. Die @removed Anmerkung wird in den folgenden Szenarien hinzugefügt:

  • Wenn der Benutzer gelöscht wurde, enthält das Element eine Anmerkung: @removed mit einem Wert von "reason": "changed".
  • Wenn der Benutzer endgültig gelöscht wird, enthält das Element eine Anmerkung: @removed mit dem "reason": "deleted"Wert .
  • Wenn der Benutzer erstellt oder aus dem Container für gelöschte Elemente wiederhergestellt wird, gibt es keine Anmerkung.
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":"Cameron White",
      "givenName":"Cameron",
      "surname":"White",
      "id":"ffff7b1a-13b6-477b-8c0c-380905cd99f7"
    },
    {
      "displayName":"Delia Dennis",
      "givenName":"Delia",
      "surname":"Dennis",
      "id":"605d1257-ffff-40b6-8e6f-528a53f5dc55"
    },
    {
      "id": "86462606-fde0-4fc4-9e0c-a20eb73e54c6",
      "@removed": {
        "reason": "deleted"
      }
    },
    {
      "displayName": "Conf Room Adams",
      "id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"
    }
  ]
}

Die zweite Anforderung gibt das aus der vorherigen Antwort zurückgegebene skipToken an. Beachten Sie, dass der $select Parameter codiert und in der skipTokenenthalten ist.

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

Die Antwort enthält einen anderen @odata.nextLink mit einem neuen skipToken Wert, der angibt, dass weitere Änderungen, die für Benutzer nachverfolgt wurden, verfügbar sind. Verwenden Sie die @odata.nextLink URL in weiteren Anforderungen, bis @odata.deltaLink in der endgültigen Antwort eine URL (in einem @odata.deltaLink Parameter) zurückgegeben wird, auch wenn der Wert eine leere Anordnung ist.

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":"Mallory Cortez",
      "givenName":"Mallory",
      "surname":"Cortez",
      "id":"d8c37826-ffff-4cae-b348-e2725b1e814b"
    },
    {
      "displayName":"Diego Sicilian",
      "givenName":"Diego",
      "surname":"Sicilian",
      "id":"8b1ee412-cd8f-4d59-ffff-24010edb9f1f"
    }
  ]
}

Die dritte Anforderung verwendet die neueste skipToken, die von der letzten Synchronisierungsanforderung zurückgegeben wurde.

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

Diese Antwort enthält eine @odata.deltaLink URL, die angibt, dass keine Weiteren Daten zum vorhandenen Zustand der Benutzerobjekte vorhanden sind. Für zukünftige Anforderungen verwendet die Anwendung die @odata.deltaLink URL, um von weiteren Änderungen an Benutzern zu erfahren. Speichern Sie die deltatoken und verwenden Sie diese in der nachfolgenden Anforderungs-URL, um weitere Änderungen an Benutzern zu ermitteln.

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":"Lidia Holloway",
      "givenName":"Lidia",
      "surname":"Holloway",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "displayName":"Patti Fernandez",
      "givenName":"Patti",
      "surname":"Fernandez",
      "id":"f6ede700-27d0-4c42-bfb9-4dffff43c74a"
    }
  ]
}

Mithilfe von deltatoken aus der letzten Antwort erhalten Sie Änderungen (Ergänzungen, Löschungen oder Updates) an Benutzern seit der letzten Anforderung.

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

Wenn keine Änderungen vorgenommen werden, wird ein @odata.deltaLink ohne Ergebnisse zurückgegeben. Die Value-Eigenschaft ist ein leeres Array.

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 vorhanden sind, wird eine Auflistung geänderter Benutzerobjekte eingeschlossen. Die Antwort enthält zudem @odata.nextLink – falls mehrere Seiten mit Änderungen abgerufen werden müssen – oder @odata.deltaLink. Implementieren Sie das gleiche Muster, dem @odata.nextLink endgültigen Aufruf folgen und behalten Sie es für zukünftige Aufrufe @odata.deltaLink bei.

Hinweis

Bei dieser Anforderung kann es zu Replikationsverzögerungen für Benutzer kommen, die kürzlich erstellt, aktualisiert oder gelöscht wurden. Wiederholen Sie die @odata.nextLink oder @odata.deltaLink nach einiger Zeit, um die neuesten Änderungen abzurufen.

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":"MOD Administrator",
      "givenName":"MOD",
      "surname":"Administrator",
      "id":"25dcffff-959e-4ece-9973-e5d9b800e8cc"
    },
    {
      "id":"8ffff70c-1c63-4860-b963-e34ec660931d",
      "@removed": {
         "reason": "changed"
      }
    }
  ]
}