Freigeben über


listItem: delta

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Rufen Sie neu erstellte, aktualisierte oder gelöschte Listenelemente ab, ohne die gesamte Elementsammlung vollständig lesen zu müssen.

Die App ruft zunächst delta ohne Parameter auf. Der Dienst beginnt mit dem Aufzählen der Hierarchie der Liste und gibt Elementseiten und entweder einen @odata.nextLink oder einen @odata.deltaLink zurück. Ihre App sollte weiterhin mit dem @odata.nextLink aufrufen, bis ein @odata.deltaLink zurückgegeben wird.

Nachdem Sie alle Änderungen erhalten haben, können Sie sie auf Ihren lokalen Zustand anwenden. Um in Zukunft nach Änderungen zu suchen, rufen Sie delta erneut mit der @odata.deltaLink aus der vorherigen Antwort auf.

Der „delta“-Feed zeigt den aktuellen Zustand jedes Elements, nicht jede Änderung. Wenn ein Element zweimal umbenannt wurde, wird es nur einmal mit dem neuesten Namen angezeigt. Dasselbe Element kann aus verschiedenen Gründen mehrmals in einem Deltafeed angezeigt werden. Verwenden Sie das letzte Vorkommen in der Auflistung.

Gelöschte Elemente werden mit dem gelöschten Facet zurückgegeben. Deleted gibt an, dass das Element gelöscht wurde und nicht wiederhergestellt werden kann. Elemente mit dieser Eigenschaft sollten aus Ihrem lokalen Zustand entfernt werden.

Anmerkung: Sie sollten einen Ordner nur lokal löschen, wenn er nach dem Synchronisieren aller Änderungen leer ist.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Sites.Read.All Sites.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Sites.Read.All Sites.ReadWrite.All

HTTP-Anforderung

GET /sites/{siteId}/lists/{listId}/items/delta

Abfrageparameter

In der Anforderungs-URL können Sie den folgenden optionalen Abfrageparameter einschließen.

Parameter Typ Beschreibung
token Zeichenfolge Wenn nicht angegeben, listet den aktuellen Status der Hierarchie auf. Gibt latesteine leere Antwort mit dem neuesten Deltatoken zurück. Wenn ein vorheriges Deltatoken vorhanden ist, gibt seit diesem Token einen neuen Zustand zurück.

Diese Methode unterstützt auch die $selectOData-Abfrageparameter , $expandund $top zum Anpassen der Antwort.

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.

Anforderungstext

Geben Sie keinen Anforderungstext für diese Methode an.

Antwort

Bei Erfolg gibt diese Methode einen 200 OK-Antwortcode und eine Sammlung von listItem-Objekten im Antworttext zurück.

Zusätzlich zu einer Auflistung von listItem-Objekten enthält die Antwort auch eine der folgenden Eigenschaften.

Name Wert Beschreibung
@odata.nextLink URL Eine URL zum Abrufen der nächsten verfügbaren Seite mit Änderungen, wenn weitere Änderungen in der aktuellen Gruppe vorhanden sind.
@odata.deltaLink URL Eine URL, die anstelle eines @odata.nextLink zurückgegeben wird, sobald alle aktuellen Änderungen zurückgegeben wurden. Verwenden Sie diese Eigenschaft, um die nächsten Änderungen in der Zukunft zu lesen.

In einigen Fällen gibt der Dienst einen 410 Gone Antwortcode mit einer Fehlerantwort zurück, die einen der folgenden Fehlercodes enthält, und einen Location Header, der einen neuen enthält, der eine neue nextLink Deltaaufzählung startet. Dies tritt auf, wenn der Dienst keine Liste der Änderungen für ein bestimmtes Token bereitstellen kann. Beispielsweise, wenn ein Client versucht, ein altes Token wiederzuverwenden, nachdem die Verbindung für längere Zeit getrennt wurde, oder wenn sich der Serverstatus geändert hat und ein neues Token erforderlich ist.

Nachdem die vollständige Enumeration abgeschlossen ist, vergleichen Sie die zurückgegebenen Elemente mit Ihrem lokalen Zustand, und befolgen Sie die Anweisungen basierend auf dem Fehlertyp.

