Freigeben über


Abrufen inkrementeller Änderungen für Gruppen

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 Gruppen ermöglicht ihnen die Delta-Abfrage das Ermitteln von Änderungen, ohne den gesamten Satz von Gruppen zum Vergleichen von Änderungen abzurufen.

Clients, die Gruppen 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 Gruppen in einem Mandanten durch und ruft dann in regelmäßigen Abständen inkrementelle Änderungen an Gruppen ab.

Nachverfolgen von Änderungen an Gruppen

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 Gruppen:

  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 Gruppenressource 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.
  • Der optionale $select-Abfrageparameter wird außerdem verwendet, um anzuzeigen, wie Mitglieder der Gruppe zusammen mit Objekten der Gruppe abgerufen werden können. Diese Funktion ermöglicht die Nachverfolgung von Mitgliedschaftsänderungen, z. B. wenn Benutzer hinzugefügt oder aus Gruppen entfernt werden.
  • Die ursprüngliche Anforderung enthält keinen Zustands-Token. Zustandstoken werden in nachfolgenden Anforderungen verwendet.
GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members

Ursprüngliche Antwort

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 200 OK und das group-Sammlungsobjekt im Antworttext zurückgegeben. Wenn die gesamte Gruppe von Gruppen zu groß ist, um in eine Antwort zu passen, wird ein @odata.nextLink mit einem Zustandstoken eingeschlossen.

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 members@delta Eigenschaft ist in der Gruppe Alle Unternehmen enthalten und enthält die beiden aktuellen Mitglieder der Gruppe. sg-HR enthält diese Eigenschaft nicht, da die Gruppe über keine Mitglieder verfügt.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups(displayName,description)",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ",
  "value": [
    {
      "displayName":"All Company",
      "description":"This is the default group for everyone in the network",
      "id":"c2f798fd-f95d-4623-8824-63aec21fffff",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "693acd06-2877-4339-8ade-b704261fe7a0"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    },
    {
      "displayName":"sg-HR",
      "description":"All HR personnel",
      "id":"ec22655c-8eb2-432a-b4ea-8b8a254bffff"
    }
  ]
}

Die zweite Anforderung verwendet @odata.nextLink aus der vorherigen Antwort, die skiptoken enthält. Beachten Sie, dass der $select Parameter nicht sichtbar vorhanden ist, da er codiert und im Token enthalten ist.

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

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

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"Mark 8 Project Team",
      "description":"Mark 8 Project Team",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "632f6bb2-3ec8-4c1f-9073-0027a8c68593"
               }
      ]
    },
    {
      "displayName":"Sales and Marketing",
      "description":"Sales and Marketing",
      "id":"421e797f-9406-4934-b778-4908421e3505",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "3c8ac7c4-d365-4df9-abfa-356a9dd7763c"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    }
  ]
}

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

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7

Wenn eine @odata.deltaLink URL zurückgegeben wird, gibt es keine Daten mehr über den vorhandenen Status von Gruppenobjekten. Für zukünftige Anforderungen verwendet die Anwendung die @odata.deltaLink URL, um sich über andere Änderungen an Gruppen zu informieren. Speichern Sie die deltatoken Datei, und verwenden Sie diese in der nachfolgenden Anforderungs-URL, um weitere Änderungen an Gruppen zu ermitteln.

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
    {
      "displayName":"All Employees",
      "id":"bed7f0d4-750e-4e7e-ffff-169002d06fc9"
    },
    {
      "displayName":"Remote living",
      "description":"Remote living",
      "id":"421e797f-9406-ffff-b778-4908421e3505"
    }
  ]
}

Mithilfe von @odata.deltaLink aus der letzten Antwort erhalten Sie Änderungen (Ergänzungen, Löschungen oder Aktualisierungen) an Gruppen seit der letzten Anforderung. Dazu gehören:

  • Neu erstelle Gruppenobjekte
  • Gelöschte Gruppenobjekte
  • Gruppieren von Objekten, für die eine nachverfolgte Eigenschaft geändert wurde (z. B. ein aktualisierter displayName-Wert).
  • Gruppierungsobjekte, für die Memberobjekte hinzugefügt oder entfernt wurden.
GET https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw

Wenn keine Änderungen vorgenommen werden, wird ein @odata.deltaLink ohne Ergebnisse zurückgegeben. Die Value-Eigenschaft ist ein leeres Array. Stellen Sie sicher, dass Sie den vorherigen Link in der Anwendung durch den neuen für die Verwendung in kommenden Anrufen ersetzen.

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

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

Wenn Änderungen vorgenommen werden, wird eine Sammlung geänderter Gruppen 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 bei Gruppen 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.

