Partager via


événement : delta

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Obtenez un ensemble de ressources d’événement qui sont ajoutées, supprimées ou mises à jour dans un ou plusieurs calendriers.

Vous pouvez obtenir des types spécifiques de ces modifications incrémentielles dans les événements de tous les calendriers d’une boîte aux lettres ou d’un calendrier spécifique, ou dans une collection d’événements d’un calendarView (plage d’événements définie par les dates de début et de fin) d’un calendrier. Le calendrier peut être le calendrier par défaut ou un autre calendrier spécifié qui appartient à l’utilisateur. Lors de l’obtention de modifications incrémentielles sur calendarView, le calendrier peut également être un calendrier de groupe.

En règle générale, la synchronisation d’événements dans un calendrier ou calendarView dans un magasin local implique une série d’appels de fonction delta multiples. L'appel initial est une synchronisation complète, et chaque appel delta ultérieur dans le même tour obtient les changements incrémentaux (ajouts, suppressions ou mises à jour). L’utilisation de deltas vous permet de gérer et de synchroniser de façon incrémentielle un magasin local d’événements dans le calendrier spécifié.

Le tableau suivant répertorie les différences entre la fonction delta sur les événements et la fonction delta sur un calendarView dans un calendrier.

Fonction Delta sur les événements Fonction Delta sur calendarView
Obtient les modifications incrémentielles de tous les événements d’un calendrier non limité par une plage de dates de début et de fin. Vous pouvez également obtenir des modifications incrémentielles des événements dans un calendrier limité par une heure de début, à partir de cette date/heure ou après. Obtient les modifications incrémentielles des événements dans la date/heure de début et de fin du calendarView.
Retourne uniquement un ensemble limité de propriétés d’événement pour des raisons de performances. Client à utiliser GET /events/{id} ultérieurement pour développer tous les événements. L’extension côté serveur retourne un ensemble plus complet de propriétés d’événement .
La réponse inclut des instances uniques et des master de séries périodiques. La réponse inclut des instances uniques, ainsi que des occurrences et des exceptions de séries périodiques.
S’applique aux événements dans les calendriers utilisateur, mais pas aux calendriers de groupe. S’applique aux événements dans les calendriers d’utilisateurs et de groupes.
Actuellement disponible uniquement dans la version bêta. Disponible dans les versions v1.0 et bêta.

Cette API est disponible dans les déploiements de cloud national suivants.

Service global Gouvernement des États-Unis L4 Us Government L5 (DOD) Chine gérée par 21Vianet

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire) Calendars.ReadBasic Calendars.Read, Calendars.ReadWrite
Déléguée (compte Microsoft personnel) Calendars.ReadBasic Calendars.Read, Calendars.ReadWrite
Application Calendars.Read Calendars.ReadBasic, Calendars.ReadWrite

Requête HTTP

Cette section présente la syntaxe de requête HTTP pour l’appel de fonction delta initial afin de démarrer une synchronisation complète qui récupère tous les événements dans l’affichage calendrier ou calendrier spécifié. Cette syntaxe ne contient aucun jeton d’état.

L’URL de requête retournée dans un @odata.nextLink ou @odata.deltaLink d’une réponse réussie inclut un jeton d’état. Pour tout appel de fonction delta ultérieur, utilisez l’URL de requête dans un @odata.nextLink ou @odata.deltaLink le précédant.

Fonction Delta sur les événements d’un calendrier utilisateur (préversion)

Appliquez la fonction delta à tous les événements ou événements commençant à ou après une date/heure spécifique, dans le ou les calendriers utilisateur spécifiés :

  • Pour obtenir des modifications incrémentielles de tous les événements ou d’événements commençant à ou après la date/heure spécifiée dans la boîte aux lettres de l’utilisateur :

    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}
    
  • Pour obtenir des modifications incrémentielles de tous les événements ou d’événements commençant à ou après la date/heure spécifiée dans le calendrier par défaut de l’utilisateur :

    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}
    
  • Pour obtenir des modifications incrémentielles de tous les événements ou des événements commençant à ou après la date/heure spécifiée dans le calendrier utilisateur spécifié :

    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}
    
  • Pour obtenir les modifications incrémentielles de tous les événements ou d’événements commençant à ou après la date/heure spécifiée dans le groupe de calendriers et le calendrier spécifiés :

    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}
    

