Menyinkronkan perubahan konferensi kalender

Catatan: Fungsi ini dibuat khusus untuk penyedia konferensi, dan awalnya tersedia sebagai add-on konferensi Kalender.

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 peristiwa, kegagalan dalam memperbarui konferensi saat perubahan acara dapat menyebabkan konferensi tidak dapat digunakan dan menghasilkan pengalaman pengguna yang buruk.

Proses pembaruan 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 ke 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 melakukan pembaruan yang sesuai.

Prosedur sinkronisasi umum adalah sebagai berikut:

1. Saat pengguna pertama kali membuat konferensi, proses sinkronisasi akan diinisialisasi.
2. Setiap kali pengguna membuat, memperbarui, atau menghapus salah satu acara Kalender, pemicu akan menjalankan fungsi pemicu di 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. Setiap pembaruan yang diperlukan 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.

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 harus diselesaikan 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 EventUpdated pemicu yang dapat diinstal. 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 memastikan tidak ada error, add-on Anda akan memeriksa apakah pemicu ada untuk pengguna ini atau tidak, dan jika tidak membuatnya.

Catatan: Untuk membuat pemicu, add-on Anda harus diizinkan 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 Kalender EventUpdated aktif saat pengguna membuat, mengubah, atau menghapus acara apa pun dalam kalender tertentu.

Anda harus menerapkan fungsi pemicu yang digunakan add-on Anda. Fungsi pemicu ini harus melakukan hal berikut:

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

   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.

   Perhatian: Terkadang token sinkronisasi tidak valid oleh server, sehingga menyebabkan error Sync token is no longer valid. Jika hal ini terjadi, kode Anda harus melakukan sinkronisasi penuh dan mengganti token sinkronisasi yang disimpan.
2. Setiap peristiwa yang diubah akan diperiksa untuk menentukan apakah peristiwa tersebut memiliki konferensi pihak ketiga yang terkait.
3. Jika peristiwa memiliki konferensi, peristiwa tersebut akan diperiksa untuk melihat apa yang diubah. Tergantung pada perubahannya, modifikasi pada konferensi terkait mungkin diperlukan. Misalnya, jika peristiwa dihapus, add-on mungkin juga akan menghapus konferensi.
4. Setiap perubahan yang diperlukan pada konferensi dilakukan dengan melakukan panggilan API ke sistem pihak ketiga.
5. Setelah melakukan semua perubahan yang diperlukan, simpan nextSyncToken yang ditampilkan oleh metode Calendar.Events.list(). Token sinkronisasi ini ditemukan di halaman hasil terakhir 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 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.

  }
}