event: 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.
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 serienserienmaster. | 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 /calendarViewAnforderung erhalten würden. Sie können$selectnicht 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. Erfahren Sie mehr über die Authentifizierung und Autorisierung. |
| 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\"> </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\"> </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"
}
}
}
]
}