Menyinkronkan perubahan konferensi kalender

Pengguna dapat dengan bebas memperbarui atau menghapus acara Google Kalender mereka. Jika pengguna memperbarui acara setelah membuat konferensi untuknya, add-on Anda mungkin perlu merespons perubahan dengan memperbarui data konferensi. Jika sistem konferensi pihak ketiga bergantung pada pemantauan data peristiwa, kegagalan mengupdate konferensi pada perubahan peristiwa dapat menyebabkan konferensi tidak dapat digunakan dan menghasilkan pengalaman pengguna yang buruk.

Proses memperbarui data konferensi dengan perubahan pada acara Google Kalender disebut sinkronisasi. Anda dapat menyinkronkan perubahan peristiwa dengan membuat pemicu yang dapat diinstal Apps Script yang aktif setiap kali peristiwa berubah dalam 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 dibuat pada kalender sejak sinkronisasi terakhir, memfilter daftar peristiwa, dan membuat pembaruan yang sesuai.

Prosedur sinkronisasi umumnya adalah sebagai berikut:

1. Saat pertama kali pengguna membuat konferensi, proses sinkronisasi akan diinisialisasi.
2. Setiap kali pengguna membuat, memperbarui, atau menghapus salah satu peristiwa Kalender, pemicu akan menjalankan fungsi pemicu dalam project add-on Anda.
3. Fungsi pemicu memeriksa kumpulan perubahan peristiwa sejak sinkronisasi terakhir dan menentukan apakah ada yang memerlukan pembaruan konferensi pihak ketiga terkait.
4. Update yang diperlukan akan dilakukan pada konferensi dengan membuat permintaan API pihak ketiga.
5. Token sinkronisasi baru disimpan sehingga eksekusi pemicu berikutnya hanya perlu memeriksa perubahan terbaru pada kalender.

Menginisialisasi sinkronisasi

Setelah berhasil membuat konferensi di sistem pihak ketiga, add-on harus membuat pemicu yang dapat diinstal yang merespons perubahan peristiwa di kalender ini, jika pemicu belum ada.

Setelah membuat pemicu, inisialisasi harus diselesaikan dengan membuat token sinkronisasi awal. Hal ini dilakukan dengan menjalankan fungsi pemicu secara langsung.

Membuat pemicu Kalender

Untuk menyinkronkan, add-on perlu mendeteksi saat acara Kalender yang memiliki lampiran konferensi diubah. Hal ini dilakukan dengan membuat pemicu yang dapat diinstal EventUpdated. Add-on 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 memastikan tidak ada error, add-on harus memeriksa apakah pemicu ada untuk pengguna ini dan membuatnya tidak.

Catatan: Pembuatan pemicu mengharuskan add-on Anda diberi otorisasi dengan cakupan https://www.googleapis.com/auth/calendar.readonly dan https://www.googleapis.com/auth/script.scriptapp.

Mengimplementasikan fungsi pemicu sinkronisasi

Fungsi pemicu dijalankan saat Apps Script mendeteksi kondisi yang menyebabkan pemicu diaktifkan. Pemicu EventUpdated Kalender aktif 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 akan melakukan hal berikut:

1. Lakukan panggilan Calendar.Events.list() layanan lanjutan Kalender menggunakan syncToken untuk mengambil daftar acara yang telah berubah sejak sinkronisasi terakhir. Dengan menggunakan token sinkronisasi, Anda mengurangi jumlah peristiwa yang harus diperiksa add-on.

   Jika dijalankan tanpa token sinkronisasi yang valid, fungsi pemicu akan di-backoff ke sinkronisasi penuh. Sinkronisasi penuh hanya mencoba mengambil semua peristiwa dalam jangka waktu yang ditentukan untuk menghasilkan token sinkronisasi baru yang valid.

   Perhatian: Terkadang token sinkronisasi dibatalkan oleh server, sehingga menghasilkan error Sync token is no longer valid. Jika ini terjadi, kode Anda harus melakukan sinkronisasi penuh dan mengganti semua token sinkronisasi tersimpan yang Anda miliki.
2. Setiap peristiwa yang diubah akan diperiksa untuk menentukan apakah peristiwa tersebut memiliki konferensi pihak ketiga terkait.
3. Jika suatu acara memiliki konferensi, acara tersebut akan diperiksa untuk melihat apa yang telah berubah. Bergantung pada perubahannya, modifikasi konferensi terkait mungkin diperlukan. Misalnya, jika acara dihapus, add-on mungkin juga akan menghapus konferensi tersebut.
4. Setiap perubahan yang diperlukan pada konferensi akan dibuat dengan melakukan panggilan API ke sistem pihak ketiga.
5. Setelah membuat semua perubahan yang diperlukan, simpan nextSyncToken yang ditampilkan oleh metode Calendar.Events.list(). Token sinkronisasi ini ditemukan di halaman terakhir hasil yang ditampilkan oleh panggilan Calendar.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 update bersyarat dengan header If-Match. Hal ini mencegah perubahan Anda secara tidak sengaja mengganti perubahan serentak yang dibuat oleh pengguna pada klien yang berbeda.

Contoh

Contoh berikut menunjukkan cara menyiapkan sinkronisasi untuk acara kalender dan konferensi terkaitnya.

/**
 *  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.

  }
}