event: delta

  • Artikel

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.

Ruft eine Reihe von Ereignisressourcen ab, die in einem oder mehreren Kalendern hinzugefügt, gelöscht oder aktualisiert wurden.

Sie können bestimmte Typen dieser inkrementellen Änderungen in den Ereignissen in allen Kalendern eines Postfachs oder in einem bestimmten Kalender oder in einer Ereignissammlung einer calendarView (bereich von Ereignissen, die durch Start- und Enddatum definiert werden) eines Kalenders abrufen. Der Kalender kann der Standardkalender oder ein anderer angegebener Kalender des Benutzers sein. Im Fall von inkrementellen Änderungen an calendarView kann der Kalender auch ein Gruppenkalender sein.

Die Synchronisierung von Ereignissen in einem kalender oder calendarView-Objekt in einem lokalen Speicher umfasst in der Regel mehrere Deltafunktionsaufrufe. Der erste Aufruf ist eine vollständige Synchronisierung. Jeder nachfolgende Delta-Aufruf in derselben Runde erhält die inkrementellen Änderungen (Hinzufügungen, Löschungen oder Aktualisierungen). Auf diese Weise können Sie einen lokalen Ereignisspeicher im angegebenen Kalender verwalten und synchronisieren, ohne jedes Mal alle Ereignisse dieses Kalenders vom Server abrufen zu müssen.

In der folgenden Tabelle sind die Unterschiede zwischen der Delta-Funktion für Ereignisse und der Delta-Funktion in einer calendarView in einem Kalender aufgeführt.

Delta-Funktion für Ereignisse Delta-Funktion in calendarView
Ruft inkrementelle Änderungen aller Ereignisse in einem Kalender ab, die nicht durch einen Anfangs- und Enddatumsbereich begrenzt sind. Alternativ können Sie inkrementelle Änderungen der Ereignisse in einem Kalender abrufen, der durch eine Startzeit begrenzt ist und am oder nach diesem Datum/dieser Uhrzeit beginnt. Ruft inkrementelle Änderungen von Ereignissen innerhalb des Start- und Enddatums/der Uhrzeit der calendarView ab.
Gibt aus Leistungsgründen nur einen begrenzten Satz von Ereigniseigenschaften zurück. Client, der anschließend GET /events/{id} verwendet werden soll, um ereignisse zu erweitern. Die serverseitige Erweiterung gibt einen umfassenderen Satz von Ereigniseigenschaften zurück.
Die Antwort umfasst einzelinstanzen und serienserien master. Die Antwort umfasst einzelne Instanzen sowie Vorkommen und Ausnahmen von Serienserien.
Gilt für Ereignisse in Benutzerkalendern, aber nicht für Gruppenkalender. Gilt für Ereignisse in Benutzer- und Gruppenkalendern.
Derzeit nur in der Betaversion verfügbar. Verfügbar in den Versionen v1.0 und Beta.

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) Calendars.ReadBasic Calendars.Read, Calendars.ReadWrite
Delegiert (persönliches Microsoft-Konto) Calendars.ReadBasic Calendars.Read, Calendars.ReadWrite
Anwendung Calendars.Read Calendars.ReadBasic, Calendars.ReadWrite

HTTP-Anforderung

Dieser Abschnitt zeigt die HTTP-Anforderungssyntax für den anfänglichen Delta-Funktionsaufruf , um eine vollständige Synchronisierung zu starten, die alle Ereignisse im angegebenen Kalender oder der angegebenen Kalenderansicht abruft. Diese Syntax enthält keine Zustandstoken.

Die abfrage-URL, die in einer @odata.nextLink oder @odata.deltaLink einer erfolgreichen Antwort zurückgegeben wird, enthält ein Zustandstoken. Verwenden Sie für jeden nachfolgenden Delta-Funktionsaufruf die Abfrage-URL in einem @odata.nextLink oder @odata.deltaLink davor.

Delta-Funktion für Ereignisse in einem Benutzerkalender (Vorschau)

Wenden Sie die Delta-Funktion auf alle Ereignisse oder Ereignisse an, die an oder nach einem bestimmten Datum/einer bestimmten Uhrzeit in den angegebenen Benutzerkalendern beginnen:

  • So rufen Sie inkrementelle Änderungen aller Ereignisse oder von Ereignissen ab oder nach dem angegebenen Datum/der angegebenen Uhrzeit im Postfach des Benutzers ab:

    GET /me/events/delta