Beachten Sie einige Punkte zur Beispielantwort:

  • Die Objekte werden mit demselben Eigenschaftensatz zurückgegeben, der ursprünglich mit dem Abfrageparameter $select angegeben wurde.
  • Sowohl geänderte als auch unveränderte Eigenschaften sind enthalten. Die description-Eigenschaft verfügt über einen neuen Wert, während die displayName-Eigenschaft nicht geändert wurde.
  • members@delta enthält die folgenden Änderungen an der Gruppenmitgliedschaft.
    • Der Benutzer mit der ID 632f6bb2-3ec8-4c1f-9073-0027a8c6859 wurde aus der Gruppe entfernt, indem seine Mitgliedschaft entfernt wurde, wie in der @removed -Eigenschaft beschrieben. Objekte, die durch Löschen des Objekts aus einer Gruppe entfernt werden, werden von Deltaabfragen nicht erkannt.
    • Der zweite Benutzer mit der ID 37de1ae3-408f-4702-8636-20824abda004 wurde der Gruppe hinzugefügt.

Ein Gruppenobjekt kann die @removed Anmerkung in den folgenden Szenarien enthalten:

  • Wenn eine Gruppe gelöscht wird (Microsoft 365 Gruppen), enthält das Element eine Anmerkung: @removed mit dem Wert von "reason": "changed".
  • Wenn die Gruppe endgültig gelöscht wird (eine Sicherheitsgruppe oder dauerhaft eine Microsoft 365-Gruppe), enthält das Element eine Anmerkung: @removed mit dem "reason": "deleted"Wert .
  • Wenn die Gruppe erstellt oder wiederhergestellt wird, gibt es keine Anmerkung.
HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
          {
              "displayName": "TestGroup3",
              "description": "A test group for change tracking",
              "id": "2e5807ce-58f3-4a94-9b37-ffff2e085957",
              "members@delta": [
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
                      "@removed": {
                          "reason": "deleted"
                      }
                  },
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "37de1ae3-408f-4702-8636-20824abda004"
                  }
              ]
          }
      ]
}

Blättern durch Mitglieder in einer großen Gruppe

Die members@delta -Eigenschaft ist standardmäßig in Gruppenobjekten enthalten, wenn der $select Abfrageparameter nicht angegeben wird oder wenn der $select=members Parameter explizit angegeben wird. Bei Gruppen mit vielen Mitgliedern ist es möglich, dass nicht alle Mitglieder in eine einzelne Antwort passen. Implementieren Sie das folgende Muster, um solche Fälle zu behandeln.

Hinweis

Dieses Muster bezieht sich sowohl auf den anfänglichen Abruf des Gruppenzustands als auch auf nachfolgende Aufrufe zum Abrufen von Delta-Änderungen.

Angenommen, Sie führen die folgende Delta-Abfrage aus, um entweder den anfänglichen vollständigen Status von Gruppen zu erfassen oder später, um Delta-Änderungen abzurufen:

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members
  1. Microsoft Graph gibt möglicherweise eine Antwort zurück, die nur ein Gruppenobjekt mit einer großen Liste von Mitgliedern in der members@delta -Eigenschaft enthält:

Erste Seite

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "37de1ae3-408f-4702-8636-20824abda004"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}
  1. Wenn Sie dem @odata.nextLinkfolgen, erhalten Sie möglicherweise eine Antwort, die dasselbe Gruppenobjekt enthält. Die gleichen Eigenschaftswerte werden zurückgegeben, aber die members@delta Eigenschaft enthält jetzt eine andere Liste von Benutzern.

Zweite Seite

HTTP/1.1 200 OK
Content-type: application/json
{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "c08a463b-7b8a-40a4-aa31-f9bf690b9551",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "23423fa6-821e-44b2-aae4-d039d33884c2"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}
  1. Schließlich wird die gesamte Mitgliederliste auf diese Weise zurückgegeben, und andere Gruppen werden in der Antwort angezeigt.

Es wird empfohlen, die folgenden bewährten Methoden zu verwenden, um dieses Muster zu verarbeiten:

  • Folgen Sie stets @odata.nextLink und führen Sie den Zustand jeder Gruppe lokal zusammen: Wenn Sie Antworten im Zusammenhang mit der gleichen Gruppe erhalten haben, verwenden Sie diese, um in Ihrer Anwendung die komplette Mitgliederliste zu erstellen.
  • Gehen Sie nicht von einer bestimmten Sequenz der Antworten aus. Gehen Sie davon aus, dass die gleiche Gruppe an einer beliebigen Stelle in der Sequenz @odata.nextLink angezeigt werden kann und berücksichtigen Sie dies in Ihrer Zusammenführungslogik.