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 (bereich von Ereignissen, die durch Start- und Enddatum definiert werden) 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.

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). Mithilfe von Deltas können Sie einen lokalen Ereignisspeicher im angegebenen Kalender inkrementell verwalten und synchronisieren.

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.

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

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 im angegebenen Benutzerkalender oder in den angegebenen Kalendern 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. 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 nicht die folgenden Abfrageparameter für Ereignisse in einem Benutzerkalender oder Ereignisse in einer calendarView: $expand, $filter,$orderby$search , und $select.

Anforderungsheader

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} später, 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.

In einer Runde von Delta-Funktionsaufrufen, die durch den Datumsbereich einer calendarView gebunden sind, finden Sie manchmal einen Deltaaufruf, der zwei Arten von Ereignissen unter @removed mit dem Grund deletedzurückgibt:

• Ereignisse, die innerhalb des Datumsbereichs liegen und seit dem vorherigen Deltaaufruf gelöscht wurden.
• Ereignisse, die außerhalb des Datumsbereichs liegen und seit dem vorherigen Deltaaufruf 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 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

mgc-beta users calendar events delta get --user-id {user-id} --start-date-time "2020-06-12T00:00:00Z"

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, 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

mgc-beta users calendars calendar-view delta get --user-id {user-id} --calendar-id {calendar-id} --start-date-time "2020-06-01T00:00:00Z" --end-date-time "2020-06-10T00:00:00Z"

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, 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 folgende Antwort 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

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