Abrufen inkrementeller Änderungen an Ereignissen in einer KalenderansichtGet incremental changes to events in a calendar view

Mithilfe von Delta Query können Sie neue, aktualisierte oder gelöschte Ereignisse in bestimmten Kalendern oder in einer definierten Sammlung von Ereignissen (als Kalenderansicht) im Kalender abrufen.By using delta query, you can get new, updated, or deleted events in a specified calendar(s), or within a defined collection of events (as a calendar view) in the calendar. In diesem Artikel wird Letzteres beschrieben – das Abrufen inkrementeller Änderungen an Ereignissen in einer Kalenderansicht.This article describes the latter - getting such incremental changes to events in a calendar view.

Hinweis Die Funktion des Ersteren – das Abrufen inkrementeller Änderungen an Ereignissen in einem Kalender, die nicht an einen festen Anfangs- und Endtermin gebunden sind, ist derzeit nur in der Betaversion verfügbar.Note The capability for the former - getting incremental changes to events in a calendar not bound to a fixed start and end date range - is currently available only in the beta version. Weitere Informationen finden Sie im Thema zur Delta-Funktion.For more information, see delta function.

Eine Kalenderansicht ist eine Sammlung von Ereignissen in einen Datums-/Uhrzeitbereich (../me/calendarview) aus dem Standardkalender oder aus einem anderen angegebenen Kalender eines Benutzers oder aus einem Gruppenkalender.A calendar view is a collection of events in a date/time range (../me/calendarview) from the default calendar or some other specified calendar of a user, or from a group calendar. Die zurückgegebenen Ereignisse können einzelne Instanzen, Vorkommen und Ausnahmen einer Serie enthalten.The returned events may include single instances, or occurrences and exceptions of a recurring series. Mit Delta-Daten können Sie einen lokalen Speicher für Ereignisse eines Benutzers pflegen und synchronisieren, ohne dass Sie jedes Mal den gesamten Ereignissatz vom Server abrufen müssen.The delta data enables you to maintain and synchronize a local store of a user's events, without having to fetch the entire set of the user's events from the server every time.

Die Delta-Abfrage unterstützt die vollständige Synchronisierung, die alle Ereignisse in der angegebenen Kalenderansicht abruft, und die inkrementelle Synchronisierung, die nur die Ereignisse abruft, die seit der letzten Synchronisierung in der Kalenderansicht geändert wurden. In der Regel führen Sie zunächst eine vollständige Synchronisierung durch und rufen anschließend regelmäßig inkrementelle Änderungen an dieser Kalenderansicht ab.Delta query supports both full synchronization that retrieves all the events in the specified calendar view, and incremental synchronization that retrieves those events that have changed in the calendar view since the last synchronization. Typically, you would do an initial full synchronization, and subsequently, get incremental changes to that calendar view periodically.

Nachverfolgen von Ereignisänderungen in einer KalenderansichtTrack event changes in a calendar view

Delta-Abfragen für Ereignisse in einer Kalenderansicht sind spezifisch für einen Kalender und Datums-/Uhrzeitbereich, die Sie angeben.Delta query for events in a calendar view is specific to a calendar and date/time range that you specify. Um die Änderungen in mehreren Kalendern nachzuverfolgen, müssen Sie jeden Kalender einzeln verfolgen.To track the changes in multiple calendars, you need to track each calendar individually.

Das Nachverfolgen von Ereignisänderungen in einer Kalenderansicht ist in der Regel eine Runde aus einer oder mehreren GET-Anforderungen mit der Delta-Funktion.Tracking event changes in a calendar view typically is a round of one or more GET requests with the delta function. Die ursprüngliche GET-Anforderung wird ähnlich wie das Auflisten einer Kalenderansicht durchgeführt, außer dass die folgende delta-Funktion eingeschlossen wird.The initial GET request is very much like the way you list a calendarView, except that you include the delta function. Im Folgenden finden Sie die anfängliche GET-Deltaanforderung einer Kalenderanzeige im Standardkalender des angemeldeten Benutzers:The following is the initial GET delta request of a calendar view in the signed-in user's default calendar:

GET /me/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}

Eine GET-Anforderung mit der delta-Funktion gibt Folgendes zurück:A GET request with the delta function returns either:

  • nextLink (mit einer URL mit einem delta-Funktionsaufruf und einem skipToken) oderA nextLink (that contains a URL with a delta function call and a skipToken), or
  • deltaLink (mit einer URL mit einem delta-Funktionsaufruf und einem deltaToken).A deltaLink (that contains a URL with a delta function call and deltaToken).

Diese Token sind Statustoken, die die Parameter startDateTime und endDateTime sowie alle anderen Abfrageparameter in der GET-Anforderung der ursprünglichen Delta-Abfrage codieren.These tokens are state tokens which encode the startDateTime and endDateTime parameters, and any other query parameter in your initial delta query GET request. Diese Parameter müssen in nachfolgenden Anforderungen nicht berücksichtigt werden, da Sie in den Token codiert sind.You do not need to include these parameters in subsequent requests as they are encoded in the tokens.

