Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat konferensi pihak ketiga

Setiap solusi konferensi yang Anda tentukan dalam project skrip manifes memiliki onCreateFunction terkait. Add-on memanggil fungsi ini untuk membuat konferensi setiap kali pengguna mencoba memilih solusi konferensi itu dan peristiwa.

Anda harus mengimplementasikan setiap onCreateFunction yang dijelaskan dalam manifes add-on. Secara umum, fungsi ini harus melakukan hal berikut:

Ambil informasi acara Google Kalender, seperti ID acara atau daftar peserta, yang mungkin dibutuhkan oleh sistem konferensi pihak ketiga dalam untuk membuat konferensi.
Menghubungkan ke layanan konferensi pihak ketiga dan membuat konferensi baru menggunakan informasi acara Google Kalender.
Jika permintaan pembuatan konferensi gagal karena alasan tertentu, gunakan error informasi untuk membangun dan mengembalikan ConferenceData objek yang berisi ConferenceError. Jika tidak, selesaikan langkah berikutnya.
1. Lakukan inisialisasi sinkronisasi konferensi.
2. Gunakan informasi yang ditampilkan oleh layanan konferensi pihak ketiga untuk membangun dan mengembalikan ConferenceData .

Mengambil informasi peristiwa

Untuk membuat konferensi pihak ketiga mengenai informasi tertentu tentang Acara Google Kalender diperlukan. Informasi peristiwa yang diperlukan bervariasi di antara sistem konferensi pihak ketiga yang berbeda, tetapi sering kali ini mencakup waktu mulai acara, waktu berakhir, ringkasan, daftar peserta, dan ID.

Saat dipanggil, setiap onCreateFunction yang Anda tentukan akan menerima argumen yang berisi ID kalender dan acara. Anda bisa menggunakan ID ini untuk mengambil informasi peristiwa lengkap menggunakan Layanan lanjutan Google Kalender.

Google Kalender dapat menambahkan detail konferensi ke acara sebelum keberadaannya. Dalam kasus tersebut, Google Kalender akan meneruskan onCreateFunction valid eventId, tetapi panggilan berikutnya ke Calendar.Events.get() dapat menghasilkan respons {i>error<i} yang mengatakan peristiwa tersebut tidak ada. Dalam kasus ini, cara terbaik adalah membuat konferensi pihak ketiga menggunakan data placeholder; data ini diganti lain kali acara tersebut sinkronisasi.

Membuat konferensi pihak ketiga

Setelah onCreateFunction mengambil data peristiwa yang diperlukan, data harus sambungkan ke sistem konferensi pihak ketiga untuk membuat konferensi. Biasanya hal ini dilakukan dengan membuat permintaan API yang didukung oleh sistem konferensi pihak ketiga. Memeriksa dokumentasi untuk pihak ketiga solusi konferensi untuk menentukan permintaan API apa yang dapat Anda gunakan untuk membuat konferensi.

Di Apps Script, cara termudah untuk menangani pembuatan permintaan API eksternal adalah dengan menggunakan OAuth2 untuk Apps Script atau OAuth1 untuk Apps Script library open source. Anda juga dapat terhubung ke API eksternal menggunakan layanan UrlFetch, tetapi hal ini mengharuskan Anda menangani detail otorisasi secara eksplisit.

Setelah meminta pembuatan konferensi, Anda mungkin perlu melakukan untuk mengambil detail konferensi baru.

Melakukan inisialisasi sinkronisasi konferensi

Setelah add-on berhasil membuat konferensi di sistem pihak ketiga, diperlukan beberapa langkah untuk mengaktifkan menyinkronkan sehingga berubah menjadi acara Google Kalender tercermin dalam konferensi tersebut.

Lihat Menyinkronkan perubahan Kalender untuk mengetahui detail tentang cara menyiapkan sinkronisasi setelah pembuatan konferensi.

Membangun respons data konferensi

Menggunakan informasi konferensi yang dikembalikan oleh layanan pihak ketiga, onCreateFunction kemudian harus membangun dan menampilkan ConferenceData objek; tindakan Data konferensi menjelaskan konten objek ini. Google Kalender menggunakan data menggunakan informasi ini untuk mengarahkan pengguna ke konferensi setelah dimulai.

Saat membuat ConferenceData perlu diketahui bahwa ada beberapa batasan panjang {i>field<i}, format URI titik entri, dan kombinasi titik entri yang diizinkan. Misalnya, hanya boleh ada maksimal satu titik entri VIDEO dalam satu ConferenceData. Batasan ini sama dengan batasan yang dijelaskan di Kalender Event API untuk properti conferenceData, meskipun tidak semua kolom peristiwa API yang dijelaskan di sana yang tersedia di Apps Script.

Menangani error

Terkadang, pembuatan konferensi tidak dapat diselesaikan karena dari error yang ditampilkan oleh sistem konferensi pihak ketiga. Dalam kasus ini, add-on Anda harus menangani kondisi {i>error<i} secara kokoh dengan membangun dan mengembalikan ConferenceData objek yang berisi ConferenceError detail, agar Google Kalender dapat bertindak dengan sesuai.

Saat membuat objek ConferenceData untuk melaporkan error, Anda tidak boleh perlu menyertakan komponen ConferenceData apa pun selain dari Objek ConferenceError. ConferenceErrors dapat memiliki ConferenceErrorType, pesan {i>error<i}, dan dalam kasus otentikasi masalah, sebuah URL yang memungkinkan pengguna untuk {i>login<i} ke sistem konferensi pihak ketiga.

Contoh

