Apporter des modifications incrémentielles aux événements dans l’affichage CalendrierGet incremental changes to events in a calendar view

L’utilisation de la requête Delta vous permet d’obtenir les événements nouveaux, mis à jour ou supprimés dans un ou plusieurs calendriers spécifiés ou au sein d’une collection d’événements définie (sous forme d’affichage Calendrier) dans le calendrier.By using delta query, you can get new, updated, or deleted events in a specified calendar(s), or within a defined collection of events (as a calendar view) in the calendar. Cet article décrit l’obtention des modifications incrémentielles apportées aux événements dans un affichage Calendrier.This article describes the latter - getting such incremental changes to events in a calendar view.

Remarque : la possibilité d’obtenir des modifications incrémentielles apportées aux événements d’un calendrier non lié à une plage de dates de début et de fin fixes est actuellement disponible uniquement dans la version bêta.Note The capability for the former - getting incremental changes to events in a calendar not bound to a fixed start and end date range - is currently available only in the beta version. Pour plus d’informations, voir fonction delta.For more information, see delta function.

L’affichage Calendrier est une collection d’événements d’une plage de date/heure (../me/calendarview) extraite du calendrier par défaut, d’un autre calendrier d’un utilisateur ou d’un calendrier de groupe.A calendar view is a collection of events in a date/time range (../me/calendarview) from the default calendar or some other specified calendar of a user, or from a group calendar. Les événements renvoyés peuvent inclure des instances uniques ou des occurrences et des exceptions de séries périodiques.The returned events may include single instances, or occurrences and exceptions of a recurring series. Les données de la requête delta vous permettent de mettre à jour et de synchroniser une collection locale des événements d’un utilisateur, sans avoir à récupérer l’ensemble des événements de l’utilisateur depuis le serveur.The delta data enables you to maintain and synchronize a local store of a user's events, without having to fetch the entire set of the user's events from the server every time.

La requête delta s’occupe à la fois de la synchronisation complète qui récupère tous les événements dans l’affichage Calendrier spécifié, et de la synchronisation incrémentielle qui récupère les événements ayant été modifiés dans l’affichage Calendrier depuis la dernière synchronisation. En règle générale, il est préférable d’effectuer une première synchronisation complète, puis d’apporter régulièrement des modifications incrémentielles à cet affichage Calendrier.Delta query supports both full synchronization that retrieves all the events in the specified calendar view, and incremental synchronization that retrieves those events that have changed in the calendar view since the last synchronization. Typically, you would do an initial full synchronization, and subsequently, get incremental changes to that calendar view periodically.

Suivi des modifications apportées aux événements dans l’affichage CalendrierTrack event changes in a calendar view

La requête delta pour les événements dans l’affichage Calendrier est spécifique au calendrier et à la plage date/heure indiqués.Delta query for events in a calendar view is specific to a calendar and date/time range that you specify. Pour suivre les modifications apportées dans plusieurs calendriers, vous devez suivre chaque calendrier individuellement.To track the changes in multiple calendars, you need to track each calendar individually.

Le suivi des modifications apportées aux événements dans un affichage Calendrier correspond généralement à une série de requêtes GET envoyées avec la fonction delta.Tracking event changes in a calendar view typically is a round of one or more GET requests with the delta function. Le processus de la première requête GET ressemble à celui de la requête List calendarView, sauf que vous incluez la fonction delta.The initial GET request is very much like the way you list a calendarView, except that you include the delta function. Voici la requête GET delta initiale d’un affichage Calendrier dans le calendrier par défaut de l’utilisateur connecté :The following is the initial GET delta request of a calendar view in the signed-in user's default calendar:

GET /me/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}

Une requête GET avec la fonction delta renvoie, soit :A GET request with the delta function returns either:

  • nextLink (qui contient une URL avec un appel de la fonction delta et un jeton skipToken), soitA nextLink (that contains a URL with a delta function call and a skipToken), or
  • deltaLink (qui contient une URL avec un appel de la fonction delta et un jeton deltaToken).A deltaLink (that contains a URL with a delta function call and deltaToken).

Ces jetons d’état codent les paramètres startDateTime et endDateTime, et les autres paramètres de requête inclus dans votre première requête GET effectuée avec la fonction delta.These tokens are state tokens which encode the startDateTime and endDateTime parameters, and any other query parameter in your initial delta query GET request. Vous n’avez pas besoin d’inclure ces paramètres dans les requêtes suivantes, car ils sont codés dans les jetons.You do not need to include these parameters in subsequent requests as they are encoded in the tokens.

