Üçüncü taraf konferanslar oluşturma

Komut dosyası projenizde tanımladığınız her konferans çözümü manifest ile ilişkili bir onCreateFunction içerir. Eklenti, bir kullanıcı ilgili konferans çözümünü bir etkinlik seçmeye çalıştığında konferans oluşturmak için bu işlevi çağırır.

Eklenti manifestinizde açıklanan her bir onCreateFunction öğesini uygulamanız gerekir. Genel olarak, bu işlevler aşağıdakileri yapmalıdır:

1. Üçüncü taraf konferans sisteminin konferansı oluşturmak için ihtiyaç duyabileceği, etkinlik kimliği veya katılımcı listesi gibi Google Takvim etkinlik bilgilerini alın.
2. Üçüncü taraf konferans hizmetine bağlanın ve Google Takvim etkinlik bilgilerini kullanarak burada yeni bir konferans oluşturun.
3. Konferans oluşturma isteği herhangi bir nedenle başarısız olduysa ConferenceError içeren bir ConferenceData nesnesi oluşturmak ve döndürmek için hata bilgilerini kullanın. Aksi halde sonraki adımları tamamlayın.
   1. Konferans senkronizasyonunu başlatın.
   2. Yeni bir ConferenceData nesnesi oluşturmak ve döndürmek için üçüncü taraf konferans hizmetinin döndürdüğü bilgileri kullanın.

Etkinlik bilgilerini alma

Üçüncü taraf konferansı oluşturmak için, ilgili Google Takvim etkinliğiyle ilgili bazı bilgiler gereklidir. Gereken kesin etkinlik bilgileri, farklı üçüncü taraf konferans sistemlerinden değişiklik gösterir, ancak genellikle bu bilgiler arasında etkinlik başlangıç saati, bitiş zamanı, özet, katılımcı listesi ve kimlik bilgileri 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 iletir. Google Takvim gelişmiş hizmetini kullanarak tüm etkinlik bilgilerini almak için bu kimlikleri kullanabilirsiniz.

Google Takvim, konferans ayrıntılarını henüz etkinlik oluşmadan bu etkinliğe ekleyebilir. Bu tür durumlarda, Google Takvim geçerli bir onCreateFunction eventId öğesini iletir ancak Calendar.Events.get() öğesine yapılan sonraki çağrılar, etkinliğin mevcut olmadığını belirten bir hata yanıtıyla sonuçlanabilir. Bu durumlarda, üçüncü taraf konferansı yer tutucu verileri kullanarak oluşturmak en iyi seçenektir. Bu veriler, etkinliğin 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 genellikle üçüncü taraf konferans sistemi tarafından desteklenen API istekleri oluşturularak gerçekleştirilir. Konferans oluşturmak amacıyla hangi API isteklerini kullanabileceğinizi belirlemek için üçüncü taraf konferans çözümünüzün dokümanlarına göz atın.

Apps Komut Dosyası'nda harici API isteklerini ele almanın en kolay yolu, Apps Komut Dosyası için OAuth2 veya Apps Komut Dosyası için OAuth1 açık kaynak kitaplıklarını kullanmaktır. UrlFetch hizmetini kullanarak harici API'lere de bağlanabilirsiniz ancak bu işlem için yetkilendirme ayrıntılarını açık bir şekilde 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şlat

Eklenti, üçüncü taraf bir sistemde başarıyla konferans oluşturduktan sonra, Google Takvim etkinliğindeki değişikliklerin konferansa yansıtılması için senkronizasyonu etkinleştirmek üzere birkaç adım gerçekleştirilmesi gerekir.

Konferans oluşturulduktan sonra senkronizasyonu ayarlamayla ilgili ayrıntılar için Takvim değişikliklerini senkronize etme sayfasına göz atın.

Konferans veri yanıtı oluşturma

Üçüncü taraf hizmetin döndürdüğü konferans bilgilerini kullanarak onCreateFunction, daha sonra bir ConferenceData nesnesi oluşturup döndürmelidir. Konferans verileri bölümünde bu nesnenin içeriği açıklanır. Google Takvim bu bilgileri kullanarak, konferans başladıktan sonra kullanıcıları konferansa yönlendirir.

ConferenceData nesnesi oluştururken alan uzunlukları, giriş noktası URI'lerinin biçimleri ve izin verilen giriş noktası kombinasyonları üzerinde 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. Bununla birlikte, burada açıklanan API etkinliği alanlarının tümü Apps Komut Dosyası'nda mevcut değildir.

Hataları işleme

Bazı durumlarda, üçüncü taraf konferans sisteminin döndürdüğü bir hata nedeniyle konferans oluşturma işlemi tamamlanamaz. Bu durumlarda eklentiniz, ConferenceError ayrıntılarını içeren bir ConferenceData nesnesi oluşturup geri göndererek hata koşulunu etkili bir şekilde ele almalıdır. Böylece Google Takvim uygun şekilde işlem yapabilir.

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

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

Örnek

Aşağıda bir onCreateFunction örneği gösterilmektedir (işlev adının herhangi bir şey olabileceğini unutmayın. Bunu yalnızca eklenti proje manifestinizde tanımlamanız gerekir).

create3rdPartyConference() işlevi, üçüncü taraf sistemle iletişim kurarak konferansı burada oluşturur, getAuthenticationUrl() işlevi ise üçüncü taraf sistem kimlik doğrulama URL'si oluşturur. Bunlar büyük ölçüde üçüncü taraf sistem ayrıntılarına bağlı olduğundan burada tam olarak uygulanmaz.

initializeSyncing() işlevi burada gösterilmemektedir; senkronizasyon için gereken ön çalışmaları gerçekleştirir. Ayrıntılar için Takvim değişikliklerini senkronize etme sayfasına göz atın.

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