カレンダー ビューのイベントへの増分の変更を取得する

  • [アーティクル]

デルタ クエリを使用すると、指定したカレンダー、またはカレンダーの定義済みイベントのコレクション (カレンダービューとして) 内で、新規、更新、または削除されたイベントを取得できます。 この記事では、後者の、カレンダービューのイベントにそのような増分的な変更を取得することについて説明します。

注:

前者の機能 (固定の開始日と終了日の範囲にバインドされていない予定表のイベントに対する増分変更を取得する) は、現在、ベータ版でのみ使用できます。 詳細については、「デルタ関数」を参照してください。

予定表ビューは、日付/時刻範囲 (../me/calendarView) は、既定の予定表、またはユーザーまたはグループ予定表の他の指定された予定表から取得します。 返されるイベントには、単一のインスタンス、または定期的な一連のアイテムの発生と例外が含まれる場合があります。 デルタ データを使用すると、毎回サーバーからユーザーのイベントのセット全体をフェッチせずに、ユーザーのイベントのローカル ストアの保守と同期が行えます。

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

カレンダー ビューのイベントの変更を追跡する

カレンダービューのイベントのデルタクエリは、指定したカレンダーと日付/時刻範囲に固有のものです。 複数のカレンダー ビューの変更を追跡するには、各カレンダーを個別に追跡する必要があります。

通常、カレンダー ビュー内のイベント変更の追跡は、デルタ関数を使用した、1 つ以上の GET 要求のラウンドです。 最初の GET 要求は、デルタ 関数を含めることを除いて、カレンダー ビューを一覧表示する 方法と非常によく似ています。 以下は、サインインしたユーザーのデフォルトカレンダーのカレンダービューの最初のGETデルタ要求です。

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

デルタ関数を使用した GET 要求は、次のいずれかを返します。

  • @odata.nextLink (デルタ関数の呼び出しと $skipToken を使用した URL を含みます)、または
  • @odata.deltaLink (デルタ関数の呼び出しと $deltaToken を使用した URL を含みます)。

これらのトークンは、startDateTime パラメーターと endDateTime パラメーター、および最初のデルタ クエリの GET 要求内の他のすべてのクエリ パラメーターをエンコードする state tokens です。 これらのパラメーターはトークンにエンコードされるため、後続の要求にこれらのパラメーターを含める必要はありません。

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

これらの @odata.nextLink と @odata.deltaLink の URL を使用する方法については、以下の 例 を参照してください。

カレンダー ビューのデルタ クエリでクエリ パラメーターを使用する

  • startDateTime パラメーターと endDateTime パラメーターを含めて、カレンダー ビューの日付/時刻範囲を定義します。
  • $select はサポートされていません。

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

各デルタ クエリの GET 要求は、応答で 1 つ以上のイベントのコレクションを返します。 必要に応じて、要求ヘッダー Prefer: odata.maxpagesize={x} を指定して、応答内の最大イベント数を設定できます。

例: カレンダー ビューのイベントを同期させる

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

簡潔にするため、サンプルの応答にはイベントのプロパティのサブセットのみを表示します。 実際の呼び出しでは、ほとんどのイベント プロパティが返されます。

次のラウンド で行う操作も参照してください。

手順 1: 最初の要求のサンプル

この例では、サインインしているユーザーのデフォルトカレンダーで指定されたカレンダービューが初めて同期されているため、最初の同期要求には状態トークンが含まれていません。 このラウンドは、そのカレンダー ビュー内のすべてのイベントを返します。

最初の要求では、次を指定します。

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

最初の応答のサンプル

応答には、2 つのイベントと、 を含む @odata.nextLink 応答ヘッダーが skipToken含まれます。 URL は、取得するカレンダー ビューにさらにイベントがあることを示します。

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.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.com"
                }
            },
            "id":"AAMkADVxSAAA="
        }
    ]
}

手順 2: 2 番目の要求のサンプル

2 番目の要求では、前の応答で返された @odata.nextLink URL が指定されます。 URL 内の と同じ startDateTime パラメーターと endDateTime パラメーターを指定skipToken@odata.nextLinkする必要がなくなりました。

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

2 番目の応答のサンプル

2 番目の応答は、カレンダー ビューから取得するイベントがまだあることを示す、カレンダー ビュー内の次の 2 つのイベントと別の @odata.nextLink を返します。

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.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.com"
                }
            },
            "id":"AAMkADVxUAAA="
        }
    ]
}

手順 3: 3 番目の要求のサンプル

3 番目の要求は、最後の同期要求から返された最新の @odata.nextLink を引き続き使用します。

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

3 番目と最後の応答のサンプル

3 番目の応答は、予定表ビューに残っている唯一のイベントと @odata.deltaLink 、この予定表ビューの同期が完了したことを示す URL を返します。 URL を @odata.deltaLink 保存して使用して、 次のラウンドでその予定表ビューを同期します。

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.com"
                }
            },
            "id":"AAMkADj1HuAAA="
        }
    ]
}

次のラウンド: 最初の要求のサンプル

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

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

次のラウンド: 最初の応答のサンプル

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.com"
                }
            },
            "id":"AAMkADj1HvAAA="
        }
    ]
}

関連コンテンツ