イベント: デルタ

[アーティクル]
06/22/2024

名前空間: 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



mgc-beta users calendar events delta get --user-id {user-id} --start-date-time "2020-06-12T00:00:00Z"

重要

Microsoft Graph SDK では、既定で v1.0 バージョンの API が使用され、ベータ版で使用可能なすべての型、プロパティ、API がサポートされているわけではありません。 SDK を使用してベータ API にアクセスする方法の詳細については、「ベータ API で Microsoft Graph SDK を使用する」を参照してください。

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z')
	.version('beta')
	.get();

重要

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

応答

要求が成功した場合、応答には状態トークンが含まれます。これは 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



mgc-beta users calendars calendar-view delta get --user-id {user-id} --calendar-id {calendar-id} --start-date-time "2020-06-01T00:00:00Z" --end-date-time "2020-06-10T00:00:00Z"

重要

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。


const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?startDateTime=2020-06-01T00:00:00Z&endDateTime=2020-06-10T00:00:00Z')
	.version('beta')
	.get();

重要

プロジェクトに SDK を追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

応答

以下の応答は、@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\">&nbsp;</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\">&nbsp;</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"
                }
            }
        }
    ]
}

次の方法で共有

イベント: デルタ

アクセス許可

HTTP 要求

ユーザー予定表のイベントに対する Delta 関数 (プレビュー)

ユーザー予定表の calendarView の Delta 関数

calendarView のグループ予定表の Delta 関数

クエリパラメーター

OData クエリパラメーター

要求ヘッダー

応答

イベントの Delta 関数 (プレビュー)

calendarView の Delta 関数

例

例 1: 予定表のイベントに対する Delta 関数 (プレビュー)

要求

応答

例 2: calendarView の Delta 関数

要求

応答

フィードバック

フィードバック

その他のリソース

次の方法で共有

イベント: デルタ

アクセス許可

HTTP 要求

ユーザー 予定表のイベントに対する Delta 関数 (プレビュー)

ユーザー予定表の calendarView の Delta 関数

calendarView のグループ 予定表の Delta 関数

クエリ パラメーター

OData クエリ パラメーター

要求ヘッダー

応答

イベントの Delta 関数 (プレビュー)

calendarView の Delta 関数

例

例 1: 予定表のイベントに対する Delta 関数 (プレビュー)

要求

応答

例 2: calendarView の Delta 関数

要求

応答

関連コンテンツ

フィードバック

フィードバック

その他のリソース

ユーザー予定表のイベントに対する Delta 関数 (プレビュー)

calendarView のグループ予定表の Delta 関数

クエリパラメーター

OData クエリパラメーター