Freigeben über


Site: delta

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

Ein Deltafunktionsaufruf für Standorte ähnelt einer GET-Anforderung, mit der Ausnahme, dass Sie durch die entsprechende Anwendung von Zustandstoken in einem oder mehreren dieser Aufrufe inkrementelle Änderungen an den Standorten abfragen können. Es ermöglicht Ihnen, einen lokalen Speicher der Websites eines Benutzers zu verwalten und zu synchronisieren, ohne jedes Mal alle Websites vom Server abrufen zu müssen. Die Anwendung ruft die API ohne Angabe von Parametern auf. Der Dienst beginnt mit dem Aufzählen von Websites und gibt Seiten mit Änderungen an diesen Websites zurück, begleitet von einem @odata.nextLink oder einem @odata.deltaLink. Ihre Anwendung sollte weiterhin Aufrufe mit dem @odata.nextLink ausführen, bis in der Antwort ein @odata.deltaLink vorhanden ist.

Nachdem Sie alle Änderungen erhalten haben, können Sie sie auf Ihren lokalen Zustand anwenden. Um zukünftige Änderungen zu überwachen, rufen Sie die Delta-API mithilfe der @odata.deltaLink in der vorherigen Antwort auf.

Alle als gelöscht markierten Ressourcen sollten aus Ihrem lokalen Zustand entfernt werden.

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/delta

Abfrageparameter

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

Parameter Typ Beschreibung
token Zeichenfolge Wenn der Wert ist latest, gibt der Aufruf eine leere Antwort mit dem neuesten Deltatoken zurück. Wenn der Wert ein vorheriges Deltatoken ist, gibt der Aufruf den neuen Zustand zurück, seit dieses Token ausgestellt wurde.

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 OKAntwortcode und eine Auflistung von site-Objekten im Antworttext zurück.

Zusätzlich zur Auflistung von Websiteobjekten 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 von @odata.nextLink zurückgegeben wird, nachdem 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 Serverzustand geändert hat und ein neues Token erforderlich ist.

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

Fehlertyp Anweisungen
resyncChangesApplyDifferences Ersetzen Sie alle lokalen Standorte durch die Versionen des Servers (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 Websites hoch, die der Dienst nicht zurückgegeben hat, und laden Sie websites hoch, die sich von den Versionen des Servers unterscheiden. Behalten Sie beide Kopien bei, wenn Sie nicht sicher sind, welche kopie aktueller ist.

weitere Informationen finden Sie unter Microsoft Graph-Fehlerantworten und -Ressourcentypen.

Beispiele

Beispiel 1: Ursprüngliche Anforderung

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

Anforderung

Das folgende Beispiel zeigt die anfängliche Anforderung.

GET https://graph.microsoft.com/v1.0/sites/delta

Antwort

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

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

{
  "value": [
    {
      "id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,712a596e-90a1-49e3-9b48-bfa80bee8740",
      "name": "teamSiteA"
    },
    {
      "id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,0271110f-634f-4300-a841-3a8a2e851851",
      "name": "teamSiteB"
    },
    {
      "id": "contoso.sharepoint.com,da60e844-ba1d-49bc-b4d4-d5e36bae9019,0271110f-634f-4300-a841-3a8a2e851851",
      "name": "teamSiteC"
    }
  ],
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/sites/delta?token=1230919asd190410jlka"
}

Beispiel 2: Letzte Seitenanforderung

Das folgende Beispiel zeigt eine Anforderung, die auf die letzte Seite in einer Gruppe zugreift, und wie Sie diese API aufrufen, um Ihren lokalen Zustand zu aktualisieren.

Anforderung

Das folgende Beispiel zeigt eine Anforderung nach der ersten Anforderung.

GET https://graph.microsoft.com/v1.0/sites/delta?token=1230919asd190410jlka

Antwort

Das folgende Beispiel zeigt die Antwort, die angibt, dass der Standort mit dem Namen All Company zwischen der ursprünglichen Anforderung und dieser Anforderung gelöscht wurde, um den lokalen Zustand zu aktualisieren.

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/sites/delta?$deltatoken=b2vm2fSuZ-V_1Gdq4ublGPD4lReifRNHYMGxkFf0yz2fTqr9U6jMyWv8hihThODJCO_5I7JbpAFLQAIOUzYXhCPl0jlQdjTC1o24iBe81xQyAWJOiP3q1xyMKjlfZUawWok3Njc_LIrrSgrdSydhsVCL6XYpRkYGJ9JDYxFMiJw2vUs1QC_S0cW6hqYQnOimeA918dQZwD8pJI9oUJryV2Ow-7Dj9p18p1I6pFg044k.xipVdgMKlOFIlXzPipsKzlFJbYUTD1sGiFiPe7uZA7Q",
    "value": [
        {
            "createdDateTime": "2024-03-11T02:36:04Z",
            "name": "All Company",
            "displayName": "All Company",
            "isPersonalSite": false,
            "id": "bd565af7-7963-4658-9a77-26e11ac73186",
            "root": {}
        }
    ]
}

In einigen Szenarien möchten Sie möglicherweise den aktuellen deltaLink Wert anfordern, ohne zuerst alle Websites, Listen und Websites aufzulisten. Dies kann nützlich sein, wenn Ihre App nur über Änderungen informiert werden möchte und keine Informationen zu vorhandenen Websites benötigt. Rufen delta Sie mit dem Abfragezeichenfolgenparameter ?token=latestauf, um die neueste deltaLinkabzurufen.

Anmerkung: Wenn Sie eine vollständige lokale Darstellung der Ressourcen beibehalten möchten, müssen Sie für die anfängliche Enumeration verwenden delta . Die Verwendung von delta ist die einzige Möglichkeit, um sicherzustellen, dass Sie alle benötigten Daten gelesen haben.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

GET https://graph.microsoft.com/v1.0/sites/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/v1.0/sites/delta?token=1230919asd190410jlka"
}

Siehe auch