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

デルタクエリを使用すると、指定したカレンダー、またはカレンダーの定義済みイベントのコレクション(カレンダービューとして)内で、新規、更新、または削除されたイベントを取得できます。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. この記事では、カレンダービューのイベントへの増分の変更について説明します。This article describes the latter - getting such incremental changes to events in a calendar view.

開始日と終了日の範囲内に連結されていないカレンダーのイベントへの増分変更を取得する機能は、 現在、ベータ版でのみ利用可能です。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. 詳細については、「デルタ関数」を参照してください。For more information, see delta function.

カレンダービューは、ユーザーのデフォルトカレンダーまたは他の指定されたカレンダー、あるいはグループカレンダーからの日付/時間範囲(../me/calendarview)のイベントを表示します。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. 返されるイベントには、単一のインスタンス、または定期的な一連のアイテムの発生と例外が含まれる場合があります。The returned events may include single instances, or occurrences and exceptions of a recurring series. デルタ データを使用すると、毎回サーバーからユーザーのイベントのセット全体をフェッチせずに、ユーザーのイベントのローカル ストアの保守と同期が行えます。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 in a calendar view is specific to a calendar and date/time range that you specify. 複数のカレンダー ビューの変更を追跡するには、各カレンダーを個別に追跡する必要があります。To track the changes in multiple calendars, you need to track each calendar individually.

通常、カレンダー ビュー内のイベント変更の追跡は、デルタ関数を使用した、1 つ以上の GET 要求のラウンドです。Tracking event changes in a calendar view typically is a round of one or more GET requests with the delta function. 最初のGET要求は、デルタ関数を含めることを除いて、calendarView を一覧表示する方法と非常によく似ています。The initial GET request is very much like the way you list a calendarView, except that you include the delta function. 以下は、サインインしたユーザーのデフォルトカレンダーのカレンダービューの最初のGETデルタ要求です。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}

デルタ関数を使用した 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).

これらのトークンは、startDateTime パラメーターと endDateTime パラメーター、および最初のデルタ クエリの GET 要求内の他のすべてのクエリ パラメーターをエンコードする state tokens です。These tokens are state tokens which encode the startDateTime and endDateTime parameters, and any other query parameter in your initial delta query GET request. これらのパラメーターはトークンにエンコードされるため、後続の要求にこれらのパラメーターを含める必要はありません。You do not need to include these parameters in subsequent requests as they are encoded in the tokens.

状態トークンは、クライアントに対して完全に不透明です。変更追跡のラウンドを続行する手順は、最後の 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 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. このラウンドは、そのカレンダー ビュー内のすべてのイベントを返します。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="
        }
    ]
}

手順 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="
        }
    ]
}

手順 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="
        }
    ]
}

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

関連項目See also