カレンダー ビューのイベントへの増分の変更を取得するGet incremental changes to events in a calendar view

カレンダー ビューは、既定のカレンダー (../me/calendarview) またはユーザーの他のカレンダーからの日付/時刻範囲内にあるイベントのコレクションです。デルタ クエリを使用すると、カレンダー ビューで新規、更新済み、または削除済みのイベントを取得できます。返されるイベントには、定期的なアイテムの発生と例外、および単一のインスタンスが含まれている場合があります。デルタ データを使用すると、毎回サーバーからユーザーのイベントのセット全体をフェッチせずに、ユーザーのイベントのローカル ストアの保守と同期が行えます。A calendar view is a collection of events in a date/time range from the default calendar (../me/calendarview) or some other calendar of the user's. By using delta query, you can get new, updated, or deleted events in a calendar view. The returned events may include occurrences and exceptions of a recurring series, and single instances. 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.

デルタ クエリでは、指定したカレンダー ビュー内のすべてのイベントを取得する完全な同期と、最後の同期以降にカレンダー ビューで変更されたそれらのイベントを取得する増分同期の両方がサポートされています。通常は、最初の完全同期を実行して、その後、そのカレンダー ビューへの増分の変更を定期的に取得します。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.

カレンダー ビューのイベントの変更を追跡するTrack event changes in a calendar view

イベントのデルタ クエリは、指定するカレンダーと日付/時刻範囲 (つまり、カレンダー ビュー) に固有のものです。複数のカレンダー ビューの変更を追跡するには、各カレンダーを個別に追跡する必要があります。Delta query for events is specific to a calendar and date/time range that you specify (i.e., a calendar view). To track the changes in multiple calendars, you need to track each calendar individually.

通常、カレンダー ビュー内のイベント変更の追跡は、デルタ関数を使用した、1 つ以上の GET 要求のラウンドです。最初の GET 要求は、デルタ関数を含めることを除いて、calendarView の一覧表示方法とほぼ同じです。Tracking event changes in a calendar view typically is a round of one or more GET requests with the delta function. The initial GET request is very much like the way you list a calendarView, except that you include the delta function:

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

デルタ関数を使用した GET 要求は、次のいずれかを返します。A GET request with the delta function returns either:

  • nextLink (デルタ関数の呼び出しと skipToken を使用した URL を含む)、またはA nextLink (that contains a URL with a delta function call and a skipToken), or
  • deltaLink (デルタ関数の呼び出しと deltaToken を使用した URL を含む)。A deltaLink (that contains a URL with a delta function call and deltaToken).

これらのトークンは、refs/remotes/microsoftgraph/master startDateTime パラメーターと endDateTime パラメーター、最初のデルタ クエリの GET 要求内の他のすべてのクエリ パラメーターをエンコードする状態トークンです。These tokens are state tokens which encode the refs/remotes/microsoftgraph/master startDateTime and endDateTime parameters, and any other query parameter in your initial delta query GET request.

状態トークンは、クライアントに対して完全に不透明です。変更追跡のラウンドを続行する手順は、最後の GET 要求から返された nextLink または deltaLink の URL を、その同じカレンダー ビューの次のデルタ関数呼び出しにコピーして適用するだけです。応答で返される deltaLink は、変更追跡の現在のラウンドが完了したことを示します。deltaLink URL を保存して、次のラウンドを開始する際に使用することができます。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.

これらの nextLinkdeltaLink の URL を使用する方法については、以下のを参照してください。See the example below to learn how to use these nextLink and deltaLink URLs.

カレンダー ビューのデルタ クエリでクエリ パラメーターを使用するUse query parameters in a delta query for calendar view

  • startDateTime パラメーターと endDateTime パラメーターを含めて、カレンダー ビューの日付/時刻範囲を定義します。Include the startDateTime and endDateTime parameters to define a date/time range for your calendar view.
  • $select はサポートされていません。$select is not supported.

オプションの要求ヘッダーOptional request header

各デルタ クエリの GET 要求は、応答で 1 つ以上のイベントのコレクションを返します。Each delta query GET request returns a collection of one or more events in the response. 必要に応じて、要求ヘッダー Prefer: odata.maxpagesize={x} を指定して、応答内の最大イベント数を設定できます。You can optionally specify the request header, Prefer: odata.maxpagesize={x}, to set the maximum number of events in a response.

カレンダー ビューでのイベント同期の例Example to synchronize events in a calendar view

次の例では、特定の時間範囲にあるユーザーの既定のカレンダーを同期するための一連の 3 つの要求を示します。そのカレンダー ビューには 5 つのイベントがあります。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.

