イベント: デルタ
名前空間: microsoft.graph
重要
Microsoft Graph の /beta
バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
1 つ以上の予定表で追加、削除、または更新された一連の イベント リソースを取得します。
これらの増分変更の特定の種類は、メールボックスのすべての予定表または特定の予定表のイベント、または 予定表の calendarView のイベント コレクション (開始日と終了日で定義されたイベントの範囲) で取得できます。 予定表には、既定の予定表、またはユーザーの指定した他の予定表を指定できます。 calendarView で増分変更を取得する場合は、予定表をグループ予定表にすることもできます。
通常、ローカル ストアの予定表または calendarView でイベントを同期するには、複数の デルタ 関数呼び出しのラウンドが必要です。 最初の呼び出しは完全同期で、同じラウンドの後続の 差分 呼び出しはすべて増分の変更 (追加、削除、更新) を取得します。 これにより、その予定表のすべてのイベントをサーバーから毎回フェッチすることなく、指定した予定表内のイベントのローカル ストアを維持および同期できます。
次の表に、イベントのデルタ関数と予定表の calendarView のデルタ関数の違いを示します。
イベントに対する Delta 関数 | calendarView の Delta 関数 |
---|---|
開始日と終了日の範囲で囲まれていない予定表のすべてのイベントの増分変更を取得します。 または、カレンダー内のイベントの増分変更を、その日付/時刻以降の開始時刻で囲んで取得することもできます。 | calendarView の開始時刻と終了日時内のイベントの増分変更を取得します。 |
パフォーマンス上の理由から、 限られたイベント プロパティのセットのみを返します。 その後、 GET /events/{id} を使用してイベントを展開するクライアント。 |
サーバー側の拡張は、 イベント プロパティの完全なセットを返します。 |
応答には、単一インスタンスと定期的なシリーズ マスターが含まれます。 | 応答には、1 つのインスタンスと、定期的な系列の発生と例外が含まれます。 |
ユーザー予定表のイベントに適用されますが、グループ予定表には適用されません。 | ユーザーとグループの予定表のイベントに適用されます。 |
現在、ベータ版でのみ使用できます。 | v1.0 およびベータ 版で使用できます。 |
この API は、次の国内クラウド展開で使用できます。
グローバル サービス | 米国政府機関 L4 | 米国政府機関 L5 (DOD) | 21Vianet が運営する中国 |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
アクセス許可
この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。
アクセス許可の種類 | 最小特権アクセス許可 | より高い特権のアクセス許可 |
---|---|---|
委任 (職場または学校のアカウント) | Calendars.ReadBasic | Calendars.Read、Calendars.ReadWrite |
委任 (個人用 Microsoft アカウント) | Calendars.ReadBasic | Calendars.Read、Calendars.ReadWrite |
アプリケーション | Calendars.Read | Calendars.ReadBasic、Calendars.ReadWrite |
HTTP 要求
このセクションでは、指定した予定表または予定表ビューのすべてのイベントを取得する完全同期を開始するための、初期 デルタ 関数呼び出しの HTTP 要求構文を示します。 この構文には 、状態トークンは含まれません。
成功した応答の @odata.nextLink
または @odata.deltaLink
で返されるクエリ URL には、状態トークンが含まれます。 それ以降の デルタ 関数呼び出しでは、 @odata.nextLink
内のクエリ URL を使用するか、その前に @odata.deltaLink
します。
ユーザー 予定表のイベントに対する Delta 関数 (プレビュー)
指定したユーザー カレンダーで、特定の日付/時刻以降のすべてのイベントまたはイベントに デルタ 関数を適用します。
すべてのイベント、または ユーザーのメールボックスで指定された日付/時刻以降から開始されるイベントの増分変更を取得するには、
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}
すべてのイベント、または ユーザーの既定の予定表で指定した日時以降に開始されるイベントの増分変更を取得するには:
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}
すべてのイベント、または 指定したユーザーカレンダーで指定した日付/時刻以降から開始するイベントの増分変更を取得するには:
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}
増分変更を取得するには、すべてのイベント、または 指定した予定表グループと予定表の指定した日付/時刻以降のイベントの変更を行います。
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}
ユーザー予定表の calendarView の Delta 関数
指定したユーザー カレンダーで、開始日と終了日時で区切られたイベントの範囲に デルタ 関数を適用します。
ユーザーの既定の予定表の予定表ビューで増分変更を取得するには:
GET /me/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime} GET /users/{id}/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}
指定したユーザー予定表の予定表ビューで増分変更を取得するには:
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}
calendarView のグループ 予定表の Delta 関数
- グループの予定表の予定表ビューで増分変更 を取得するには:
GET /groups/{id}/calendarView?startDateTime={start_datetime}&endDateTime={end_datetime}
クエリ パラメーター
変更を追跡すると、1 つ以上の デルタ 関数呼び出しのラウンドが発生します。 任意のクエリ パラメーター ($deltatoken
と$skiptoken
以外) を使用する場合は、最初のデルタ要求でこれを指定する必要があります。 Microsoft Graph は、応答で提供される @odata.nextLink
または @odata.deltaLink
の URL のトークン部分に指定したパラメーターを自動的にエンコードします。 必要なクエリ パラメーターを前もって 1 回指定しておくだけで済みます。
後続の要求では、前の応答の @odata.nextLink
または @odata.deltaLink
URL をコピーして適用するだけです。その URL には、エンコードされた目的のパラメーターが既に含まれています。
クエリ パラメーター | 種類 | 説明 |
---|---|---|
startDateTime | String | 時間範囲の開始日時は、ISO 8601 形式で表されます。 たとえば、"2019-11-08T19:00:00-08:00" です。 タイムゾーンはパラメーター値のタイムゾーンオフセット部分で指定され、存在する場合は Prefer: outlook.timezone ヘッダーの影響を受けません。 タイムゾーン オフセットが値に含まれていない場合、UTC と解釈されます。予定表のイベントの デルタ の場合は省略可能です。 calendarView のデルタに必要です。 |
endDateTime | String | 時間範囲の終了日時は、ISO 8601 形式で表されます。 たとえば、"2019-11-08T20:00:00-08:00" です。 タイムゾーンはパラメーター値のタイムゾーンオフセット部分で指定され、存在する場合は Prefer: outlook.timezone ヘッダーの影響を受けません。 タイムゾーン オフセットが値に含まれていない場合、UTC と解釈されます。予定表のイベントのデルタではサポートされていません。 calendarView のデルタに必要です。 |
$deltatoken | string | 同じ予定表ビューの前のデルタ関数呼び出しの@odata.deltaLink URL で返された状態トークン。変更追跡のラウンドの完了を示します。 このトークンを含む @odata.deltaLink URL 全体を保存して、その予定表ビューの次の一覧の変更追跡の最初の要求に適用します。 |
$skiptoken | string | 前のデルタ関数呼び出しの @odata.nextLink URL 内で返された状態トークンで、同じカレンダー ビュー内に追跡されるべきさらなる変化があることを示しています。 |
OData クエリ パラメーター
calendarView での delta 関数の呼び出しは、通常の
GET /calendarView
要求で取得するものと同じプロパティを返すことを予想します。$select
を使用して、それらのプロパティのサブセットのみを取得することはできません。delta 関数では、ユーザー予定表のイベント、または calendarView のイベントに対するクエリ パラメーター (
$expand
、$filter
、$orderby
、$search
、$select
) はサポートされていません。
要求ヘッダー
名前 | 種類 | 説明 |
---|---|---|
Authorization | string | ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。 |
Content-Type | string | application/json. Required. |
Prefer | string | odata.maxpagesize={x}。 省略可能。 |
Prefer | string | outlook.timezone={タイム ゾーン文字列}。 省略可能。存在しない場合は UTC と見なされます。 |
応答
イベントの Delta 関数 (プレビュー)
成功した場合、このメソッドは 200 OK
応答コードと、応答本文の イベント コレクションを返します。 応答の各 イベント には、パフォーマンス上の理由から id、 type、 start 、 end の各プロパティのみが含まれています。 後で GET /events/{id}
を使用して、応答からイベントを展開します。
calendarView の Delta 関数
成功した場合、このメソッドは 200 OK
応答コードと、応答本文の イベント コレクションを返します。
GET /calendarView
要求から通常取得するすべてのプロパティを取得することを想定しています。
calendarView の日付範囲にバインドされた delta 関数呼び出しのラウンド内で、差分呼び出しが @removed
以下の 2 種類のイベントを以下の deleted
の理由で返すことがあります。
- 日付範囲内にあり、前回の差分呼び出し以降に削除されたイベント。
- 日付範囲外にあり、前回の差分呼び出し以降に追加、削除、または更新されたイベント。
シナリオで必要とされる日付範囲の @removed
以下のイベントをフィルター処理します。
例
例 1: 予定表のイベントに対する Delta 関数 (プレビュー)
要求
次の例は、サインインしているユーザーの既定の予定表でイベントを取得するための初期同期要求を示しています。これは、指定した startDateTime
パラメーターの前後に発生します。 最初の要求には、状態トークンは含まれません。
要求では、 Prefer: odata.maxpagesize
ヘッダーを使用して、各応答のイベントの最大数を 1 に制限します。
応答に@odata.deltaLink
が表示されるまで、@odata.nextLink
で返されたクエリを使用して、delta
関数の呼び出しを続行します。
GET https://graph.microsoft.com/beta/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z
Prefer: odata.maxpagesize=1
応答
要求が成功した場合、応答には状態トークンが含まれます。これは skipToken ( @odata.nextLink 応答ヘッダー内) または deltaToken ( @odata.deltaLink 応答ヘッダー内)。 それぞれ、ラウンドを続行するか、そのラウンドのすべての変更の取得を完了したかを示します。
以下の応答は、@odata.nextLink 応答ヘッダーに含まれる skipToken を示しています。
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"
}
}
]
}
例 2: calendarView の Delta 関数
要求
次の例は、 calendarView によって示される日付の範囲内で、サインインしているユーザーの指定した予定表でイベントを取得するための初期同期要求を示しています。 最初の要求には、状態トークンは含まれません。
要求では、 Prefer: odata.maxpagesize
ヘッダーを使用して、各応答のイベントの最大数を 2 に制限します。 その予定表ビューのすべてのイベントと応答で@odata.deltaLink
が取得されるまで、@odata.nextLink
で返されたクエリを使用して、delta
関数の呼び出しを続行します。
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
応答
要求が成功した場合、応答には状態トークンが含まれます。これは skipToken ( @odata.nextLink 応答ヘッダー内) または deltaToken ( @odata.deltaLink 応答ヘッダー内)。 それぞれ、ラウンドを続行するか、そのラウンドのすべての変更の取得を完了したかを示します。
以下の応答は、@odata.nextLink 応答ヘッダーに含まれる skipToken を示しています。
注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。
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\"> </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\"> </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"
}
}
}
]
}