Sinkronkan perubahan konferensi kalender

Pengguna dapat memperbarui atau menghapus acara Google Kalender mereka. Jika pengguna memperbarui acara setelah membuat konferensi untuk acara tersebut, add-on Google Workspace Anda mungkin perlu merespons perubahan dengan memperbarui data konferensi. Jika sistem konferensi pihak ketiga Anda bergantung pada pelacakan data peristiwa, tidak memperbarui konferensi saat terjadi perubahan acara dapat membuat konferensi tidak dapat digunakan.

Proses menjaga agar data konferensi tetap diperbarui dengan perubahan pada acara Kalender disebut penyinkronan. Sinkronkan perubahan acara dengan membuat pemicu yang dapat diinstal Google Apps Script yang diaktifkan setiap kali acara berubah dalam kalender tertentu. Pemicu tidak melaporkan peristiwa mana yang berubah dan Anda tidak dapat membatasinya hanya pada peristiwa dengan konferensi yang Anda buat. Minta daftar semua perubahan yang dilakukan pada kalender sejak sinkronisasi terakhir, filter daftar acara, dan lakukan 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 di project add-on Anda.
Fungsi pemicu memeriksa kumpulan perubahan peristiwa sejak sinkronisasi terakhir dan menentukan apakah ada perubahan yang memerlukan pembaruan konferensi pihak ketiga terkait.
Pembaruan yang diperlukan dilakukan pada konferensi dengan membuat permintaan API pihak ketiga.
Token sinkronisasi baru disimpan sehingga eksekusi pemicu berikutnya hanya memeriksa perubahan terbaru pada kalender.

Menginisialisasi sinkronisasi

Proses inisialisasi memastikan add-on Anda siap merespons perubahan kalender. Setelah add-on berhasil membuat konferensi di sistem pihak ketiga, add-on harus 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 perlu mendeteksi saat acara Kalender yang memiliki konferensi terlampir diubah. Hal ini dapat 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 direkomendasikan untuk membuat pemicu adalah saat pengguna membuat konferensi pertama mereka, 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 membuatnya jika tidak ada.

Untuk membuat pemicu, add-on harus memiliki https://www.googleapis.com/auth/calendar.readonly dan https://www.googleapis.com/auth/script.scriptapp cakupan.

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 dalam kalender tertentu.

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

Lakukan panggilan layanan lanjutan Kalender Calendar.Events.list 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 Anda.

Saat fungsi pemicu dieksekusi tanpa token sinkronisasi yang valid, fungsi tersebut akan melakukan sinkronisasi penuh. Sinkronisasi penuh mencoba mengambil semua acara dalam jangka waktu yang ditentukan untuk membuat token sinkronisasi baru yang valid.

Perhatian: Terkadang token sinkronisasi dibatalkan validasinya oleh server, sehingga menghasilkan error Sync token is no longer valid. Jika hal ini terjadi, kode Anda harus melakukan sinkronisasi penuh dan mengganti token sinkronisasi tersimpan yang Anda miliki.
Setiap acara yang diubah diperiksa untuk menentukan apakah acara tersebut memiliki konferensi pihak ketiga yang terkait.
Jika suatu acara memiliki konferensi, acara tersebut akan diperiksa untuk melihat apa yang diubah. Bergantung pada perubahan, modifikasi konferensi terkait mungkin diperlukan. Misalnya, jika acara dihapus, add-on harus menghapus konferensi.
Perubahan yang diperlukan pada konferensi dilakukan dengan membuat panggilan API ke sistem pihak ketiga.
Setelah melakukan 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 Kalender

Dalam beberapa kasus, Anda mungkin ingin memperbarui acara Kalender saat melakukan sinkronisasi. Jika Anda memilih untuk melakukannya, perbarui acara dengan permintaan layanan lanjutan Kalender yang sesuai. Pastikan untuk menggunakan pembaruan bersyarat dengan header If-Match. Hal ini mencegah perubahan Anda menimpa perubahan serentak yang dilakukan oleh pengguna di klien yang berbeda.

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.

  }
}