簡潔にするため、サンプルの応答にはイベントのプロパティのサブセットのみを表示します。実際の呼び出しでは、ほとんどのイベント プロパティが返されます。For brevity, the sample responses show only a subset of the properties for an event. In an actual call, most event properties are returned.

次のラウンドで行う操作も参照してください。See also what you'll do in the next round.

手順 1: 最初の要求のサンプルStep 1: sample initial request

この例では、指定されたカレンダー ビューは初めて同期されるため、最初の同期要求には状態トークンは含まれません。このラウンドは、そのカレンダー ビュー内のすべてのイベントを返します。In this example, the specified calendar view is being synchronized for the first time, so the initial sync request does not include any state token. This round will return all the events in that calendar view.

最初の要求では、次を指定します。The first request specifies the following:

  • startDateTime パラメーターと endDateTime パラメーターの日付/時刻の値。Date/time values for the startDateTime and endDateTime parameters.
  • オプションの要求ヘッダーである odata.maxpagesize が一度に 2 つのイベントを返します。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

最初の応答のサンプルSample initial response

応答には、2 つのイベントと skipToken のある @odata.nextLink 応答ヘッダーが含まれています。nextLink URL は、取得するカレンダー ビューにさらにイベントがあることを示します。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="
        }
    ]
}

SDK サンプル コードSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var queryOptions = new List<QueryOption>()
{
    new QueryOption("startdatetime", "2016-12-01T00:00:00Z"),
    new QueryOption("enddatetime", "2016-12-30T00:00:00Z")
};

var delta = await graphClient.Me.CalendarView.Delta()
    .Request( queryOptions )
    .Header("Prefer","odata.maxpagesize=2")
    .GetAsync();

Sdk をプロジェクトに 追加し、 auth provider インスタンスを作成する方法の詳細については、 sdk のドキュメントを参照してください。For details about how to add the SDK to your project and create an auth provider instance, see the SDK documentation.

手順 2: 2 番目の要求のサンプルStep 2: sample second request

2 番目の要求では、前の応答で返された nextLink URL を指定します。最初の要求にあるような同じ startDateTime パラメーターと endDateTime パラメーターを指定する必要はなくなりましたのでご注意ください。これは、nextLink URL の skipToken によってこれらのパラメーターがエンコードされて含まれるためです。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

2 番目の応答のサンプルSample second response

2 番目の応答は、カレンダー ビューから取得するイベントがまだあることを示す、カレンダー ビュー内の次の 2 つのイベントと別の nextLink を返します。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="
        }
    ]
}

SDK サンプル コードSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Me.CalendarView.Delta()
    .Request()
    .Header("Prefer","odata.maxpagesize=2")
    .SkipToken("R0usmcCM996atia_s")
    .GetAsync();

Sdk をプロジェクトに 追加し、 auth provider インスタンスを作成する方法の詳細については、 sdk のドキュメントを参照してください。For details about how to add the SDK to your project and create an auth provider instance, see the SDK documentation.

手順 3: 3 番目の要求のサンプルStep 3: sample third request

3 番目の要求は、最後の同期要求から返された最新の nextLink を引き続き使用します。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

3 番目と最後の応答のサンプルSample third and final response

3 番目の応答では、カレンダー ビューに残っている 1 つだけのイベントと、このカレンダー ビューの同期が完了したことを示す deltaLink URL が返されます。deltaLink URL を保存して、次のラウンドでそのカレンダー ビューを同期するために使用します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="
        }
    ]
}

SDK サンプル コードSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Me.CalendarView.Delta()
    .Request()
    .Header("Prefer","odata.maxpagesize=2")
    .SkipToken("R0usmci39OQxqJrxK4")
    .GetAsync();

Sdk をプロジェクトに 追加し、 auth provider インスタンスを作成する方法の詳細については、 sdk のドキュメントを参照してください。For details about how to add the SDK to your project and create an auth provider instance, see the SDK documentation.

次のラウンド: 最初の要求のサンプルThe next round: sample first request

最後のラウンドの最後の応答からの deltaLink を使用すると、それ以降にそのカレンダー ビューで (追加、削除、または更新によって) 変更されたこれらのイベントのみを取得できます。次のラウンドの最初の要求は、同じ最大ページ サイズを維持することを前提とすると、次のようになります。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

次のラウンド: 最初の応答のサンプルThe 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="
        }
    ]
}

SDK サンプル コードSDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var delta = await graphClient.Me.CalendarView.Delta()
    .Request()
    .Header("Prefer","odata.maxpagesize=2")
    .GetAsync();

Sdk をプロジェクトに 追加し、 auth provider インスタンスを作成する方法の詳細については、 sdk のドキュメントを参照してください。For details about how to add the SDK to your project and create an auth provider instance, see the SDK documentation.

関連項目See also