Feedback Bearbeiten

event: delta

  • Artikel
  • 9 Minuten Lesedauer

Namespace: microsoft.graph

Wichtig

APIs unter der /beta Version in Microsoft Graph können geändert werden. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in Version 1.0 verfügbar ist, verwenden Sie die Versionsauswahl .

Dient zum Abrufen einer Gruppe von Ereignisressourcen, 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 (durch Start- und Enddatum definierte Ereignisbereiche) eines Kalenders abrufen. Der Kalender kann der Standardkalender oder ein anderer angegebener Kalender des Benutzers sein. Im Falle inkrementeller Änderungen in calendarView kann der Kalender auch ein Gruppenkalender sein.

In der Regel umfasst das Synchronisieren von Ereignissen in einem Kalender oder in calendarView in einem lokalen Speicher eine Runde von mehreren Delta-Funktionsaufrufen. Der anfängliche Aufruf ist eine vollständige Synchronisierung, und jeder nachfolgende Delta-Aufruf in derselben Runde ruft die inkrementellen Änderungen (Ergänzungen, Löschungen oder Updates) ab. Auf diese Weise können Sie einen lokalen Speicher von Ereignissen 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, beginnend mit oder nach diesem Datum/dieser Uhrzeit. Ruft inkrementelle Änderungen von Ereignissen innerhalb des Anfangs- und Enddatums/der Endzeit der calendarView ab.
Gibt aus Leistungsgründen nur einen begrenzten Satz von Ereigniseigenschaften zurück. Client, der anschließend zum Erweitern von Ereignissen verwendet GET /events/{id} werden soll. Die serverseitige Erweiterung gibt einen vollständigeren Satz von Ereigniseigenschaften zurück.
Die Antwort umfasst einzelne Instanzen und serienserienmaster. Die Antwort umfasst einzelne Instanzen sowie Vorkommen und Ausnahmen von Terminserien.
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 der Version v1.0 und in der Betaversion.

Berechtigungen

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema Berechtigungen.

Berechtigungstyp Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto) Calendars.Read, Calendars.ReadWrite
Delegiert (persönliches Microsoft-Konto) Calendars.Read, Calendars.ReadWrite
Anwendung Calendars.Read, 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 in der angegebenen Kalender- oder Kalenderansicht abruft. Diese Syntax enthält keine Statustoken.

Die Abfrage-URL, die in einer oder einer erfolgreichen Antwort zurückgegeben nextLink deltaLink wird, enthält ein Statustoken. Verwenden Sie für alle nachfolgenden Delta-Funktionsaufrufe die Abfrage-URL in einer nextLink oder vor deltaLink ihr.

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

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

  • So rufen Sie inkrementelle Änderungen aller Ereignisse oder von Ereignissen ab 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 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 aller Ereignisse oder von Ereignissen ab oder nach dem angegebenen Datum/der angegebenen Uhrzeit in der angegebenen Kalendergruppe und im 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 auf calendarView in einem Benutzerkalender

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

  • 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 auf 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 Delta-Funktionsaufrufen. 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 nextLink- oder deltaLink-URL. Sie müssen alle gewünschten Abfrageparameter nur einmal im Vorfeld angeben. Kopieren Sie in nachfolgenden Anforderungen einfach die oder die nextLink deltaLink URL aus der vorherigen Antwort, da diese URL bereits die codierten, gewünschten Parameter enthält.

Abfrageparameter Typ Beschreibung
startDateTime Zeichenfolge Startdatum und -uhrzeit des Zeitraums, dargestellt im ISO 8601-Format. Beispiel: "2019-11-08T19:00:00-08:00".
Die Zeitzone wird im Zeitzonen-Offsetteil des Parameterwerts angegeben und wird von der Kopfzeile nicht Prefer: outlook.timezone 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 Zeichenfolge Enddatum und -uhrzeit des Zeitraums, dargestellt im ISO 8601-Format. Beispiel: "2019-11-08T20:00:00-08:00".
Die Zeitzone wird im Zeitzonen-Offsetteil des Parameterwerts angegeben und wird von der Kopfzeile nicht Prefer: outlook.timezone 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 Statustoken, das in der deltaLink-URL des vorhergehenden delta-Funktionsaufrufs für dieselbe Kalenderansicht zurückgegeben wird und den Abschluss dieser Runde der Änderungsnachverfolgung anzeigt. Speichern Sie die gesamte deltaLink-URL einschließlich dieses Tokens, und wenden Sie sie in der ersten Anforderung der nächsten Änderungsnachverfolgungsrunde für diese Kalenderansicht an.
$skiptoken string Ein Statustoken, das in der nextLink-URL des vorhergehenden delta-Funktionsaufrufs zurückgegeben wird und anzeigt, dass in derselben Kalenderansicht weitere Änderungen zum Nachverfolgen vorliegen.