Zustandstoken sind für den Client nicht transparent. Um mit einer Änderungsnachverfolgung fortzufahren, kopieren Sie die von der letzten GET-Anforderung zurückgegebene nextLink- oder deltaLink-URL einfach und wenden sie auf den nächsten delta-Funktionsaufruf für dieselbe Kalenderansicht an. deltaLink (in einer Antwort zurückgegeben), bedeutet, dass die aktuelle Runde der Änderungsnachverfolgung abgeschlossen ist. Sie können die deltaLink-URL für die nächste Runde speichern und verwenden.State tokens are completely opaque to the client. To proceed with a round of change tracking, simply copy and apply the nextLink or deltaLink URL returned from the last GET request to the next delta function call for that same calendar view. A deltaLink returned in a response signifies that the current round of change tracking is complete. You can save and use the deltaLink URL when you begin the next round.

Im Beispiel unten finden Sie Informationen zur Verwendung der nextLink- und deltaLink-URLs.See the example below to learn how to use these nextLink and deltaLink URLs.

Verwenden von Abfrageparametern in einer Delta-Abfrage für eine KalenderansichtUse query parameters in a delta query for calendar view

  • Schließen Sie die Parameter startDateTime und endDateTime ein, um einen Datums-/Uhrzeitbereich für Ihre Kalenderansicht zu definieren.Include the startDateTime and endDateTime parameters to define a date/time range for your calendar view.
  • $select wird nicht unterstützt.$select is not supported.

Optionaler AnforderungsheaderOptional request header

Jede GET-Anforderung der Delta-Abfrage gibt eine Sammlung aus einem oder mehreren Ereignissen in der Antwort zurück.Each delta query GET request returns a collection of one or more events in the response. Sie können optional den Anforderungsheader, Prefer: odata.maxpagesize={x}, angeben, um die maximale Anzahl an Ereignissen in einer Antwort festzulegen.You can optionally specify the request header, Prefer: odata.maxpagesize={x}, to set the maximum number of events in a response.

Beispiel für die Synchronisierung von Ereignissen in einer KalenderansichtExample to synchronize events in a calendar view

Das folgende Beispiel zeigt eine Reihe von 3 Anforderungen zum Synchronisieren des Standardkalenders eines Benutzers in einem bestimmten Zeitbereich. Es gibt 5 Ereignisse in dieser Kalenderansicht.The following example shows a series of 3 requests to synchronize the user's default calendar in a specific time range. There are 5 events in that calendar view.

Aus Platzgründen wird in den Beispielantworten nur eine Untergruppe der Eigenschaften eines Ereignisses angezeigt. In einem tatsächlichen Aufruf werden die meiste Ereigniseigenschaften zurückgegeben.For brevity, the sample responses show only a subset of the properties for an event. In an actual call, most event properties are returned.

Sehen Sie sich auch an, was Sie in der nächsten Runde tun werden.See also what you'll do in the next round.

Schritt 1: Beispiel für ursprüngliche AnforderungStep 1: sample initial request

In diesem Beispiel wird die angegebene Kalenderansicht im Standardkalender des angemeldeten Benutzers zum ersten Mal synchronisiert, sodass die ursprüngliche Synchronisierungsanforderung kein Zustandstoken enthält.In this example, the specified calendar view in the signed-in user's default calendar is being synchronized for the first time, so the initial sync request does not include any state token. In dieser Runde werden alle Ereignisse in dieser Kalenderansicht zurückgegeben.This round will return all the events in that calendar view.

Die erste Anforderung gibt Folgendes an:The first request specifies the following:

  • Datum-/Uhrzeitwerte für die Parameter startDateTime und endDateTime.Date/time values for the startDateTime and endDateTime parameters.
  • Den optionalen Anforderungsheader, odata.maxpagesize, der gleichzeitig 2 Ereignisse zurückgibt.The optional request header, odata.maxpagesize, returning 2 events at a time.
GET https://graph.microsoft.com/v1.0/me/calendarView/delta?startdatetime=2016-12-01T00:00:00Z&enddatetime=2016-12-30T00:00:00Z HTTP/1.1
Prefer: odata.maxpagesize=2

Beispiel für ursprüngliche AntwortSample initial response

Die Antwort enthält zwei Ereignisse und einen @odata.nextLink-Antwortheader mit einem skipToken. Die nextLink-URL gibt an, dass in der Kalenderansicht weitere Ereignisse abgerufen werden können.The response includes two events and a @odata.nextLink response header with a skipToken. The nextLink URL indicates there are more events in the calendar view to get.

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

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmcCM996atia_s",
    "value":[
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvIQ==\"",
            "subject":"Plan shopping list",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-09T20:30:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-09T22:00:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },      
            "id":"AAMkADNVxRAAA="
        },
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvIg==\"",
            "subject":"Pick up car",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-10T01:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-10T02:00:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADVxSAAA="
        }
    ]
}

