ユーザーは各自の Google カレンダーの予定を自由に更新、削除できます。ユーザーが会議を作成した後に予定を更新する場合、アドオンで会議データを更新して変更が必要になることがあります。サードパーティ製の会議システムがイベントデータの追跡に依存している場合、イベントの変更時に会議を更新しないと会議が使用できなくなり、ユーザー エクスペリエンスが低下する可能性があります。
Google カレンダーの予定に変更が加えられた会議データを最新の状態に保つプロセスを「同期」と呼びます。イベントの変更を同期するには、Apps Script のインストール可能なトリガーを作成します。このトリガーは、特定のカレンダーでイベントが変更されるたびに呼び出されます。残念ながら、トリガーで変更されたイベントは報告されず、作成した会議を含むイベントのみに制限することはできません。代わりに、前回の同期以降にカレンダーに加えられたすべての変更のリストをリクエストし、それに応じて予定をフィルタして更新する必要があります。
一般的な同期手順は次のとおりです。
- ユーザーが初めて会議を作成すると、同期処理が初期化されます。
- ユーザーがカレンダーの予定を作成、更新、削除するたびに、アドオン プロジェクト内でトリガーがトリガーされます。
- トリガー関数は、前回の同期以降の一連のイベント変更を調べて、関連するサードパーティ会議の更新が必要かどうかを判断します。
- サードパーティの API リクエストを行うと、カンファレンスに必要な更新が行われる。
- 新しい同期トークンが保存されるため、次のトリガーの実行で、カレンダーへの最新の変更を確認するだけで済みます。
同期を初期化する
アドオンがサードパーティのシステムで会議を正常に作成したら、トリガーがまだ存在しない場合は、このカレンダーのイベントの変更に応答するインストール可能なトリガーを作成する必要があります。
トリガーを作成したら、初期同期トークンを作成して初期化を終了します。これを行うには、トリガー関数を直接実行します。
カレンダーのトリガーを作成する
同期するには、会議が関連付けられているカレンダーの予定が変更されたときに、アドオンが検出する必要があります。これを行うには、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.
}
}