Üçüncü taraf konferansları oluşturma

Not: Bu işlev, özellikle konferans sağlayıcılar için geliştirilmiştir ve başlangıçta Takvim konferans eklentileri olarak kullanıma sunulmuştur.

Komut dosyası projenizin manifest dosyasında tanımladığınız her konferans çözümü ile ilişkili bir onCreateFunction bulunur. Eklenti, kullanıcı bir etkinliğe söz konusu konferans çözümünü eklemeye çalıştığında konferans oluşturmak için bu işlevi çağırır.

Eklenti manifestinizde açıklanan her onCreateFunction'yı uygulamanız gerekir. Genel olarak bu işlevler şunları yapmalıdır:

1. Üçüncü taraf konferans sisteminin konferansı oluşturmak için ihtiyaç duyabileceği Google Takvim etkinlik bilgileri (ör. etkinlik kimliği veya katılımcı listesi) alınır.
2. Üçüncü taraf konferans hizmetine bağlanın ve Google Takvim etkinlik bilgilerini kullanarak orada yeni bir konferans oluşturun.
3. Konferans oluşturma isteği herhangi bir nedenle başarısız olursa hata bilgilerini kullanarak ConferenceError içeren bir ConferenceData nesnesi oluşturup döndürün. Aksi takdirde sonraki adımları tamamlayın.
   1. Konferans senkronizasyonunu başlatın.
   2. Üçüncü taraf konferans hizmeti tarafından döndürülen bilgileri kullanarak yeni bir ConferenceData nesnesi oluşturun ve döndürün.

Etkinlik bilgilerini alma

Üçüncü taraf konferans oluşturmak için ilgili Google Takvim etkinliğiyle ilgili belirli bilgiler gerekir. Gerekli olan etkinlik bilgileri, farklı üçüncü taraf konferans sistemlerine göre değişir. Ancak genellikle etkinlik başlangıç saati, bitiş saati, özeti, katılımcı listesi ve kimliği bu bilgiler arasındadır.

Tanımladığınız her onCreateFunction çağrıldığında, takvim ve etkinlik kimliklerini içeren bir bağımsız değişken iletilir. Bu kimlikleri kullanarak Google Takvim gelişmiş hizmetini kullanarak tam etkinlik bilgilerini alabilirsiniz.

Google Takvim, konferans ayrıntılarını bir etkinliğe etkinlik oluşturulmadan önce ekleyebilir. Bu gibi durumlarda Google Takvim, onCreateFunction geçerli bir eventId iletir ancak Calendar.Events.get() için sonraki çağrılar, etkinliğin mevcut olmadığını belirten bir hata yanıtına neden olabilir. Bu gibi durumlarda, yer tutucu veriler kullanarak üçüncü taraf konferansı oluşturmak en iyisidir. Bu veriler, etkinlik bir sonraki senkronizasyonunda değiştirilir.

Üçüncü taraf konferansı oluşturma

onCreateFunction gerekli etkinlik verilerini aldıktan sonra konferansı oluşturmak için üçüncü taraf konferans sistemine bağlanmalıdır. Bu işlem genellikle üçüncü taraf konferans sistemi tarafından desteklenen API istekleri gönderilerek gerçekleştirilir. Konferans oluşturmak için hangi API isteklerini kullanabileceğinizi belirlemek üzere üçüncü taraf konferans çözümünüzün dokümanlarını inceleyin.

Apps Script'te harici API istekleri oluşturmayı ele almanın en kolay yolu, Apps Script için OAuth2 veya Apps Script için OAuth1 açık kaynaklı kitaplıklarını kullanmaktır. Ayrıca UrlFetch hizmetini kullanarak harici API'lere de bağlanabilirsiniz ancak bu durumda yetkilendirme ayrıntılarını açıkça işlemeniz gerekir.

Konferans oluşturma isteğinde bulunduktan sonra, yeni konferans ayrıntılarını almak için ek isteklerde bulunmanız gerekebilir.

Konferans senkronizasyonunu başlatma

Eklenti, üçüncü taraf sisteminde konferansı başarıyla oluşturduktan sonra, Google Takvim etkinliğinde yapılan değişikliklerin konferansa yansıtılması için senkronizasyonun etkinleştirilmesi birkaç adımda tamamlanır.

Konferans oluşturulduktan sonra senkronizasyonu ayarlama hakkında ayrıntılı bilgi için Takvim değişikliklerini senkronize etme başlıklı makaleyi inceleyin.

Konferans verileri yanıtı oluşturma

Üçüncü taraf hizmeti tarafından döndürülen konferans bilgilerini kullanarak onCreateFunction, ConferenceData nesnesini oluşturup döndürmelidir. Konferans verileri bölümünde bu nesnenin içeriği açıklanmaktadır. Google Takvim, bu bilgileri kullanarak kullanıcıları konferans başladığında konferansa yönlendirir.

ConferenceData nesnesi oluştururken alan uzunlukları, giriş noktası URI'lerinin biçimleri ve izin verilen giriş noktası kombinasyonları konusunda bazı sınırlamalar olduğunu unutmayın. Örneğin, tek bir ConferenceData içinde en fazla bir VIDEO giriş noktası olabilir. Bu sınırlamalar, ilgili conferenceData alanı için Calendar API Etkinliği'nde açıklanan sınırlamalarla aynıdır. Ancak orada açıklanan API etkinlik alanlarının tümü Apps Komut Dosyası'nda kullanılamaz.

Hataları işleme

Bazı durumlarda, üçüncü taraf konferans sistemi tarafından döndürülen bir hata nedeniyle konferans oluşturma işlemi tamamlanamaz. Bu gibi durumlarda, Google Takvim'in buna göre hareket edebilmesi için eklentiniz, ConferenceData nesnesi oluşturup döndürerek hata durumunu sağlam bir şekilde işlemeli ve ConferenceError ayrıntılarını içermelidir.

Bir hatayı bildirmek için ConferenceData nesnesi oluştururken ConferenceError nesnesi dışında herhangi bir ConferenceData bileşeni eklemeniz gerekmez. ConferenceErrors öğesinde ConferenceErrorType, hata mesajı ve kimlik doğrulama sorunları olması durumunda kullanıcıların üçüncü taraf konferans sistemine giriş yapmasına olanak tanıyan bir URL olabilir.

Not: Konferans oluşturma girişimi başarısız olduysa eklentinizin konferans senkronizasyonunu ayarlamaya çalışması gerekmez.

Örnek

Aşağıda bir onCreateFunction örneği gösterilmektedir (işlevin adının herhangi bir şey olabileceğini, yalnızca eklenti projesi manifestinizde tanımlamanız gerektiğini unutmayın).

create3rdPartyConference() işlevi, konferansı oluşturmak için üçüncü taraf sistemiyle iletişime geçer ve getAuthenticationUrl() işlevi, üçüncü taraf sistem kimlik doğrulama URL'si oluşturur. Bunlar, üçüncü taraf sistem ayrıntılarına büyük ölçüde bağlı oldukları için burada tam olarak uygulanmaz.

initializeSyncing() işlevi burada gösterilmemiştir. Senkronizasyon için gereken tüm ön işlemleri yapar. Ayrıntılar için Takvim değişikliklerini senkronize etme başlıklı makaleyi inceleyin.

/**
 *  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;
}