GET /users/{id | userPrincipalName}/events/delta

GET /me/events/delta?startDateTime={start_datetime}
GET /users/{id | userPrincipalName}/events/delta?startDateTime={start_datetime}

  • So rufen Sie inkrementelle Änderungen aller Ereignisse oder von Ereignissen ab oder nach dem angegebenen Datum/der angegebenen Uhrzeit im Standardkalender des Benutzers ab:

    GET /me/calendar/events/delta
GET /users/{id | userPrincipalName}/calendar/events/delta

GET /me/calendar/events/delta?startDateTime={start_datetime}
GET /users/{id | userPrincipalName}/calendar/events/delta?startDateTime={start_datetime}

  • So rufen Sie inkrementelle Änderungen aller Ereignisse oder von Ereignissen ab oder nach dem angegebenen Datum/der angegebenen Uhrzeit im angegebenen Benutzerkalender ab:

    GET /me/calendars/{id}/events/delta
GET /users/{id | userPrincipalName}/calendars/{id}/events/delta

GET /me/calendars/{id}/events/delta?startDateTime={start_datetime}
GET /users/{id | userPrincipalName}/calendars/{id}/events/delta?startDateTime={start_datetime}

  • So rufen Sie inkrementelle Änderungen für alle Ereignisse oder ereignisse ab oder nach dem angegebenen Datum/der angegebenen Uhrzeit in der angegebenen Kalendergruppe und dem angegebenen Kalender ab:

    GET /me/calendarGroups/{id}/calendars/{id}/events/delta
GET /users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}/events/delta

GET /me/calendarGroups/{id}/calendars/{id}/events/delta?startDateTime={start_datetime}
GET /users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}/events/delta?startDateTime={start_datetime}

Delta-Funktion für calendarView in einem Benutzerkalender

Wenden Sie die Delta-Funktion auf einen Bereich von Ereignissen an, die durch Start- und Enddatum/-uhrzeit im angegebenen Benutzerkalender getrennt sind:

  • So rufen Sie inkrementelle Änderungen in einer Kalenderansicht des Standardkalenders des Benutzers ab:

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

  • So rufen Sie inkrementelle Änderungen in einer Kalenderansicht des angegebenen Benutzerkalenders ab:

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

Delta-Funktion für calendarView in einem Gruppenkalender

  • So rufen Sie inkrementelle Änderungen in einer Kalenderansicht des Kalenders einer Gruppe ab: 
    GET /groups/{id}/calendarView?startDateTime={start_datetime}&endDateTime={end_datetime}

Abfrageparameter

Das Nachverfolgen von Änderungen verursacht eine Runde von einem oder mehreren Deltafunktionsaufrufen. Wenn Sie Abfrageparameter (außer $deltatoken und $skiptoken) verwenden, müssen Sie sie in der ursprünglichen Delta-Anforderung angeben. Microsoft Graph codiert automatisch alle angegebenen Parameter in den Tokenteil der in der Antwort enthaltenen @odata.nextLink- oder @odata.deltaLink-URL. Sie müssen alle gewünschten Abfrageparameter nur einmal im Vorfeld angeben. Kopieren Sie in nachfolgenden Anforderungen einfach die - oder @odata.deltaLink -@odata.nextLinkURL aus der vorherigen Antwort, und wenden Sie sie an, da diese URL bereits die codierten gewünschten Parameter enthält.

Abfrageparameter Typ Beschreibung
startDateTime String Startdatum und -uhrzeit des Zeitraums, dargestellt im ISO 8601-Format. Beispiel: "2019-11-08T19:00:00-08:00".
Die Zeitzone wird im Zeitzonenoffsetteil des Parameterwerts angegeben und wird nicht vom Prefer: outlook.timezone Header beeinflusst, falls vorhanden. Wenn im Wert kein TimeZone-Offset enthalten ist, wird er als UTC interpretiert.
Optional für Delta für Ereignisse in einem Kalender.
Erforderlich für Delta in calendarView.
endDateTime String Enddatum und -uhrzeit des Zeitbereichs, dargestellt im ISO 8601-Format. Beispiel: "2019-11-08T20:00:00-08:00".
Die Zeitzone wird im Zeitzonenoffsetteil des Parameterwerts angegeben und wird nicht vom Prefer: outlook.timezone Header beeinflusst, falls vorhanden. Wenn im Wert kein TimeZone-Offset enthalten ist, wird er als UTC interpretiert.
Wird von Delta für Ereignisse in einem Kalender nicht unterstützt.
Erforderlich für Delta in calendarView.
$deltatoken string Ein Zustandstoken, das in der @odata.deltaLink URL des vorherigen Delta-Funktionsaufrufs für dieselbe Kalenderansicht zurückgegeben wird und den Abschluss dieser Änderungsnachverfolgungsrunde angibt. Speichern Und anwenden Sie die gesamte @odata.deltaLink URL einschließlich dieses Tokens in der ersten Anforderung der nächsten Änderungsnachverfolgungsrunde für diese Kalenderansicht.
$skiptoken string Ein Statustoken, das in der @odata.nextLink-URL des vorhergehenden delta-Funktionsaufrufs zurückgegeben wird und anzeigt, dass in derselben Kalenderansicht weitere Änderungen zum Nachverfolgen vorliegen.