Fonction Delta sur calendarView dans un calendrier utilisateur

Appliquez la fonction delta sur une plage d’événements délimités par des dates/heures de début et de fin, dans le calendrier utilisateur spécifié :

  • Pour obtenir des modifications incrémentielles dans un affichage calendrier du calendrier par défaut de l’utilisateur :

    GET /me/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}
    GET /users/{id}/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}
    
  • Pour obtenir des modifications incrémentielles dans un affichage calendrier du calendrier utilisateur spécifié :

    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}
    

Fonction Delta sur calendarView dans un calendrier de groupe

  • Pour obtenir des modifications incrémentielles dans un affichage calendrier du calendrier d’un groupe :
    GET /groups/{id}/calendarView?startDateTime={start_datetime}&endDateTime={end_datetime}
    

Paramètres de requête

Le suivi des modifications entraîne une série d’appels de fonction delta . Si vous utilisez un paramètre de requête (autre que $deltatoken et $skiptoken), vous devez le spécifier dans la requête delta initiale. Microsoft Graph code automatiquement les paramètres spécifiés dans la partie jeton du @odata.nextLink ou de l’URL @odata.deltaLink fournie dans la réponse. Il vous suffit de spécifier les paramètres de requête de votre choix la première fois. Dans les requêtes suivantes, copiez et appliquez le @odata.nextLink ou l’URL @odata.deltaLink à partir de la réponse précédente, car cette URL inclut déjà les paramètres codés souhaités.

Paramètre de requête Type Description
startDateTime String La date et l’heure de début de la plage horaire, représentées au format ISO 8601. Par exemple, « 2019-11-08T19:00:00-08:00 ».
Le fuseau horaire est spécifié dans la partie décalage de fuseau horaire de la valeur du paramètre et n’est pas affecté par l’en-tête s’il Prefer: outlook.timezone est présent. Si aucun décalage de fuseau horaire n’est inclus dans la valeur, il est interprété comme UTC.
Facultatif pour delta sur les événements d’un calendrier.
Obligatoire pour delta sur calendarView.
endDateTime String La date et l’heure de fin de la plage horaire, représentées au format ISO 8601. Par exemple, « 2019-11-08T20:00:00-08:00 ».
Le fuseau horaire est spécifié dans la partie décalage de fuseau horaire de la valeur du paramètre et n’est pas affecté par l’en-tête, le Prefer: outlook.timezone cas échéant. Si aucun décalage de fuseau horaire n’est inclus dans la valeur, il est interprété comme UTC.
Non pris en charge par delta sur les événements d’un calendrier.
Obligatoire pour delta sur calendarView.
$deltatoken string Jeton d’état retourné dans l’URL @odata.deltaLink de l’appel de fonction delta précédent pour le même affichage calendrier, indiquant la fin de cette série de suivi des modifications. Enregistrez et appliquez l’URL entière @odata.deltaLink , y compris ce jeton, dans la première demande de la série suivante de suivi des modifications pour cet affichage Calendrier.
$skiptoken string Jeton sur l’état renvoyé dans l’URL @odata.nextLink de l’appel de fonction delta précédent, indiquant que des modifications supplémentaires doivent être suivies dans le même affichage Calendrier.

Paramètres de requête OData

  • Attendez-vous à ce qu’un appel de fonction delta sur un calendarView retourne les mêmes propriétés que vous obtenez normalement à partir d’une GET /calendarView demande. Vous ne pouvez pas utiliser $select pour obtenir uniquement un sous-ensemble de ces propriétés.

  • La fonction delta ne prend pas en charge les paramètres de requête suivants pour les événements d’un calendrier utilisateur ou les événements dans un calendarView : $expand, $filter,$orderby$search et .$select