Fehlertyp Anweisungen
resyncChangesApplyDifferences Ersetzen Sie alle lokalen Elemente durch die Versionen vom Server (einschließlich Löschvorgängen), wenn Sie sicher sind, dass der Dienst bei der letzten Synchronisierung mit Ihren lokalen Änderungen auf dem neuesten Stand war. Laden Sie alle lokalen Änderungen hoch, die dem Server noch nicht bekannt sind.
resyncChangesUploadDifferences Laden Sie alle lokalen Elemente hoch, die der Dienst nicht zurückgegeben hat, und laden Sie alle Elemente hoch, die sich von den Versionen des Servers unterscheiden. Behalten Sie beide Kopien bei, wenn Sie nicht sicher sind, welche kopie aktueller ist.

Zusätzlich zu den Neusynchronisierungsfehlern und weitere Informationen zur Rückgabe von Fehlern finden Sie unter Microsoft Graph-Fehlerantworten und -Ressourcentypen.

Beispiele

Beispiel 1: Ursprüngliche Anforderung

Das folgende Beispiel zeigt eine anfängliche Anforderung und wie Sie diese API aufrufen, um Ihren lokalen Zustand einzurichten.

Anforderung

Das folgende Beispiel zeigt eine anfängliche Anforderung.

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta

Antwort

Das folgende Beispiel zeigt die Antwort, die die erste Seite der Änderungen und die @odata.nextLink-Eigenschaft enthält, die angibt, dass keine weiteren Elemente in der aktuellen Gruppe von Elementen verfügbar sind. Ihre App sollte weiterhin den URL-Wert von @odata.nextLink anfordern, bis alle Seiten mit Elementen abgerufen wurden.

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

{
  "value": [
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
      "id": "1",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "1",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Folder"
      }
    },
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC067},756\"",
      "id": "2",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemA.txt",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "2",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      }
    },
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC068},756\"",
      "id": "3",
      "lastModifiedDateTime": "2021-10-14T23:27:27Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestItemB.txt",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "3",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      }
    }
  ],
  "@odata.nextLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

Beispiel 2: Letzte Seitenanforderung

Das folgende Beispiel zeigt eine Anforderung, die die letzte Seite in einem Satz abruft, und wie Diese API aufgerufen wird, um Ihren lokalen Zustand zu aktualisieren.

Anforderung

Das folgende Beispiel zeigt eine Anforderung nach der ersten Anforderung.

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka

Antwort

Das folgende Beispiel zeigt die Antwort, die angibt, dass das Element mit dem Namen TestItemB.txt gelöscht wurde und das Element TestFolder entweder zwischen der ursprünglichen Anforderung und dieser Anforderung hinzugefügt oder geändert wurde, um den lokalen Zustand zu aktualisieren.

Die letzte Seite der Elemente enthält die eigenschaft @odata.deltaLink , die die URL bereitstellt, die später zum Abrufen von Änderungen seit dem aktuellen Elementsatz verwendet werden kann.

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

{
  "value": [
    {
      "createdDateTime": "2020-06-02T22:46:58Z",
      "eTag": "\"{12AD05BB-59B8-43AA-9456-77C44E9BC066},756\"",
      "id": "1",
      "lastModifiedDateTime": "2016-03-21T20:01:37Z",
      "webUrl": "http://contoso.sharepoint.com/Shared%20Documents/TestFolder",
      "createdBy": {
        "user": {
          "displayName": "John doe"
        }
      },
      "parentReference": {
        "id": "1",
        "path": "Shared%20Documents",
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Folder"
      }
    },
    {
      "id": "3",
      "parentReference": {
        "siteId": "12AD05BB-59B8-43AA-9456-77C44E9BC066"
      },
      "contentType": {
        "id": "0x00123456789abc",
        "name": "Document"
      },
      "deleted": {
        "state": "deleted"
      }
    }
  ],
  "@odata.deltaLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}

In einigen Szenarien können Sie den aktuellen deltaLink Wert anfordern, ohne zuvor alle Elemente in der Liste aufzuzählen. Dies kann nützlich sein, wenn Ihre App nur über Änderungen informiert werden möchte und keine Informationen zu vorhandenen Elementen benötigen. Rufen delta Sie mit dem Abfragezeichenfolgenparameter ?token=latestauf, um die neueste deltaLinkabzurufen.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

GET https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=latest

Antwort

Das folgende Beispiel zeigt die Antwort.

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

{
  "value": [ ],
  "@odata.deltaLink": "https://graph.microsoft.com/beta/sites/contoso.sharepoint.com,2C712604-1370-44E7-A1F5-426573FDA80A,2D2244C3-251A-49EA-93A8-39E1C3A060FE/lists/22e03ef3-6ef4-424d-a1d3-92a337807c30/items/delta?token=1230919asd190410jlka"
}