Les jetons d’état sont complètement opaques pour le client. Pour réaliser une première série de suivis des modifications, copiez et appliquez l’URL nextLink ou deltaLink renvoyée par la dernière requête GET à l’autre appel de la fonction delta pour le même affichage Calendrier. Si deltaLink est renvoyé, la série de suivis des modifications en cours est terminée. Vous pouvez enregistrer et utiliser l’URL deltaLink quand vous lancez la série de suivis suivante.State tokens are completely opaque to the client. To proceed with a round of change tracking, simply copy and apply the nextLink or deltaLink URL returned from the last GET request to the next delta function call for that same calendar view. A deltaLink returned in a response signifies that the current round of change tracking is complete. You can save and use the deltaLink URL when you begin the next round.

Consultez l’exemple ci-dessous pour savoir comment utiliser les URL nextLink et deltaLink.See the example below to learn how to use these nextLink and deltaLink URLs.

Utilisation des paramètres de requête dans une requête delta pour l’affichage CalendrierUse query parameters in a delta query for calendar view

  • Inclure les paramètres startDateTime et endDateTime pour définir une plage date/heure pour votre affichage Calendrier.Include the startDateTime and endDateTime parameters to define a date/time range for your calendar view.
  • $select n’est pas pris en charge.$select is not supported.

En-tête de requête facultatifOptional request header

Chaque requête GET effectuée avec la fonction delta renvoie une collection d’un ou de plusieurs événements dans la réponse.Each delta query GET request returns a collection of one or more events in the response. Vous pouvez spécifier l’en-tête de la requête, Prefer: odata.maxpagesize={x}, pour définir le nombre maximal d’événements à inclure dans une réponse.You can optionally specify the request header, Prefer: odata.maxpagesize={x}, to set the maximum number of events in a response.

Exemple pour synchroniser les événements dans un affichage CalendrierExample to synchronize events in a calendar view

L’exemple suivant montre une série de 3 requêtes pour synchroniser le calendrier par défaut de l’utilisateur dans un intervalle de temps spécifique. Il existe 5 événements dans cet affichage Calendrier.The following example shows a series of 3 requests to synchronize the user's default calendar in a specific time range. There are 5 events in that calendar view.

Pour des raisons de concision, les exemples de réponse montrent uniquement un sous-ensemble des propriétés d’un événement. Dans un véritable appel, la plupart des propriétés de l’événement sont renvoyées.For brevity, the sample responses show only a subset of the properties for an event. In an actual call, most event properties are returned.

Consultez également les étapes de la deuxième série de suivis.See also what you'll do in the next round.

Étape 1 : exemple de la première requêteStep 1: sample initial request

Dans cet exemple, l’affichage Calendrier spécifié dans le calendrier par défaut de l’utilisateur connecté est synchronisé pour la première fois. C’est pourquoi la synchronisation initiale ne contient aucun jeton d’état.In this example, the specified calendar view in the signed-in user's default calendar is being synchronized for the first time, so the initial sync request does not include any state token. Cette série renvoie tous les événements figurant dans cet affichage Calendrier.This round will return all the events in that calendar view.

La première requête comprend les éléments suivants :The first request specifies the following:

  • Valeurs de date/heure des paramètres startDateTime et endDateTime.Date/time values for the startDateTime and endDateTime parameters.
  • L’en-tête de requête facultatif, odata.maxpagesize, qui renvoie 2 événements à la fois.The optional request header, odata.maxpagesize, returning 2 events at a time.
GET https://graph.microsoft.com/v1.0/me/calendarView/delta?startdatetime=2016-12-01T00:00:00Z&enddatetime=2016-12-30T00:00:00Z HTTP/1.1
Prefer: odata.maxpagesize=2

Exemple de première réponseSample initial response

La réponse comprend deux événements et un en-tête de réponse @odata.nextLink avec un jeton skipToken. L’URL nextLink indique qu’il est possible de récupérer plusieurs événements de l’affichage Calendrier.The response includes two events and a @odata.nextLink response header with a skipToken. The nextLink URL indicates there are more events in the calendar view to get.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmcCM996atia_s",
    "value":[
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvIQ==\"",
            "subject":"Plan shopping list",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-09T20:30:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-09T22:00:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },      
            "id":"AAMkADNVxRAAA="
        },
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvIg==\"",
            "subject":"Pick up car",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-10T01:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-10T02:00:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADVxSAAA="
        }
    ]
}

Étape 2 : exemple de la deuxième requêteStep 2: sample second request

La deuxième requête comprend l’URL nextLink renvoyée par la réponse précédente. Notez qu’il est inutile de repréciser les paramètres startDateTime et endDateTime, puisqu’ils sont codés et inclus par le jeton skipToken présent dans l’URL nextLink.The second request specifies the nextLink URL returned from the previous response. Notice that it no longer has to specify the same startDateTime and endDateTime parameters as in the initial request, as the skipToken in the nextLink URL encodes and includes them.

GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmcCM996atia_s HTTP/1.1
Prefer: odata.maxpagesize=2

Exemple de deuxième réponseSample second response

La deuxième réponse renvoie les 2 événements suivants dans l’affichage Calendrier et une autre URL nextLink, indiquant qu’il est possible de récupérer d’autres événements dans l’affichage Calendrier.The second response returns the next 2 events in the calendar view and another nextLink, indicating there are more events to get from the calendar view.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.nextLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmci39OQxqJrxK4",
    "value":[
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvIw==\"",
            "subject":"Get food",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-10T19:30:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-10T21:30:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADVxTAAA="
        },
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAAFXcvJA==\"",
            "subject":"Prepare food",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-10T22:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-11T00:00:00.0000000",
                "timeZone":"UTC"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADVxUAAA="
        }
    ]
}

Étape 3 : exemple de la troisième requêteStep 3: sample third request

La troisième requête continue d’utiliser les dernières URL nextLink renvoyées par la dernière requête de synchronisation.The third request continues to use the latest nextLink returned from the last sync request.

GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$skiptoken=R0usmci39OQxqJrxK4 HTTP/1.1
Prefer: odata.maxpagesize=2

Exemple de troisième et dernière réponseSample third and final response

La troisième réponse renvoie le dernier événement restant dans l’affichage Calendrier et une URL deltaLink indiquant que la synchronisation de cet affichage Calendrier est terminée. Enregistrez et utilisez l’URL deltaLink pour synchroniser cet affichage Calendrier lors de la prochaine série.The third response returns the only remaining event in the calendar view, and a deltaLink URL which indicates synchronization is complete for this calendar view. Save and use the deltaLink URL to synchronize that calendar view in the next round.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.deltaLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$deltatoken=R0usmcMDNGg0J1E",
    "value":[
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAALZu97g==\"",
            "subject":"Rest!",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-12T02:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-12T07:30:00.0000000",
                "timeZone":"UTC"
            },
            "location":{
                "displayName":"Home"
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADj1HuAAA="
        }
    ]
}

Deuxième série : exemple de la première requêteThe next round: sample first request

En utilisant l’URL deltaLink renvoyée par la dernière requête de la série précédente, vous pouvez récupérer uniquement les événements qui ont été ajoutés, supprimés ou mis à jour dans cet affichage Calendrier. Voici à quoi ressemblera la première requête de cette deuxième série de suivis, à condition que vous conserviez le même format de page maximal dans la réponse :Using the deltaLink from the last request in the last round, you will be able to get only those events that have changed (by being added, deleted, or updated) in that calendar view since then. Your first request in the next round will look like the following, assuming you prefer to keep the same maximum page size in the response:

GET https://graph.microsoft.com/v1.0/me/calendarView/delta?$deltatoken=R0usmcMDNGg0J1E HTTP/1.1
Prefer: odata.maxpagesize=2

Deuxième série : exemple de la première réponseThe next round: sample first response

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(event)",
    "@odata.deltaLink":"https://graph.microsoft.com/v1.0/me/calendarView/delta?$deltatoken=R0usmcFuQtZdtpk4",
    "value":[
        {
            "@odata.type": "#microsoft.graph.event",
            "id": "AAMkADk0MGFkODE3LWE4MmYtNDRhOS04OGQLkRkXbBznTvAADb6ytyAAA=",
            "@removed": {
                "reason": "deleted"
            }
        },
        {
            "@odata.type":"#microsoft.graph.event",
            "@odata.etag":"W/\"EZ9r3czxY0m2jz8c45czkwAALZu97w==\"",
            "subject":"Attend service",
            "body":{
                "contentType":"html",
                "content":""
            },
            "start":{
                "dateTime":"2016-12-25T06:00:00.0000000",
                "timeZone":"UTC"
            },
            "end":{
                "dateTime":"2016-12-25T07:30:00.0000000",
                "timeZone":"UTC"
            },
            "location":{
                "displayName":"Chapel of Saint Ignatius",
                "address":{
                    "street":"900 Broadway",
                    "city":"Seattle",
                    "state":"WA",
                    "countryOrRegion":"United States",
                    "postalCode":""
                },
                "coordinates":{
                    "latitude":47.6105,
                    "longitude":-122.321
                }
            },
            "attendees":[

            ],
            "organizer":{
                "emailAddress":{
                    "name":"Samantha Booth",
                    "address":"samanthab@contoso.onmicrosoft.com"
                }
            },
            "id":"AAMkADj1HvAAA="
        }
    ]
}

Voir aussiSee also