En-têtes de demande

Nom Type Description
Autorisation string Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
Content-Type string application/json. Obligatoire.
Préférence chaîne odata.maxpagesize={x}. Optional.
Préférence chaîne outlook.timezone={Chaîne de fuseau horaire}. Facultatif, format UTC utilisé si absente.

Réponse

Fonction Delta sur les événements (préversion)

Si elle réussit, cette méthode renvoie un 200 OK code de réponse et une collection d’événements dans le corps de la réponse. Chaque événement dans la réponse contient uniquement les propriétés id, type, début et fin pour des raisons de performances. Utilisez GET /events/{id} ultérieurement pour développer tous les événements de la réponse.

Fonction Delta sur calendarView

Si elle réussit, cette méthode renvoie un 200 OK code de réponse et une collection d’événements dans le corps de la réponse.

Attendez-vous à obtenir toutes les propriétés que vous obtiendriez normalement à partir d’une GET /calendarView requête.

Dans une série d’appels de fonction delta liés par la plage de dates d’un calendarView, vous pouvez parfois trouver un appel delta retournant deux types d’événements sous @removed avec la raison deleted:

  • Événements qui se trouvent dans la plage de dates et qui ont été supprimés depuis l’appel delta précédent.
  • Événements qui se trouvent en dehors de la plage de dates et qui ont été ajoutés, supprimés ou mis à jour depuis l’appel delta précédent.

Filtrez les @removed événements sous pour la plage de dates nécessaire à votre scénario.

Exemples

Exemple 1 : fonction Delta sur les événements d’un calendrier (préversion)

Demande

L’exemple suivant montre la demande de synchronisation initiale pour obtenir des événements dans le calendrier par défaut de l’utilisateur connecté, qui se produisent sur ou après le paramètre spécifié startDateTime . La requête initiale n’inclut aucun jeton d’état.

La requête utilise l’en-tête Prefer: odata.maxpagesize pour limiter le nombre maximal d’événements dans chaque réponse à 1. Continuez à appeler la delta fonction à l’aide de la requête retournée dans @odata.nextLink jusqu’à ce que vous obteniez un @odata.deltaLink dans la réponse.

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

Prefer: odata.maxpagesize=1

Réponse

Si la demande réussit, la réponse inclut un jeton d’état, qui est soit un skipToken (dans un en-tête de réponse @odata.nextLink ) soit un deltaToken (dans un en-tête de réponse @odata.deltaLink ). Respectivement, ils indiquent si vous devez poursuivre la ronde ou si vous avez terminé d’obtenir toutes les modifications pour cette ronde.

La réponse suivante illustre un skipToken dans un en-tête de réponse @odata.nextLink.

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"      
          } 
        }
  ]
}

Exemple 2 : fonction Delta sur calendarView

Demande

L’exemple suivant montre la demande de synchronisation initiale pour obtenir des événements dans le calendrier spécifié de l’utilisateur connecté, dans la plage de dates indiquée par calendarView. La requête initiale n’inclut aucun jeton d’état.

La requête utilise l’en-tête Prefer: odata.maxpagesize pour limiter le nombre maximal d’événements dans chaque réponse à 2. Continuez à appeler la delta fonction à l’aide de la requête retournée dans @odata.nextLink jusqu’à ce que vous obteniez tous les événements dans cet affichage Calendrier et un @odata.deltaLink dans la réponse.

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

Réponse

Si la demande réussit, la réponse inclut un jeton d’état, qui est soit un skipToken (dans un en-tête de réponse @odata.nextLink ) soit un deltaToken (dans un en-tête de réponse @odata.deltaLink ). Respectivement, ils indiquent si vous devez poursuivre la ronde ou si vous avez terminé d’obtenir toutes les modifications pour cette ronde.

La réponse suivante montre un skipToken dans un en-tête de réponse @odata.nextLink .

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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"
                }
            }
        }
    ]
}