Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie rozmów wideo innych firm

Każde rozwiązanie konferencyjne zdefiniowane w projekcie skryptu w pliku manifestu ma powiązany onCreateFunction. Gdy użytkownik spróbuje wybrać to rozwiązanie do rozmów wideo podczas tworzenia wydarzenia, dodatek wywołuje tę funkcję, aby utworzyć rozmowę wideo.

Musisz zaimplementować wszystkie onCreateFunction opisane w pliku manifestu dodatku. Ogólnie funkcje te muszą spełniać te wymagania:

Pobierać informacje o wydarzeniach w Kalendarzu Google, takie jak identyfikator wydarzenia czy lista uczestników, których system konferencyjny innej firmy może potrzebować do utworzenia konferencji.
Połącz się z usługą konferencyjną innej firmy i utwórz w niej nową konferencję, korzystając z informacji o wydarzeniu w Kalendarzu Google.
Jeśli żądanie utworzenia konferencji nie powiodło się z jakiegoś powodu, użyj informacji o błędzie, aby utworzyć i zwrócić obiekt ConferenceData zawierający obiekt ConferenceError. W przeciwnym razie wykonaj te czynności.
1. Inicjowanie synchronizacji konferencji.
2. Użyj informacji zwróconych przez zewnętrzną usługę konferencyjną, aby utworzyć i zwrócić nowy obiekt ConferenceData.

Pobieranie informacji o zdarzeniu

Aby utworzyć konferencję osoby trzeciej, potrzebne są pewne informacje o odpowiednim wydarzeniu w Kalendarzu Google. Wymagane informacje o wydarzeniu różnią się w zależności od zewnętrznych systemów konferencyjnych, ale często obejmują one czas rozpoczęcia i zakończenia wydarzenia, podsumowanie, listę uczestników oraz identyfikator.

Po wywołaniu każdej zdefiniowanej przez Ciebie funkcji onCreateFunction przekazywany jest jej argument zawierający identyfikatory kalendarza i zdarzenia. Za pomocą tych identyfikatorów możesz pobierać 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 powstanie. W takich przypadkach Kalendarz Google przekazuje onCreateFunction prawidłowy eventId, ale kolejne wywołania Calendar.Events.get() mogą spowodować błąd informujący, że wydarzenie nie istnieje. W takich przypadkach najlepiej utworzyć konferencję zewnętrzną, używając danych zastępczych. Te dane zostaną zastąpione podczas następnej synchronizacji zdarzenia.

Tworzenie konferencji zewnętrznej

Gdy onCreateFunction pobierze niezbędne dane o wydarzeniu, 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. Aby dowiedzieć się, których żądań interfejsu API możesz używać do tworzenia konferencji, zapoznaj się z dokumentacją rozwiązania do konferencji innej firmy.

W Apps Script najprostszym sposobem na wysyłanie żądań do zewnętrznych interfejsów 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 podania szczegółów autoryzacji.

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

Inicjowanie synchronizacji konferencji

Gdy dodatek utworzy konferencję w systemie zewnętrznym, musisz wykonać kilka czynności, aby włączyć synchronizację, dzięki której zmiany w wydarzeniu w Kalendarzu Google będą odzwierciedlane na konferencji.

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

Tworzenie odpowiedzi na pytania dotyczące danych konferencyjnych

Korzystając z informacji o konferencji zwróconych przez usługę innej firmy, usługa onCreateFunction musi utworzyć i zwrócić obiekt ConferenceData. Sekcja Dane konferencji opisuje zawartość tego obiektu. Kalendarz Google używa tych informacji, aby kierować użytkowników na konferencję, gdy się rozpocznie.

Podczas tworzenia obiektu ConferenceData należy pamiętać, że istnieją pewne ograniczenia dotyczące 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 ConferenceData może być maksymalnie jeden punkt wejścia VIDEO. Te ograniczenia są identyczne z ograniczeniami opisanymi w zdarzeniach interfejsu Calendar API w przypadku odpowiedniego pola conferenceData, ale nie wszystkie pola zdarzeń interfejsu API opisane w tym miejscu są dostępne w usłudze Apps Script.

Obsługa błędów

W niektórych przypadkach tworzenie konferencji nie może zostać ukończone z powodu błędu zwróconego przez zewnętrzny system konferencyjny. W takich przypadkach dodatek powinien odpowiednio obsłużyć błąd, tworząc i zwracając obiekt ConferenceData zawierający szczegóły ConferenceError, aby Kalendarz Google mógł odpowiednio zareagować.

Podczas tworzenia obiektu ConferenceData, aby zgłosić błąd, nie musisz uwzględniać ż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, który pozwala użytkownikom zalogować się do systemu konferencyjnego innej firmy.

Przykład

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

Funkcja create3rdPartyConference() kontaktuje system innej firmy, aby utworzyć tam konferencję, a funkcja getAuthenticationUrl() tworzy adres URL uwierzytelniania systemu innej firmy. Nie są one wdrożone w pełni, ponieważ są silnie zależne od szczegółów systemu zewnętrznego.

Funkcja initializeSyncing() nie jest tutaj wyświetlana; odpowiada ona za wszelkie wstępne czynności wymagane do 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;
}