OData-Abfrageparameter

  • Sie können erwarten, dass ein Delta-Funktionsaufruf auf einer calendarView die gleichen Eigenschaften zurückgibt, die Sie normalerweise von einer GET /calendarView Anforderung erhalten würden. Sie können $select nicht verwenden, um nur eine Teilmenge dieser Eigenschaften zu erhalten.

  • Die Delta-Funktion unterstützt nicht die folgenden Abfrageparameter für Ereignisse in einem Benutzerkalender oder Ereignisse in einer calendarView: $expand, $filter,$orderby$search , und $select.

Anforderungsheader

Name Typ Beschreibung
Authorization string Bearer {token}. Erforderlich.
Content-Type string application/json. Erforderlich.
Prefer string odata.maxpagesize={x}. Optional.
Prefer string outlook.timezone={Zeitzonenzeichenfolge}. Optional, UTC wird angenommen, wenn sie nicht vorhanden ist.

Antwort

Delta-Funktion für Ereignisse (Vorschau)

Wenn die Methode erfolgreich verläuft, werden der 200 OK Antwortcode und eine Ereignissammlung im Antworttext zurückgegeben. Jedes Ereignis in der Antwort enthält aus Leistungsgründen nur die Eigenschaften id, type, start und end . Verwenden Sie GET /events/{id} anschließend , um alle Ereignisse aus der Antwort zu erweitern.

Delta-Funktion in calendarView

Wenn die Methode erfolgreich verläuft, werden der 200 OK Antwortcode und eine Ereignissammlung im Antworttext zurückgegeben.

Erwarten Sie, dass Sie alle Eigenschaften abrufen, die Sie normalerweise von einer GET /calendarView Anforderung erhalten würden.

Innerhalb einer Runde von Delta-Funktionsaufrufen, die durch den Datumsbereich einer calendarView gebunden sind, finden Sie möglicherweise einen Delta-Aufruf, der zwei Arten von Ereignissen unter @removed mit dem Grund deleted zurückgibt:

  • Ereignisse, die innerhalb der Datumsangaben liegen und die seit dem letzten Delta-Aufruf gelöscht worden sind.
  • Ereignisse, die außerhalb der Datumsangaben liegen und die seit dem letzten Delta-Aufruf hinzugefügt, gelöscht oder aktualisiert worden sind.

Filtern Sie die Ereignisse unter @removed nach den Datumsangaben, die für Ihr Szenario erforderlich sind.

Beispiele

Beispiel 1: Delta-Funktion für Ereignisse in einem Kalender (Vorschau)

Anforderung

Das folgende Beispiel zeigt die anfängliche Synchronisierungsanforderung zum Abrufen von Ereignissen im Standardkalender des angemeldeten Benutzers, die am oder nach dem angegebenen startDateTime Parameter auftreten. Die anfängliche Anforderung enthält kein Zustandstoken.

Die Anforderung verwendet den Prefer: odata.maxpagesize -Header, um die maximale Anzahl von Ereignissen in jeder Antwort auf 1 zu begrenzen. Fahren Sie mit dem Aufrufen der delta Funktion fort, indem Sie die Abfrage verwenden, die in @odata.nextLink zurückgegeben wird, bis Sie in der Antwort eine @odata.deltaLink erhalten.

GET https://graph.microsoft.com/beta/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z

Prefer: odata.maxpagesize=1

Antwort

Wenn die Anforderung erfolgreich ist, enthält die Antwort ein Zustandstoken, das entweder ein skipToken (in einem @odata.nextLink-Antwortheader ) oder ein deltaToken (in einem @odata.deltaLink-Antwortheader ) ist. Sie geben jeweils an, ob Sie mit der Runde fortfahren sollten oder ob Sie alle Änderungen für diese Runde abgeschlossen haben.

