Inkrementelle Änderungen für Gruppen abrufen (Vorschau)

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

Die Delta-Abfrage unterstützt die vollständige Synchronisierung, die alle Gruppen in einem Mandanten abruft, und die inkrementelle Synchronisierung, die nur die Gruppen abruft, die seit der letzten Synchronisierung geändert wurden. In der Regel führen Sie zunächst eine vollständige Synchronisierung aller Gruppen in einem Mandanten durch und rufen anschließend regelmäßig inkrementelle Änderungen an Gruppen ab.

Nachverfolgen von Gruppenänderungen

Das Nachverfolgen von Gruppenänderungen ist eine Runde von einer oder mehreren GET-Anforderungen mit der Delta-Funktion. Eine GET-Anforderung wird ähnlich wie das Auflisten von Gruppen durchgeführt, außer dass Folgendes eingeschlossen wird:

  • Die Delta-Funktion.
  • Ein Statustoken (_deltaToken_ oder skipToken) aus dem vorherigen GET-Delta-Funktionsaufruf.

Beispiel

Das folgende Beispiel zeigt eine Serienanforderung zum Nachverfolgen von Änderungen an Gruppen:

  1. Ursprüngliche Anforderung und Antwort
  2. nextLink-Anforderung und Antwort
  3. Letzte nextLink-Anforderung und Antwort
  4. deltaLink-Anforderung und deltaLink-Antwort

Ursprüngliche Anforderung

Um Änderungen an der Gruppenressource nachzuverfolgen, nehmen Sie zunächst eine Anforderung einschließlich der Delta-Funktion für die Gruppenressource vor.

Beachten Sie Folgendes:

  • Der optionale Abfrageparameter „$select“ wird in die Anforderung eingeschlossen, um zu veranschaulichen, wie Abfrageparameter automatisch in zukünftige Anforderungen eingeschlossen werden.
  • Die ursprüngliche Anforderung enthält kein Statustoken. Statustoken werden in nachfolgenden Anforderungen verwendet.
GET https://graph.microsoft.com/beta/groups/delta?$select=displayName,description

Ursprüngliche Antwort

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200, OK und das Sammlungsobjekt group im Antworttext zurückgegeben. Wenn der ganze Satz von Gruppen zu groß ist, enthält die Antwort zudem ein nextLink-Statustoken.

In diesem Beispiel wird eine nextLink-URL zurückgegeben, was bedeutet, 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.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups(displayName,description)",
  "@odata.nextLink":"https://graph.microsoft.com/beta/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ",
  "value": [
    {
      "displayName":"TestGroup1",
      "description":"Employees in test group 1",
      "id":"c2f798fd-f95d-4623-8824-63aec21fffff"
    },
    {
      "displayName":"TestGroup2",
      "description":"Employees in test group 2",
      "id":"ec22655c-8eb2-432a-b4ea-8b8a254bffff"
    }
  ]
}

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.

GET https://graph.microsoft.com/beta/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ

Die Antwort enthält einen nextLink und ein weiteres skipToken, wodurch angegeben wird, dass weitere Gruppen verfügbar sind. Sie nehmen weiterhin Anforderungen über die nextLink-URL vor, bis eine deltaLink-URL in der Antwort zurückgegeben wird.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/beta/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"TestGroup3",
      "description":"Employees in test group 3",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957"
    },
    {
      "displayName":"TestGroup4",
      "description":"Employees in test group 4",
      "id":"421e797f-9406-4934-b778-4908421e3505"
    }
  ]
}

Die dritte Anforderung verwendet weiterhin das neueste aus der letzten Synchronisierungsanforderung zurückgegebene skipToken.

GET https://graph.microsoft.com/beta/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_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 Gruppen zu ermitteln.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/beta/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
    {
      "displayName":"TestGroup5",
      "description":"Employees in test group 5",
      "id":"bed7f0d4-750e-4e7e-ffff-169002d06fc9"
    },
    {
      "displayName":"TestGroup6",
      "description":"Employees in test group 6",
      "id":"421e797f-9406-ffff-b778-4908421e3505"
    }
  ]
}

Mit dem deltaToken aus der letzten Antwort können Sie seit der letzten Anforderung geänderte (hinzugefügte, gelöschte oder aktualisierte) Gruppen abrufen.

GET https://graph.microsoft.com/beta/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw

Falls keine Änderungen vorgenommen wurden, wird dasselbe deltatoken ohne Ergebnisse zurückgegeben.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/beta/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": []
}

Wenn Änderungen vorgenommen wurden, wird dasselbe deltatoken mit einer Sammlung der geänderten Gruppen zurückgegeben.

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

{
  "@odata.context":"https://graph.microsoft.com/beta/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/beta/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
    {
      "displayName":"TestGroup7",
      "description":"Employees in test group 7",
      "id":"f764235c-ffff-4843-a14a-1d8826967260"
    }
  ]
}

Siehe auch

Microsoft Graph-Delta-Abfrage – Übersicht.