Berikut ini adalah contoh onCreateFunction (perhatikan bahwa nama fungsi dapat berupa apa saja; Anda hanya perlu menentukannya di project add-on ).

Fungsi create3rdPartyConference() menghubungi sistem pihak ketiga untuk membuat konferensi di sana dan fungsi getAuthenticationUrl() membuat URL otentikasi sistem pihak ketiga. Hal ini tidak diterapkan sepenuhnya di sini, karena sangat bergantung pada detail sistem pihak ketiga.

Fungsi initializeSyncing() tidak ditampilkan di sini; model ini akan menangani yang diperlukan untuk sinkronisasi. Lihat Menyinkronkan perubahan kalender untuk mengetahui detailnya.

/**
 *  Creates a conference, then builds and returns a ConferenceData object
 *  with the corresponding conference information. This method is called
 *  when a user selects a conference solution defined by the add-on that
 *  uses this function as its 'onCreateFunction' in the add-on manifest.
 *
 *  @param {Object} arg The default argument passed to a 'onCreateFunction';
 *      it carries information about the Google Calendar event.
 *  @return {ConferenceData}
 */
function createConference(arg) {
  const eventData = arg.eventData;
  const calendarId = eventData.calendarId;
  const eventId = eventData.eventId;

  // Retrieve the Calendar event information using the Calendar
  // Advanced service.
  var calendarEvent;
  try {
    calendarEvent = Calendar.Events.get(calendarId, eventId);
  } catch (err) {
    // The calendar event does not exist just yet; just proceed with the
    // given event ID and allow the event details to sync later.
    console.log(err);
    calendarEvent = {
      id: eventId,
    };
  }

  // Create a conference on the third-party service and return the
  // conference data or errors in a custom JSON object.
  var conferenceInfo = create3rdPartyConference(calendarEvent);

  // Build and return a ConferenceData object, either with conference or
  // error information.
  var dataBuilder = ConferenceDataService.newConferenceDataBuilder();

  if (!conferenceInfo.error) {
    // No error, so build the ConferenceData object from the
    // returned conference info.

    var phoneEntryPoint = ConferenceDataService.newEntryPoint()
        .setEntryPointType(ConferenceDataService.EntryPointType.PHONE)
        .setUri('tel:+' + conferenceInfo.phoneNumber)
        .setPin(conferenceInfo.phonePin);

    var adminEmailParameter = ConferenceDataService.newConferenceParameter()
        .setKey('adminEmail')
        .setValue(conferenceInfo.adminEmail);

    dataBuilder.setConferenceId(conferenceInfo.id)
        .addEntryPoint(phoneEntryPoint)
        .addConferenceParameter(adminEmailParameter)
        .setNotes(conferenceInfo.conferenceLegalNotice);

    if (conferenceInfo.videoUri) {
      var videoEntryPoint = ConferenceDataService.newEntryPoint()
          .setEntryPointType(ConferenceDataService.EntryPointType.VIDEO)
          .setUri(conferenceInfo.videoUri)
          .setPasscode(conferenceInfo.videoPasscode);
      dataBuilder.addEntryPoint(videoEntryPoint);
    }

    // Since the conference creation request succeeded, make sure that
    // syncing has been enabled.
    initializeSyncing(calendarId, eventId, conferenceInfo.id);

  } else if (conferenceInfo.error === 'AUTH') {
    // Authenentication error. Implement a function to build the correct
    // authenication URL for the third-party conferencing system.
    var authenticationUrl = getAuthenticationUrl();
    var error = ConferenceDataService.newConferenceError()
        .setConferenceErrorType(
            ConferenceDataService.ConferenceErrorType.AUTHENTICATION)
        .setAuthenticationUrl(authenticationUrl);
    dataBuilder.setError(error);

  } else {
    // Other error type;
    var error = ConferenceDataService.newConferenceError()
        .setConferenceErrorType(
            ConferenceDataService.ConferenceErrorType.TEMPORARY);
    dataBuilder.setError(error);
  }

  // Don't forget to build the ConferenceData object.
  return dataBuilder.build();
}


/**
 *  Contact the third-party conferencing system to create a conference there,
 *  using the provided calendar event information. Collects and retuns the
 *  conference data returned by the third-party system in a custom JSON object
 *  with the following fields:
 *
 *    data.adminEmail - the conference administrator's email
 *    data.conferenceLegalNotice - the conference legal notice text
 *    data.error - Only present if there was an error during
 *         conference creation. Equal to 'AUTH' if the add-on user needs to
 *         authorize on the third-party system.
 *    data.id - the conference ID
 *    data.phoneNumber - the conference phone entry point phone number
 *    data.phonePin - the conference phone entry point PIN
 *    data.videoPasscode - the conference video entry point passcode
 *    data.videoUri - the conference video entry point URI
 *
 *  The above fields are specific to this example; which conference information
 *  your add-on needs is dependent on the third-party conferencing system
 *  requirements.
 *
 * @param {Object} calendarEvent A Calendar Event resource object returned by
 *     the Google Calendar API.
 * @return {Object}
 */
function create3rdPartyConference(calendarEvent) {
  var data = {};

  // Implementation details dependent on the third-party system API.
  // Typically one or more API calls are made to create the conference and
  // acquire its relevant data, which is then put in to the returned JSON
  // object.

  return data;
}

/**
 *  Return the URL used to authenticate the user with the third-party
 *  conferencing system.
 *
 *  @return {String}
 */
function getAuthenticationUrl() {
  var url;
  // Implementation details dependent on the third-party system.

  return url;
}