Üçüncü taraf konferanslar oluşturma

Komut dosyası projenizin manifest dosyasında tanımlanan her konferans çözümü ile ilişkili bir onCreateFunction vardır. Google Workspace eklentisi, bir kullanıcı bir etkinlik için bu konferans çözümünü seçmeye çalıştığında konferans oluşturmak üzere bu işlevi çağırır.

Eklenti manifestinizde açıklanan her onCreateFunction öğesini uygulayın. Bu işlevler aşağıdakileri yapmalıdır:

Üçüncü taraf konferans sisteminin konferansı oluşturmak için ihtiyaç duyduğu Google Takvim etkinlik bilgilerini (ör. etkinlik kimliği veya katılımcı listesi) alabilir.
Üçüncü taraf konferans hizmetine bağlanın ve Takvim etkinliği bilgilerini kullanarak orada yeni bir konferans oluşturun.
Konferans oluşturma isteği 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.
Konferans senkronizasyonunu başlatın.
Üçü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 Takvim etkinliği hakkında bilgi gerekir. Gerekli olan etkinlik bilgileri, farklı üçüncü taraf konferans sistemlerine göre değişir ancak genellikle etkinliğin başlangıç saati, bitiş saati, özeti, katılımcı listesi ve kimliği yer alı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. Takvim gelişmiş hizmetini kullanarak etkinlik bilgilerinin tamamını almak için bu kimlikleri kullanın.

Takvim, konferans ayrıntılarını bir etkinlik gerçekleşmeden önce ekleyebilir. Bu gibi durumlarda Takvim, onCreateFunction geçerli bir eventId iletir ancak Calendar.Events.get için sonraki çağrılar, etkinliğin mevcut olmadığını belirten bir hataya neden olabilir. Bu gibi durumlarda, yer tutucu verileri kullanarak üçüncü taraf konferansı oluşturun. 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 görüşmesi 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.

Google Apps Komut Dosyası'nda harici API istekleri oluşturmayı ele almanın en kolay yolu, Apps Komut Dosyası için OAuth2 veya Apps Komut Dosyası 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 başarıyla konferans oluşturduktan sonra, 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 kullanan onCreateFunction, daha sonra bir ConferenceData nesnesi oluşturup döndürmelidir. Bu nesnenin içeriği, Konferans verileri bölümünde açıklanmaktadır. Takvim, bu bilgileri kullanarak kullanıcıları konferans başladığında konferansa yönlendirir.

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

Hataları işleme

Konferans oluşturma işlemi sırasında hatalar oluşabilir. Bazı durumlarda, üçüncü taraf konferans sistemi tarafından döndürülen bir hata nedeniyle konferans oluşturma işlemi tamamlanamaz. Bu durumlarda, Takvim'in buna göre hareket edebilmesi için eklentiniz, ConferenceData nesnesi oluşturup döndürerek hata durumunu ConferenceError ayrıntılarıyla birlikte işlemelidir.

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

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

Örnek

Aşağıdaki örnekte bir onCreateFunction uygulaması gösterilmektedir. İşlevin adı herhangi bir şey olabilir. Yalnızca eklenti projesi manifestinizde tanımlamanız gerekir.

create3rdPartyConference fonksiyonu, konferansı oluşturmak için üçüncü taraf sistemiyle iletişime geçer ve getAuthenticationUrl fonksiyonu, üçüncü taraf sistem kimlik doğrulama URL'si oluşturur. Bunlar burada tam olarak uygulanmaz.

initializeSyncing işlevi burada gösterilmez. Senkronizasyon için gereken ön çalışmayı 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;
}