Pengguna dapat dengan bebas memperbarui atau menghapus acara Google Kalender mereka. Jika pengguna memperbarui peristiwa setelah membuat konferensi untuknya, add-on Anda mungkin perlu merespons perubahan tersebut dengan memperbarui data konferensi. Jika sistem konferensi pihak ketiga Anda bergantung pada pelacakan data acara, kegagalan untuk memperbarui konferensi pada perubahan acara dapat membuat konferensi tidak dapat digunakan dan menghasilkan pengalaman pengguna yang buruk.
Proses untuk terus memperbarui data konferensi dengan perubahan pada acara Google Kalender disebut sinkronisasi. Anda dapat menyinkronkan perubahan acara dengan membuat pemicu yang dapat diinstal Apps Script yang diaktifkan setiap kali acara berubah di kalender tertentu. Sayangnya, pemicu tidak melaporkan peristiwa mana yang berubah dan Anda tidak dapat membatasinya hanya untuk peristiwa dengan konferensi yang Anda buat. Sebagai gantinya, Anda harus meminta daftar semua perubahan yang dilakukan pada kalender sejak sinkronisasi terakhir, memfilter daftar acara, dan melakukan pembaruan yang sesuai.
Prosedur sinkronisasi umum adalah sebagai berikut:
- Saat pengguna pertama kali membuat konferensi, proses sinkronisasi akan diinisialisasi.
- Setiap kali pengguna membuat, memperbarui, atau menghapus salah satu acara Kalendernya, pemicu akan menjalankan fungsi pemicu dalam project add-on Anda.
- Fungsi pemicu memeriksa kumpulan perubahan peristiwa sejak sinkronisasi terakhir dan menentukan apakah ada yang memerlukan pembaruan konferensi pihak ketiga terkait.
- Setiap pembaruan yang diperlukan dilakukan pada konferensi dengan membuat permintaan API pihak ketiga.
- Token sinkronisasi baru disimpan sehingga eksekusi pemicu berikutnya hanya perlu memeriksa perubahan terbaru pada kalender.
Melakukan inisialisasi sinkronisasi
Setelah berhasil membuat konferensi di sistem pihak ketiga, add-on ini akan membuat pemicu yang dapat diinstal yang merespons perubahan acara di kalender ini, jika pemicu belum ada.
Setelah membuat pemicu, inisialisasi akan selesai dengan membuat token sinkronisasi awal. Hal ini dilakukan dengan menjalankan fungsi pemicu secara langsung.
Membuat pemicu Kalender
Untuk menyinkronkan, add-on Anda harus mendeteksi saat acara Kalender yang memiliki konferensi terlampir diubah. Hal ini dilakukan dengan membuat pemicu yang dapat diinstal EventUpdated
. Add-on Anda
hanya memerlukan satu pemicu untuk setiap kalender, dan dapat membuatnya secara terprogram.
Waktu yang tepat untuk membuat pemicu adalah saat pengguna membuat konferensi pertamanya, karena pada saat itu pengguna mulai menggunakan add-on. Setelah membuat konferensi dan memverifikasi bahwa tidak ada error, add-on Anda harus memeriksa apakah pemicu ada untuk pengguna ini dan jika tidak, buat pemicu.
Mengimplementasikan fungsi pemicu sinkronisasi
Fungsi pemicu dijalankan saat Apps Script mendeteksi kondisi yang menyebabkan pemicu diaktifkan.
Pemicu kalender EventUpdated
diaktifkan saat pengguna membuat, mengubah, atau menghapus acara apa pun di kalender
yang ditentukan.
Anda harus menerapkan fungsi pemicu yang digunakan add-on. Fungsi pemicu ini harus melakukan hal berikut:
- Lakukan panggilan
Calendar.Events.list()
layanan lanjutan Kalender menggunakansyncToken
untuk mengambil daftar peristiwa yang telah berubah sejak sinkronisasi terakhir. Dengan menggunakan token sinkronisasi, Anda mengurangi jumlah peristiwa yang harus diperiksa oleh add-on.Saat fungsi pemicu dijalankan tanpa token sinkronisasi yang valid, fungsi tersebut akan kembali ke sinkronisasi penuh. Sinkronisasi penuh hanya mencoba mengambil semua peristiwa dalam jangka waktu yang ditentukan untuk membuat token sinkronisasi baru yang valid.
- Setiap peristiwa yang diubah akan diperiksa untuk menentukan apakah peristiwa tersebut memiliki konferensi pihak ketiga yang terkait.
- Jika peristiwa memiliki konferensi, peristiwa tersebut akan diperiksa untuk melihat apa yang diubah. Bergantung pada perubahannya, modifikasi konferensi terkait mungkin diperlukan. Misalnya, jika peristiwa dihapus, add-on mungkin juga akan menghapus konferensi.
- Setiap perubahan yang diperlukan pada konferensi dilakukan dengan melakukan panggilan API ke sistem pihak ketiga.
- Setelah melakukan semua perubahan yang diperlukan, simpan
nextSyncToken
yang ditampilkan oleh metodeCalendar.Events.list()
. Token sinkronisasi ini ditemukan di halaman hasil terakhir yang ditampilkan oleh panggilanCalendar.Events.list()
.
Memperbarui acara Google Kalender
Dalam beberapa kasus, Anda mungkin ingin memperbarui acara Google Kalender saat melakukan
sinkronisasi. Jika Anda memilih untuk melakukannya, perbarui acara dengan permintaan
layanan lanjutan Google Kalender
yang sesuai. Pastikan untuk menggunakan
pembaruan bersyarat
dengan header If-Match
. Hal ini mencegah perubahan Anda secara tidak sengaja
mengganti perubahan serentak yang dibuat oleh pengguna di klien lain.
Contoh
Contoh berikut menunjukkan cara menyiapkan sinkronisasi untuk acara kalender dan konferensi terkait.
/** * 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. } }