Tworzenie konferencji innych firm

Każde rozwiązanie konferencyjne zdefiniowane w pliku manifestu projektu skryptu ma powiązany element onCreateFunction. Dodatek Google Workspace wywołuje tę funkcję, aby utworzyć rozmowę wideo za każdym razem, gdy użytkownik próbuje wybrać to rozwiązanie do rozmów wideo w przypadku wydarzenia.

Zaimplementuj każdy element onCreateFunction opisany w pliku manifestu dodatku. Te funkcje muszą wykonywać te czynności:

  1. pobierać informacje o wydarzeniach w Kalendarzu Google, takie jak identyfikator wydarzenia lub lista uczestników, które są potrzebne systemowi konferencyjnemu innej firmy do utworzenia konferencji;
  2. Połącz się z zewnętrzną usługą konferencyjną i utwórz w niej nową konferencję, korzystając z informacji o wydarzeniu w Kalendarzu.
  3. Jeśli żądanie utworzenia konferencji się nie powiedzie, użyj informacji o błędzie, aby utworzyć i zwrócić obiekt ConferenceData zawierający ConferenceError. W przeciwnym razie wykonaj kolejne czynności.
  4. Zainicjuj synchronizację konferencji.
  5. Użyj informacji zwróconych przez usługę konferencyjną innej firmy, aby utworzyć i zwrócić nowy obiekt ConferenceData.

Pobieranie informacji o wydarzeniu

Aby utworzyć konferencję zewnętrzną, potrzebne są informacje o odpowiednim wydarzeniu w Kalendarzu. Dokładne informacje o wydarzeniu, które są wymagane, różnią się w zależności od systemu konferencyjnego innej firmy, ale często obejmują czas rozpoczęcia i zakończenia wydarzenia, podsumowanie, listę uczestników i identyfikator.

Po wywołaniu każdej zdefiniowanej funkcji onCreateFunction przekazywany jest argument zawierający identyfikatory kalendarza i wydarzenia. Użyj tych identyfikatorów, aby pobrać pełne informacje o wydarzeniu za pomocą zaawansowanej usługi Kalendarza.

Kalendarz może dodać szczegóły rozmowy wideo do wydarzenia, zanim ono powstanie. W takich przypadkach Kalendarz przekazuje prawidłowy onCreateFunction, ale kolejne wywołania Calendar.Events.get mogą spowodować błąd informujący, że wydarzenie nie istnieje.eventId W takich przypadkach utwórz konferencję zewnętrzną, używając danych zastępczych. Te dane zostaną zastąpione podczas następnej synchronizacji wydarzenia.

Tworzenie konferencji innej firmy

Gdy onCreateFunction pobierze niezbędne dane zdarzenia, musi połączyć się z systemem konferencyjnym innej firmy, aby utworzyć konferencję. Zwykle odbywa się to przez wysyłanie żądań do interfejsu API obsługiwanego przez system konferencyjny innej firmy. Zapoznaj się z dokumentacją rozwiązania do obsługi rozmów wideo innej firmy, aby dowiedzieć się, jakich żądań do interfejsu API możesz używać do tworzenia konferencji.

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

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

Inicjowanie synchronizacji konferencji

Gdy dodatek utworzy rozmowę wideo w systemie innej firmy, należy wykonać kilka czynności, aby włączyć synchronizację. Dzięki temu zmiany w wydarzeniu w Kalendarzu będą odzwierciedlane w rozmowie wideo.

Szczegółowe informacje o konfigurowaniu synchronizacji po utworzeniu konferencji znajdziesz w artykule Synchronizowanie zmian w Kalendarzu.

Tworzenie odpowiedzi z danymi konferencji

Korzystając z informacji o konferencji zwróconych przez usługę innej firmy, onCreateFunctionmusi następnie utworzyć i zwrócić obiekt ConferenceData. Sekcja Dane konferencji opisuje zawartość tego obiektu. Kalendarz używa tych informacji, aby kierować użytkowników na konferencję po jej rozpoczęciu.

Podczas tworzenia obiektu ConferenceData pamiętaj o długościach pól, formatach identyfikatorów URI punktów wejścia i dozwolonych kombinacjach punktów wejścia. Na przykład w jednym ConferenceData może być maksymalnie 1 punkt wejścia VIDEO. Te ograniczenia są identyczne z ograniczeniami opisanymi w wydarzeniu interfejsu Calendar API w przypadku odpowiedniego pola conferenceData, chociaż nie wszystkie pola wydarzeń interfejsu API opisane w tym dokumencie są dostępne w Apps Script.

Obsługuj błędy

Podczas tworzenia konferencji mogą wystąpić błędy. W niektórych przypadkach nie można utworzyć konferencji z powodu błędu zwróconego przez system konferencyjny innej firmy. W takich przypadkach dodatek powinien obsłużyć błąd, tworząc i zwracając obiekt ConferenceData zawierający szczegółowe informacje ConferenceError, aby Kalendarz mógł odpowiednio zareagować.

Podczas tworzenia obiektu ConferenceData na potrzeby zgłoszenia błędu nie musisz uwzględniać ż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, który umożliwia użytkownikom zalogowanie się w systemie do rozmów wideo innej firmy.

Jeśli próba utworzenia rozmowy wideo nie powiodła się, dodatek nie musi próbować skonfigurować synchronizacji rozmowy.

Przykład

Poniższy przykład pokazuje implementację onCreateFunction. 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ć konferencję, a funkcja getAuthenticationUrl tworzy adres URL uwierzytelniania systemu innej firmy. Nie są one w pełni wdrożone.

Funkcja initializeSyncing nie jest tu widoczna. Odpowiada ona za wstępne czynności wymagane do 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;
}