OData-Abfrageparameter

  • Erwarten Sie, dass ein Delta-Funktionsaufruf für eine calendarView dieselben Eigenschaften zurückgibt, die Sie normalerweise von einer GET /calendarview Anforderung erhalten. Sie können nicht $select verwenden, 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 , , , und $filter $orderby $search $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={Time zone string}. Optional, wenn nicht vorhanden, wird UTC angenommen.

Antwort

Delta-Funktion für Ereignisse (Vorschau)

Bei erfolgreicher Ausführung gibt die Methode den 200 OK Antwortcode und eine Ereignissammlung im Antworttext zurück. Jedes Ereignis in der Antwort enthält aus Leistungsgründen nur die Eigenschaften "ID", "Typ", "Start" und "Ende". Verwenden Sie GET /events/{id} dies anschließend, um alle Ereignisse aus der Antwort zu erweitern.

Delta-Funktion in calendarView

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

Erwarten Sie, dass Sie alle Eigenschaften abrufen, die Sie normalerweise von einer GET /calendarview Anforderung erhalten.

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

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

Filtern Sie die Ereignisse nach @removed dem Datumsbereich, der für Ihr Szenario erforderlich ist.

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 auf oder nach dem angegebenen startDateTime Parameter auftreten. Die ursprüngliche Anforderung enthält kein Statustoken.

Die Anforderung verwendet den Prefer: odata.maxpagesize Header, um die maximale Anzahl von Ereignissen in jeder Antwort auf 1 zu beschränken. Fahren Sie mit dem Aufrufen der Funktion fort, indem Sie die zurückgegebene Abfrage verwenden, delta bis Sie eine in der Antwort @odata.nextLink @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 Statustoken, das entweder ein skipToken (in einem @ odata.nextLink-Antwortheader) oder ein deltaToken (in einem @ odata.deltaLink-Antwortheader) ist. Sie geben an, ob Sie mit der Runde fortfahren sollen 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 in calendarView

Anforderung

Das folgende Beispiel zeigt die anfängliche Synchronisierungsanforderung zum Abrufen von Ereignissen im angegebenen Kalender des angemeldeten Benutzers innerhalb des datumsbereichs, der durch calendarView angegeben wird. Die ursprüngliche Anforderung enthält kein Statustoken.

Die Anforderung verwendet den Prefer: odata.maxpagesize Header, um die maximale Anzahl von Ereignissen in jeder Antwort auf 2 zu beschränken. Fahren Sie mit dem Aufrufen der delta Funktion mithilfe der zurückgegebenen Abfrage @odata.nextLink fort, bis Sie alle Ereignisse in dieser Kalenderansicht und eine @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 Statustoken, das entweder ein skipToken (in einem @ odata.nextLink-Antwortheader) oder ein deltaToken (in einem @ odata.deltaLink-Antwortheader) ist. Sie geben an, ob Sie mit der Runde fortfahren sollen oder ob Sie alle Änderungen für diese Runde erhalten haben.

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

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

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.onmicrosoft.com"
                    }
                }
            ],
            "organizer": {
                "emailAddress": {
                    "name": "Samantha Booth",
                    "address": "samanthab@contoso.onmicrosoft.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.onmicrosoft.com"
                    }
                }
            ],
            "organizer": {
                "emailAddress": {
                    "name": "Samantha Booth",
                    "address": "samanthab@contoso.onmicrosoft.com"
                }
            }
        }
    ]
}

Siehe auch