Die Antwort unten zeigt ein skipToken in einem @odata.nextLink-Antwortheader.

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

{
  "@odata.nextLink":"https://graph.microsoft.com/beta/me/calendar/events/delta?$skiptoken=R0usmcdvmMu7jxWP8",
  "value": [
    {
      "id": " AAMkADllMWMwNDkzLWJlY2EtNDIyOS1iZjAA=",
      "type": "singleInstance",
      "start": {
             "DateTime": "2020-02-19T10:00:00.0000000", 
             "TimeZone": "UTC"
         }, 
       "end": {
                "DateTime": "2020-02-19T11:00:00.0000000", 
                "TimeZone": "UTC"      
          } 
        }
  ]
}

Beispiel 2: Delta-Funktion in calendarView

Anforderung

Das folgende Beispiel zeigt die anfängliche Synchronisierungsanforderung zum Abrufen von Ereignissen im angegebenen Kalender des angemeldeten Benutzers innerhalb des durch calendarView angegebenen Datumsbereichs. Die anfängliche Anforderung enthält kein Zustandstoken.

Die Anforderung verwendet den Prefer: odata.maxpagesize -Header, um die maximale Anzahl von Ereignissen in jeder Antwort auf 2 zu begrenzen. Fahren Sie mit dem Aufrufen der delta Funktion mithilfe der in @odata.nextLink zurückgegebenen Abfrage fort, bis Sie alle Ereignisse in dieser Kalenderansicht und ein @odata.deltaLink in der Antwort erhalten.

GET https://graph.microsoft.com/beta/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?startDateTime=2020-06-01T00:00:00Z&endDateTime=2020-06-10T00:00:00Z

Prefer: odata.maxpagesize=2

Antwort

Wenn die Anforderung erfolgreich ist, enthält die Antwort ein Zustandstoken, das entweder ein skipToken (in einem @odata.nextLink-Antwortheader ) oder ein deltaToken (in einem @odata.deltaLink-Antwortheader ) ist. Sie geben jeweils an, ob Sie mit der Runde fortfahren sollten oder ob Sie alle Änderungen für diese Runde abgeschlossen haben.

