ユーザーは Google カレンダーの予定を自由に更新、削除できます。ユーザーが会議を作成した後に予定を更新した場合、アドオンは会議データを更新して変更に対応する必要があります。サードパーティの会議システムがイベントデータの追跡に依存している場合、イベントの変更時に会議を更新できないと、会議が使用できなくなり、ユーザー エクスペリエンスが低下する可能性があります。
Google カレンダーの予定の変更に合わせて会議データを更新するプロセスを「同期」と呼びます。特定のカレンダーでイベントが変更されると起動する Apps Script のインストール可能なトリガーを作成することで、イベントの変更を同期できます。トリガーは、どのイベントが変更されたかを報告しません。また、作成した会議のイベントのみに限定することはできません。代わりに、前回の同期以降にカレンダーに加えられたすべての変更のリストをリクエストし、イベントリストをフィルタして、それに応じて更新する必要があります。
一般的な同期手順は次のとおりです。
- ユーザーが初めて会議を作成すると、同期プロセスが初期化されます。
- ユーザーがカレンダーの予定の作成、更新、削除を行うと、トリガーによってアドオン プロジェクトのトリガー関数が実行されます。
- トリガー関数は、前回の同期以降の一連のイベント変更を調べ、関連するサードパーティの会議の更新が必要かどうかを判断します。
- 必要な場合は、サードパーティの API リクエストを行って会議を更新します。
- 新しい同期トークンが保存され、次回のトリガー実行では、カレンダーの最新の変更のみを調べるだけで済みます。
同期を初期化する
アドオンがサードパーティ システムで会議を正常に作成すると、このカレンダーのイベントの変更に応答するインストール可能なトリガーが作成されます(トリガーがまだ存在しない場合)。
トリガーの作成後、最初の同期トークンを作成して初期化を完了する必要があります。これを行うには、トリガー関数を直接実行します。
Calendar トリガーを作成する
会議が添付されているカレンダーの予定が変更されたことをアドオンが検出して同期するには、これを行うには、EventUpdated
インストール可能なトリガーを作成します。アドオンに必要なトリガーはカレンダーごとに 1 つだけで、プログラムで作成できます。
トリガーを作成するのは、最初の会議を作成するときです。最初の会議を作成した時点でユーザーはアドオンの使用を開始します。会議を作成し、エラーがないことを確認したら、アドオンはこのユーザーにトリガーが存在するかどうかを確認し、作成されていない場合は作成する必要があります。
同期トリガー関数を実装する
トリガー関数は、Apps Script がトリガーを起動する条件を検出すると実行されます。EventUpdated
カレンダー トリガーは、ユーザーが指定したカレンダーでイベントの作成、変更、削除を行うと呼び出されます。
アドオンで使用するトリガー関数を実装する必要があります。このトリガー関数は、次のことを行います。
syncToken
を使用してカレンダー拡張サービスのCalendar.Events.list()
呼び出しを行い、前回の同期以降に変更されたイベントのリストを取得します。同期トークンを使用することで、アドオンが調べるイベントの数を減らすことができます。有効な同期トークンなしでトリガー関数が実行されると、完全同期に戻ります。完全同期では、新しい有効な同期トークンを生成するために、指定された時間枠内のすべてのイベントの取得を試みます。
- 変更された各イベントを調べて、関連するサードパーティの会議があるかどうかを確認します。
- 予定に会議がある場合は、変更内容が確認されて変更を確認します。変更によっては、関連する会議の変更が必要になる場合があります。たとえば、予定が削除された場合、アドオンは会議も削除する必要があります。
- 会議に必要な変更は、サードパーティのシステムに対して API 呼び出しを行って行います。
- 必要な変更をすべて行ったら、
Calendar.Events.list()
メソッドから返されたnextSyncToken
を保存します。この同期トークンは、Calendar.Events.list()
呼び出しによって返された結果の最後のページにあります。
Google カレンダーの予定を更新する
場合によっては、同期の実行時に Google カレンダーの予定の更新が必要になることがあります。その場合は、適切な Google カレンダー拡張サービス リクエストを使用してイベントを更新します。If-Match
ヘッダーを使用して、条件付き更新を使用してください。これにより、別のクライアントでユーザーが同時に行った変更を誤って上書きすることがなくなります。
例
次の例は、カレンダーの予定とそれに関連する会議の同期を設定する方法を示しています。
/** * Initializes syncing of conference data by creating a sync trigger and * sync token if either does not exist yet. * * @param {String} calendarId The ID of the Google Calendar. */ function initializeSyncing(calendarId) { // Create a syncing trigger if it doesn't exist yet. createSyncTrigger(calendarId); // Perform an event sync to create the initial sync token. syncEvents({'calendarId': calendarId}); } /** * Creates a sync trigger if it does not exist yet. * * @param {String} calendarId The ID of the Google Calendar. */ function createSyncTrigger(calendarId) { // Check to see if the trigger already exists; if does, return. var allTriggers = ScriptApp.getProjectTriggers(); for (var i = 0; i < allTriggers.length; i++) { var trigger = allTriggers[i]; if (trigger.getTriggerSourceId() == calendarId) { return; } } // Trigger does not exist, so create it. The trigger calls the // 'syncEvents()' trigger function when it fires. var trigger = ScriptApp.newTrigger('syncEvents') .forUserCalendar(calendarId) .onEventUpdated() .create(); } /** * Sync events for the given calendar; this is the syncing trigger * function. If a sync token already exists, this retrieves all events * that have been modified since the last sync, then checks each to see * if an associated conference needs to be updated and makes any required * changes. If the sync token does not exist or is invalid, this * retrieves future events modified in the last 24 hours instead. In * either case, a new sync token is created and stored. * * @param {Object} e If called by a event updated trigger, this object * contains the Google Calendar ID, authorization mode, and * calling trigger ID. Only the calendar ID is actually used here, * however. */ function syncEvents(e) { var calendarId = e.calendarId; var properties = PropertiesService.getUserProperties(); var syncToken = properties.getProperty('syncToken'); var options; if (syncToken) { // There's an existing sync token, so configure the following event // retrieval request to only get events that have been modified // since the last sync. options = { syncToken: syncToken }; } else { // No sync token, so configure to do a 'full' sync instead. In this // example only recently updated events are retrieved in a full sync. // A larger time window can be examined during a full sync, but this // slows down the script execution. Consider the trade-offs while // designing your add-on. var now = new Date(); var yesterday = new Date(); yesterday.setDate(now.getDate() - 1); options = { timeMin: now.toISOString(), // Events that start after now... updatedMin: yesterday.toISOString(), // ...and were modified recently maxResults: 50, // Max. number of results per page of responses orderBy: 'updated' } } // Examine the list of updated events since last sync (or all events // modified after yesterday if the sync token is missing or invalid), and // update any associated conferences as required. var events; var pageToken; do { try { options.pageToken = pageToken; events = Calendar.Events.list(calendarId, options); } catch (err) { // Check to see if the sync token was invalidated by the server; // if so, perform a full sync instead. if (err.message === "Sync token is no longer valid, a full sync is required.") { properties.deleteProperty('syncToken'); syncEvents(e); return; } else { throw new Error(err.message); } } // Read through the list of returned events looking for conferences // to update. if (events.items && events.items.length > 0) { for (var i = 0; i < events.items.length; i++) { var calEvent = events.items[i]; // Check to see if there is a record of this event has a // conference that needs updating. if (eventHasConference(calEvent)) { updateConference(calEvent, calEvent.conferenceData.conferenceId); } } } pageToken = events.nextPageToken; } while (pageToken); // Record the new sync token. if (events.nextSyncToken) { properties.setProperty('syncToken', events.nextSyncToken); } } /** * Returns true if the specified event has an associated conference * of the type managed by this add-on; retuns false otherwise. * * @param {Object} calEvent The Google Calendar event object, as defined by * the Calendar API. * @return {boolean} */ function eventHasConference(calEvent) { var name = calEvent.conferenceData.conferenceSolution.name || null; // This version checks if the conference data solution name matches the // one of the solution names used by the add-on. Alternatively you could // check the solution's entry point URIs or other solution-specific // information. if (name) { if (name === "My Web Conference" || name === "My Recorded Web Conference") { return true; } } return false; } /** * Update a conference based on new Google Calendar event information. * The exact implementation of this function is highly dependant on the * details of the third-party conferencing system, so only a rough outline * is shown here. * * @param {Object} calEvent The Google Calendar event object, as defined by * the Calendar API. * @param {String} conferenceId The ID used to identify the conference on * the third-party conferencing system. */ function updateConference(calEvent, conferenceId) { // Check edge case: the event was cancelled if (calEvent.status === 'cancelled' || eventHasConference(calEvent)) { // Use the third-party API to delete the conference too. } else { // Extract any necessary information from the event object, then // make the appropriate third-party API requests to update the // conference with that information. } }