Tworzenie konferencji innych firm

Z każdym rozwiązaniem do obsługi konferencji zdefiniowanym w pliku manifestu projektu skryptu jest powiązany szablon onCreateFunction. Dodatek wywołuje tę funkcję, aby utworzyć konferencję, gdy użytkownik próbuje wybrać to rozwiązanie do obsługi rozmów wideo jako wydarzenie.

Musisz zaimplementować wszystkie onCreateFunction opisane w pliku manifestu dodatku. Ogólnie rzecz biorąc, te funkcje muszą wykonywać te czynności:

  1. Pobranie wszystkich informacji o wydarzeniu z Kalendarza Google, takich jak identyfikator wydarzenia lub lista uczestników, których system innej firmy może potrzebować do utworzenia rozmowy wideo.
  2. Połącz się z usługą do prowadzenia rozmów wideo innej firmy i utwórz w niej nową konferencję, korzystając z informacji o wydarzeniu z Kalendarza Google.
  3. Jeśli z jakiegoś powodu żądanie utworzenia rozmowy wideo nie powiodło się, użyj informacji o błędzie, aby skompilować i zwrócić obiekt ConferenceData zawierający ConferenceError. W przeciwnym razie wykonaj kolejne kroki.
    1. Zainicjuj synchronizację rozmów wideo.
    2. Użyj informacji zwróconych przez usługę do prowadzenia rozmów wideo innej firmy, aby utworzyć i zwrócić nowy obiekt ConferenceData.

Pobieranie informacji o zdarzeniu

Aby utworzyć konferencję z firmą zewnętrzną, musisz mieć pewne informacje o odpowiednim wydarzeniu w Kalendarzu Google. Dokładne wymagane informacje o wydarzeniu różnią się w zależności od systemu konferencyjnego innej firmy, ale często obejmuje to czas rozpoczęcia i zakończenia wydarzenia, podsumowanie, listę uczestników oraz identyfikator.

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

Kalendarz Google może dodać szczegóły rozmowy wideo do wydarzenia, zanim ono już istnieje. W takich przypadkach Kalendarz Google przekazuje onCreateFunction prawidłowy eventId, ale kolejne wywołania Calendar.Events.get() mogą spowodować wyświetlenie odpowiedzi błędu z informacją, że wydarzenie nie istnieje. W takich przypadkach najlepiej jest utworzyć konferencję zewnętrzną, używając danych zastępczych. Te dane zostaną zastąpione przy następnej synchronizacji wydarzenia.

Tworzenie rozmowy wideo z firmą zewnętrzną

Po pobraniu niezbędnych danych zdarzenia onCreateFunction musi połączyć się z systemem do obsługi rozmów wideo innej firmy, aby utworzyć konferencję. Zwykle jest to realizowane przez wysyłanie żądań do interfejsu API obsługiwanych przez system do obsługi rozmów wideo innej firmy. Aby dowiedzieć się, których żądań do interfejsu API możesz używać do tworzenia rozmów wideo, zapoznaj się z dokumentacją rozwiązania do obsługi rozmów wideo innej firmy.

W Apps Script najprostszym sposobem na tworzenie zewnętrznych żądań interfejsu API jest użycie protokołu OAuth2 dla Apps Script lub OAuth1 dla bibliotek open source. Możesz też połączyć się z zewnętrznymi interfejsami API za pomocą usługi UrlFetch, ale wymaga to wyraźnej obsługi szczegółów autoryzacji.

Po zażądaniu utworzenia rozmowy wideo może być konieczne przesłanie dodatkowych żądań w celu pobrania nowych szczegółów rozmowy.

Zainicjuj synchronizację rozmów wideo

Gdy dodatek utworzy konferencję w systemie innej firmy, należy wykonać kilka czynności w celu włączenia synchronizacji, aby zmiany w wydarzeniu z Kalendarza Google były odzwierciedlane w rozmowie.

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

Tworzenie odpowiedzi dotyczącej danych konferencji

Korzystając z informacji o rozmowie wideo zwróconych przez usługę zewnętrzną, onCreateFunction musi następnie skompilować i zwrócić obiekt ConferenceData. Zawartość tego obiektu opisuje sekcja Dane konferencji. Kalendarz Google używa tych informacji do kierowania użytkowników na konferencję po jej rozpoczęciu.

Podczas tworzenia obiektu ConferenceData pamiętaj, że obowiązują pewne ograniczenia dotyczące długości pól, formatów URI punktów wejścia i dozwolonych kombinacji punktów wejścia. Na przykład w pojedynczym elemencie ConferenceData może być maksymalnie 1 punkt wejścia VIDEO. Te ograniczenia są takie same jak ograniczenia opisane w sekcji Calendar API Event dla odpowiedniego pola conferenceData, jednak nie wszystkie opisane w nim 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 konferencji z powodu błędu zwracanego przez system do obsługi rozmów wideo innej firmy. W takich przypadkach dodatek powinien solidnie wyeliminować błąd, tworząc i zwracając obiekt ConferenceData ze szczegółami ConferenceError. Dzięki temu Kalendarz Google może wykonać odpowiednie działanie.

Podczas tworzenia obiektu ConferenceData do zgłaszania błędu nie musisz dodawać żadnych komponentów ConferenceData poza obiektem 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 obsługi rozmów wideo innej firmy.

Przykład

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

Funkcja create3rdPartyConference() kontaktuje się z systemem innej firmy, aby utworzyć w nim konferencję, a funkcja getAuthenticationUrl() tworzy adres URL uwierzytelniania systemu innej firmy. Nie są one w pełni zaimplementowane, ponieważ w dużym stopniu zależą od informacji o systemie innej firmy.

Funkcja initializeSyncing() nie jest tu widoczna, ponieważ wykonuje wszystkie czynności wstępne wymagane do przeprowadzenia synchronizacji. Więcej informacji znajdziesz w artykule Synchronizowanie 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;
}