Die Antwort unten zeigt ein skipToken in einem @odata.nextLink-Antwortheader.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt sein.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(event)",
    "@odata.nextLink": "https://graph.microsoft.com/beta/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?$skiptoken=R0usmcdvmMu7jxWP8",
    "value": [
        {
            "@odata.type": "#microsoft.graph.event",
            "@odata.etag": "W/\"Jdsb3FEkPk2qoUHCdliYowACwixTgw==\"",
            "createdDateTime": "2020-06-16T04:05:43.8668791Z",
            "lastModifiedDateTime": "2020-06-16T04:08:27.354268Z",
            "changeKey": "Jdsb3FEkPk2qoUHCdliYowACwixTgw==",
            "categories": [],
            "transactionId": null,
            "originalStartTimeZone": "Pacific Standard Time",
            "originalEndTimeZone": "Pacific Standard Time",
            "uid": "040000008200E00074C5B7101A82E00800000000F088B8B95843D601000000000000000010000000165CD5547CFC9545B6492B261750B48C",
            "reminderMinutesBeforeStart": 15,
            "isReminderOn": false,
            "hasAttachments": false,
            "subject": "Summer party",
            "bodyPreview": "",
            "importance": "normal",
            "sensitivity": "normal",
            "isAllDay": false,
            "isCancelled": false,
            "isOrganizer": true,
            "IsRoomRequested": false,
            "AutoRoomBookingStatus": "None",
            "responseRequested": true,
            "seriesMasterId": null,
            "showAs": "busy",
            "type": "singleInstance",
            "webLink": "https://outlook.office365.com/owa/?itemid=AAMkADI5MAAKkeE1QAAA%3D&exvsurl=1&path=/calendar/item",
            "onlineMeetingUrl": null,
            "isOnlineMeeting": false,
            "onlineMeetingProvider": "unknown",
            "allowNewTimeProposals": true,
            "OccurrenceId": null,
            "isDraft": false,
            "recurrence": null,
            "AutoRoomBookingOptions": null,
            "onlineMeeting": null,
            "id": "AAMkADI5MAAKkeE1QAAA=",
            "responseStatus": {
                "response": "none",
                "time": "0001-01-01T00:00:00Z"
            },
            "body": {
                "contentType": "html",
                "content": "<html>\r\n<head></head>\r\n<body lang=\"EN-US\" link=\"#0563C1\" vlink=\"#954F72\" style=\"\">\r\n<div class=\"WordSection1\">\r\n<p class=\"MsoNormal\">&nbsp;</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "start": {
                "dateTime": "2020-06-02T20:00:00.0000000",
                "timeZone": "UTC"
            },
            "end": {
                "dateTime": "2020-06-02T22:30:00.0000000",
                "timeZone": "UTC"
            },
            "location": {
                "displayName": "",
                "locationType": "default",
                "uniqueIdType": "unknown",
                "address": {
                    "type": "unknown"
                },
                "coordinates": {}
            },
            "locations": [],
            "attendees": [
                {
                    "type": "required",
                    "status": {
                        "response": "none",
                        "time": "0001-01-01T00:00:00Z"
                    },
                    "emailAddress": {
                        "name": "Samantha Booth",
                        "address": "samanthab@contoso.com"
                    }
                }
            ],
            "organizer": {
                "emailAddress": {
                    "name": "Samantha Booth",
                    "address": "samanthab@contoso.com"
                }
            }
        },
        {
            "@odata.type": "#microsoft.graph.event",
            "@odata.etag": "W/\"Jdsb3FEkPk2qoUHCdliYowACwixTfw==\"",
            "createdDateTime": "2020-06-16T04:06:18.386713Z",
            "lastModifiedDateTime": "2020-06-16T04:08:19.5694048Z",
            "changeKey": "Jdsb3FEkPk2qoUHCdliYowACwixTfw==",
            "categories": [],
            "transactionId": null,
            "originalStartTimeZone": "Pacific Standard Time",
            "originalEndTimeZone": "Pacific Standard Time",
            "uid": "040000008200E00074C5B7101A82E0080000000060074BC55843D6010000000000000000100000002D33A89F36B10D43A12FD990B62858B2",
            "reminderMinutesBeforeStart": 15,
            "isReminderOn": true,
            "hasAttachments": false,
            "subject": "Summer party part 2",
            "bodyPreview": "",
            "importance": "normal",
            "sensitivity": "normal",
            "isAllDay": false,
            "isCancelled": false,
            "isOrganizer": true,
            "IsRoomRequested": false,
            "AutoRoomBookingStatus": "None",
            "responseRequested": true,
            "seriesMasterId": null,
            "showAs": "busy",
            "type": "singleInstance",
            "webLink": "https://outlook.office365.com/owa/?itemid=AAMkADI5MAAKkeE1RAAA%3D&exvsurl=1&path=/calendar/item",
            "onlineMeetingUrl": null,
            "isOnlineMeeting": false,
            "onlineMeetingProvider": "unknown",
            "allowNewTimeProposals": true,
            "OccurrenceId": null,
            "isDraft": false,
            "recurrence": null,
            "AutoRoomBookingOptions": null,
            "onlineMeeting": null,
            "id": "AAMkADI5MAAKkeE1RAAA=",
            "responseStatus": {
                "response": "none",
                "time": "0001-01-01T00:00:00Z"
            },
            "body": {
                "contentType": "html",
                "content": "<html>\r\n<head></head>\r\n<body lang=\"EN-US\" link=\"#0563C1\" vlink=\"#954F72\" style=\"\">\r\n<div class=\"WordSection1\">\r\n<p class=\"MsoNormal\">&nbsp;</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "start": {
                "dateTime": "2020-06-04T19:30:00.0000000",
                "timeZone": "UTC"
            },
            "end": {
                "dateTime": "2020-06-04T22:30:00.0000000",
                "timeZone": "UTC"
            },
            "location": {
                "displayName": "",
                "locationType": "default",
                "uniqueIdType": "unknown",
                "address": {
                    "type": "unknown"
                },
                "coordinates": {}
            },
            "locations": [],
            "attendees": [
                {
                    "type": "required",
                    "status": {
                        "response": "none",
                        "time": "0001-01-01T00:00:00Z"
                    },
                    "emailAddress": {
                        "name": "Samantha Booth",
                        "address": "samanthab@contoso.com"
                    }
                }
            ],
            "organizer": {
                "emailAddress": {
                    "name": "Samantha Booth",
                    "address": "samanthab@contoso.com"
                }
            }
        }
    ]
}

Verwandte Inhalte