event: delta

Namespace: microsoft.graph

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

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 (durch Start- und Enddatum definierter Ereignisbereich) eines Kalenders abrufen. Der Kalender kann der Standardkalender oder ein anderer angegebener Kalender sein, der dem Benutzer gehört. Beim Abrufen inkrementeller Änderungen in calendarView kann der Kalender auch ein Gruppenkalender sein.

In der Regel erfordert das Synchronisieren von Ereignissen in einem Kalender oder einer Kalenderansicht in einem lokalen Speicher eine Runde mehrerer Delta-Funktionsaufrufe. 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). Mithilfe von Deltas können Sie einen lokalen Speicher von Ereignissen im angegebenen Kalender inkrementell verwalten und synchronisieren.

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

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

Berechtigungen

Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

HTTP-Anforderung

In diesem Abschnitt wird die HTTP-Anforderungssyntax für den anfänglichen Aufruf der Delta-Funktion zum Starten einer vollständigen Synchronisierung gezeigt, die alle Ereignisse im angegebenen Kalender oder in der angegebenen Kalenderansicht abruft. Diese Syntax enthält keine Statustoken.

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 alle nachfolgenden Delta-Funktionsaufrufe 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 am oder nach einem bestimmten Datum/einer bestimmten Uhrzeit im angegebenen Benutzerkalender oder den angegebenen Benutzerkalendern beginnen:

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

  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, die am oder nach dem angegebenen Datum/der angegebenen Uhrzeit im Standardkalender des Benutzers beginnen:

  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, die am oder nach dem angegebenen Datum/der angegebenen Uhrzeit im angegebenen Benutzerkalender beginnen:

  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 aller Ereignisse oder von Ereignissen ab, die am oder nach dem angegebenen Datum/der angegebenen Uhrzeit in der angegebenen Kalendergruppe und dem angegebenen Kalender beginnen:

  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 in calendarView in a user calendar

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 in KalenderAnsicht in einem Gruppenkalender

• So erhalten Sie inkrementelle Änderungen in einer Kalenderansicht des Kalenders einer Gruppe:

  GET /groups/{id}/calendarView?startDateTime={start_datetime}&endDateTime={end_datetime}
  

Abfrageparameter

Das Nachverfolgen von Änderungen führt zu einer Runde von mindestens einem Delta-Funktionsaufruf. 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. In nachfolgenden Anforderungen können Sie die @odata.nextLink- oder @odata.deltaLink-URL aus der vorherigen Antwort kopieren und anwenden, da diese URL bereits die codierten gewünschten Parameter enthält.

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 nicht verwenden $select , um nur eine Teilmenge dieser Eigenschaften abzurufen.

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

Anforderungsheader

Antwort

Delta-Funktion für Ereignisse (Vorschau)

Bei erfolgreicher Ausführung gibt diese Methode einen 200 OK Antwortcode und eine Ereignissammlung im Antworttext zurück. Jedes Ereignis in der Antwort enthält aus Leistungsgründen nur die Eigenschaften id, type, start und end . Verwenden Sie GET /events/{id} später, um alle Ereignisse aus der Antwort zu erweitern.

Delta-Funktion für calendarView

Bei erfolgreicher Ausführung gibt diese Methode einen 200 OK Antwortcode und eine Ereignissammlung im Antworttext zurück.

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

Innerhalb einer Runde von Delta-Funktionsaufrufen , die an den Datumsbereich einer calendarView gebunden sind, können Sie manchmal einen Delta-Aufruf finden, der zwei Arten von Ereignissen mit @removed dem Grund deletedzurückgibt:

• Ereignisse, die innerhalb des Datumsbereichs liegen und seit dem letzten Delta-Aufruf gelöscht wurden.
• Ereignisse, die außerhalb des Datumsbereichs liegen und die seit dem letzten Delta-Aufruf hinzugefügt, gelöscht oder aktualisiert wurden.

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 ursprü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 beschränken. Rufen Sie die delta Funktion mithilfe der zurückgegebenen @odata.nextLink Abfrage so lange auf, bis Sie eine @odata.deltaLink Antwort erhalten.

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

Prefer: odata.maxpagesize=1

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z')
	.version('beta')
	.get();

Antwort

Wenn die Anforderung erfolgreich ist, enthält die Antwort ein Zustandstoken, bei dem es sich entweder um einen skipToken (in einem @odata.nextLink-Antwortheader ) oder um ein deltaToken (in einem @odata.deltaLink-Antwortheader ) handelt. Sie zeigen jeweils an, ob Sie mit der Runde fortfahren sollten oder ob Sie alle Änderungen für diese Runde erhalten 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 für calendarView

Anforderung

Das folgende Beispiel zeigt die anfängliche Synchronisierungsanforderung zum Abrufen von Ereignissen im angegebenen Kalender des angemeldeten Benutzers innerhalb des von calendarView angegebenen Datumsbereichs. Die ursprü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 beschränken. Rufen Sie die delta Funktion mithilfe der zurückgegebenen @odata.nextLink Abfrage so lange auf, bis Sie alle Ereignisse in dieser Kalenderansicht und a @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

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?startDateTime=2020-06-01T00:00:00Z&endDateTime=2020-06-10T00:00:00Z')
	.version('beta')
	.get();

Antwort

Wenn die Anforderung erfolgreich ist, enthält die Antwort ein Zustandstoken, bei dem es sich entweder um einen skipToken (in einem @odata.nextLink-Antwortheader ) oder um ein deltaToken (in einem @odata.deltaLink-Antwortheader ) handelt. Sie zeigen jeweils an, ob Sie mit der Runde fortfahren sollten oder ob Sie alle Änderungen für diese Runde erhalten haben.

Die folgende Antwort zeigt einen 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

• Microsoft Graph-Delta-Abfrage
• Inkrementelle Änderungen an Ereignissen in einem Ordner abrufen