Tworzenie konferencji innych firm

Kliknij, aby połączyć.

Z każdym rozwiązaniem do wideokonferencji określonym w pliku manifestu projektu skryptu jest powiązany element onCreateFunction. Dodatek wywołuje tę funkcję, aby utworzyć konferencję za każdym razem, gdy użytkownik spróbuje wybrać rozwiązanie konferencyjne.

Musisz wdrożyć każdy element onCreateFunction opisany w pliku manifestu dodatku. Ogólnie funkcje te muszą:

  1. Pobierz wszystkie informacje o wydarzeniach z Kalendarza Google, takie jak identyfikator wydarzenia lub listę uczestników, których system do obsługi rozmów wideo może potrzebować do utworzenia rozmowy wideo.
  2. Połącz się z usługą rozmów wideo innej firmy i utwórz nową rozmowę, korzystając z informacji o wydarzeniach w Kalendarzu Google.
  3. Jeśli z jakiegoś powodu żądanie utworzenia rozmowy wideo się nie udało, użyj informacji o błędzie, aby utworzyć i zwrócić obiekt ConferenceData zawierający obiekt ConferenceError. W przeciwnym razie wykonaj kolejne czynności.
    1. Zainicjuj synchronizację rozmowy wideo.
    2. Użyj informacji zwracanych przez zewnętrzną usługę konferencyjną, aby utworzyć i zwrócić nowy obiekt ConferenceData.

Pobieranie informacji o wydarzeniu

Aby utworzyć konferencję zewnętrzną, musisz podać informacje o odpowiednim wydarzeniu z Kalendarza Google. Wymagane informacje o zdarzeniu różnią się w zależności od systemów do obsługi rozmów wideo firm zewnętrznych, ale często są to czas rozpoczęcia, czas zakończenia, podsumowanie, lista uczestników i identyfikator.

Po wywołaniu każdy zdefiniowany element onCreateFunction jest przekazywany jako argument zawierający identyfikator kalendarza i wydarzenia. Możesz użyć tych identyfikatorów, aby pobrać pełne informacje o wydarzeniu za pomocą usługi zaawansowanej Kalendarza Google.

Kalendarz Google może dodać szczegóły rozmowy wideo do wydarzenia, zanim ono istnieje. W takich przypadkach Kalendarz Google przekazuje onCreateFunction prawidłowe wyrażenie eventId, ale kolejne wywołania Calendar.Events.get() mogą spowodować wyświetlenie komunikatu o błędzie z informacją, że wydarzenie nie istnieje. W takiej sytuacji najlepiej utworzyć konferencję zewnętrzną, używając danych zastępczych. Są one zastępowane podczas następnej synchronizacji wydarzenia.

Tworzenie konferencji innej firmy

Gdy onCreateFunction pobierze niezbędne dane zdarzenia, musi utworzyć połączenie z zewnętrznym systemem konferencyjnym, aby utworzyć konferencję. Zwykle odbywa się to przez przesłanie żądań do interfejsu API obsługiwanych przez system rozmów wideo innej firmy. Zapoznaj się z dokumentacją rozwiązania do obsługi rozmów wideo innej firmy, aby określić, których żądań do interfejsu API możesz używać do tworzenia rozmów wideo.

W Apps Script najłatwiejszym sposobem wykonywania zewnętrznych żądań do interfejsu API jest użycie bibliotek open source OAuth2 dla Apps Script lub OAuth1 dla Apps Script. Możesz też połączyć się z zewnętrznymi interfejsami API za pomocą usługi UrlFetch, jednak wymaga to jawnego obsługi szczegółów autoryzacji.

Po przesłaniu prośby o utworzenie rozmowy może być konieczne wysłanie dodatkowych próśb o pobranie szczegółów nowej rozmowy.

Inicjowanie synchronizacji rozmowy wideo

Gdy dodatek utworzy konferencję w systemie innej firmy, wykonaj kilka czynności, aby włączyć synchronizację, aby zmiany w wydarzeniu Kalendarza Google zostały odzwierciedlone w konferencji.

Więcej informacji o konfigurowaniu synchronizacji po utworzeniu rozmowy znajdziesz w artykule Synchronizowanie zmian w Kalendarzu.

Tworzenie odpowiedzi na dane konferencyjne

Używając informacji o rozmowie wideo zwróconych przez usługę zewnętrzną, onCreateFunction musi następnie utworzyć i zwrócić obiekt ConferenceData; sekcja Dane rozmowy wideo opisuje zawartość tego obiektu. Kalendarz Google używa tych informacji, aby kierować użytkowników do konferencji po jej rozpoczęciu.

Podczas tworzenia obiektu ConferenceData pamiętaj o pewnych ograniczeniach dotyczących długości pól, formatów identyfikatorów URI punktów wejścia i dozwolonych kombinacji punktów wejścia. Na przykład w jednym miejscu może występować maksymalnie ConferenceData punkt wejścia VIDEO. Ograniczenia są takie same jak ograniczenia opisane w zdarzeniu Calendar API w odpowiednim polu conferenceData, chociaż nie wszystkie opisane w nich pola zdarzeń interfejsu API są dostępne w Apps Script.

Obsługa błędów

W niektórych przypadkach nie można ukończyć tworzenia rozmowy wideo z powodu błędu zwróconego przez system innej firmy. W takim przypadku dodatek powinien skutecznie obsługiwać warunek błędu przez zbudowanie i zwrócenie obiektu ConferenceData zawierającego szczegóły ConferenceError, aby Kalendarz Google mógł odpowiednio działać.

Gdy tworzysz obiekt ConferenceData do raportowania błędów, nie musisz dodawać żadnych komponentów ConferenceData oprócz obiektu ConferenceError. ConferenceErrors może zawierać ConferenceErrorType, komunikat o błędzie, a w przypadku problemów z uwierzytelnianiem – adres URL umożliwiający użytkownikom logowanie się w systemie do rozmów wideo innej firmy.

Przykład

Poniżej znajdziesz przykład tagu onCreateFunction (pamiętaj, że nazwa funkcji może być dowolna; musisz ją tylko zdefiniować w pliku manifestu projektu dodatku).

Funkcja create3rdPartyConference() kontaktuje się z systemem innej firmy, aby utworzyć w niej konferencję, a funkcja getAuthenticationUrl() tworzy adres URL uwierzytelniania systemu innej firmy. Nie są one w pełni zaimplementowane tutaj, ponieważ w znacznym stopniu zależą od szczegółów systemowych firm zewnętrznych.

Funkcja initializeSyncing() nie jest tu widoczna, ponieważ przeprowadza ona wstępną pracę wymagającą synchronizacji. Więcej informacji znajdziesz w artykule Synchronizacja zmian w kalendarzu.

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