Schritt 2: Beispiel für zweite AnforderungStep 2: sample second request

Die zweite Anforderung gibt die aus der vorherigen Antwort zurückgegebene nextLink-URL an. Beachten Sie, dass sie nicht dieselben Parameter startDateTime und endDateTime wie in der ursprünglichen Anforderung angeben muss, da das skipToken in der nextLink-URL diese codiert und einschließt.The second request specifies the nextLink URL returned from the previous response. Notice that it no longer has to specify the same startDateTime and endDateTime parameters as in the initial request, as the skipToken in the nextLink URL encodes and includes them.

GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmcCM996atia_s HTTP/1.1
Prefer: odata.maxpagesize=2

Beispiel für zweite AntwortSample second response

Die zweite Antwort gibt die nächsten 2 Ereignisse in der Kalenderansicht und ein weiteres nextLink, was bedeutet, dass weitere abzurufende Ereignisse in der Kalenderansicht vorhanden sind.The second response returns the next 2 events in the calendar view and another nextLink, indicating there are more events to get from the calendar view.

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

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmci39OQxqJrxK4",
    "value":[
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvIw==\"",
            "subject":"Get food",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-10T19:30:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-10T21:30:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADVxTAAA="
        },
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvJA==\"",
            "subject":"Prepare food",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-10T22:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-11T00:00:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADVxUAAA="
        }
    ]
}

Schritt 3: Beispiel für dritte AnforderungStep 3: sample third request

Die dritte Anforderung verwendet weiterhin das neueste aus der letzten Synchronisierungsanforderung zurückgegebene nextLink.The third request continues to use the latest nextLink returned from the last sync request.

GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmci39OQxqJrxK4 HTTP/1.1
Prefer: odata.maxpagesize=2

Beispiel für dritte und letzte AntwortSample third and final response

Die dritte Antwort gibt das einzige in dem Ordner verbleibende Ereignis in der Kalenderansicht sowie eine deltaLink-URL zurück, was bedeutet, dass die Synchronisierung für diese Kalenderansicht momentan abgeschlossen ist. Speichern und verwenden Sie die deltaLink-URL, um diese Kalenderansicht in der nächsten Runde zu synchronisieren.The third response returns the only remaining event in the calendar view, and a deltaLink URL which indicates synchronization is complete for this calendar view. Save and use the deltaLink URL to synchronize that calendar view in the next round.

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

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.deltaLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$deltatoken=R0usmcMDNGg0J1E",
    "value":[
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAALZu97g==\"",
            "subject":"Rest!",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-12T02:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-12T07:30:00.0000000",
                "timeZone":"UTC"
            },
            "location":{
                "displayName":"Home"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADj1HuAAA="
        }
    ]
}

Die nächste Runde: Beispiel für erste AnforderungThe next round: sample first request

Mit dem deltaLink aus der letzten Anforderung in der letzten Runde können Sie nur die Ereignisse abrufen, die sich seitdem in dieser Kalenderansicht geändert haben (durch Hinzufügung, Löschung oder Aktualisierung). Ihre erste Anforderung in der nächsten Runde sieht folgendermaßen aus, sofern Sie die gleiche maximale Seitengröße in der Antwort beibehalten möchten:Using the deltaLink from the last request in the last round, you will be able to get only those events that have changed (by being added, deleted, or updated) in that calendar view since then. Your first request in the next round will look like the following, assuming you prefer to keep the same maximum page size in the response:

GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$deltatoken=R0usmcMDNGg0J1E HTTP/1.1
Prefer: odata.maxpagesize=2

Die nächste Runde: Beispiel für erste AntwortThe next round: sample first response

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

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.deltaLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$deltatoken=R0usmcFuQtZdtpk4",
    "value":[
        {
            "@odata.type": "#microsoft.graph.event",
            "id": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS04OGQLkRkXbBznTvAADb6ytyAAA=",
            "@removed": {
                "reason": "deleted"
            }
        },
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAALZu97w==\"",
            "subject":"Attend service",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-25T06:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-25T07:30:00.0000000",
                "timeZone":"UTC"
            },
            "location":{
                "displayName":"Chapel of Saint Ignatius",
                "address":{
                    "street":"900 Broadway",
                    "city":"Seattle",
                    "state":"WA",
                    "countryOrRegion":"United States",
                    "postalCode":""
                },
                "coordinates":{
                    "latitude":47.6105,
                    "longitude":-122.321
                }
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADj1HvAAA="
        }
    ]
}

Siehe auchSee also