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

Tworzenie rozmów wideo innych firm

Z każdym rozwiązaniem do obsługi konferencji zdefiniowane w projekcie skryptu manifest jest powiązane zdarzenie onCreateFunction. Dodatek wywołuje tę funkcję, aby utworzyć konferencję za każdym razem, gdy użytkownik próbuje wybrać to rozwiązanie do obsługi konferencji jako zdarzenie.

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

Pobierz wszystkie informacje o wydarzeniach z Kalendarza Google, takie jak identyfikator wydarzenia i lista uczestników, które mogą być potrzebne do utworzenia rozmowy wideo przez system innej firmy.
Połącz się z usługą rozmów wideo innej firmy i utwórz w niej nową rozmowę, korzystając z informacji o wydarzeniu z Kalendarza Google.
Jeśli z jakiegoś powodu żądanie utworzenia rozmowy wideo się nie uda, użyj informacji o błędzie, aby utworzyć i zwrócić obiekt ConferenceData zawierający ConferenceError. W przeciwnym razie wykonaj kolejne czynności.
1. Zainicjuj synchronizację konferencji.
2. Użyj informacji zwróconych przez zewnętrzną usługę do rozmów wideo, aby utworzyć i zwrócić nowy obiekt ConferenceData.

Pobieram informacje o wydarzeniu

Aby utworzyć konferencję w firmie zewnętrznej, musisz podać określone informacje o odpowiednim wydarzeniu w Kalendarzu Google. Dokładne wymagane informacje o wydarzeniu są różne w przypadku różnych systemów do obsługi rozmów wideo innych firm, ale często obejmują one godzinę rozpoczęcia, godzinę zakończenia, podsumowanie, listę uczestników i identyfikator.

Po wywołaniu każdy zdefiniowany przez Ciebie element onCreateFunction otrzymuje argument zawierający identyfikatory kalendarza i wydarzeń. Możesz użyć tych identyfikatorów do pobrania pełnych informacji o wydarzeniu przy użyciu usługi zaawansowanej Kalendarza Google.

Szczegóły rozmowy wideo w Kalendarzu Google mogą być dodawane do wydarzenia jeszcze przed jego rozpoczęciem. W takich przypadkach Kalendarz Google przekazuje onCreateFunction prawidłową wartość eventId, ale kolejne wywołania Calendar.Events.get() mogą wyświetlić komunikat o błędzie z informacją, że wydarzenie nie istnieje. W takich przypadkach najlepiej utworzyć konferencję zewnętrzną przy użyciu danych zastępczych. Dane te zostaną zastąpione przy następnej synchronizacji wydarzenia.

Tworzenie rozmowy wideo innej firmy

Po pobraniu niezbędnych danych wydarzenia onCreateFunction musi połączyć się z systemem do obsługi rozmów wideo innej firmy, aby utworzyć konferencję. Zwykle odbywa się to przez obsługę żądań do interfejsu API przez system do obsługi rozmów wideo innej firmy. Sprawdź 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 rozmów wideo.

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

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

Zainicjuj synchronizację rozmów wideo

Gdy dodatek utworzy konferencję w systemie innej firmy, należy wykonać kilka czynności, aby włączyć synchronizację, tak aby zmiany w wydarzeniu w Kalendarzu Google były odzwierciedlane w tej rozmowie.

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

Tworzenie odpowiedzi dotyczącej danych rozmowy wideo

Korzystając z informacji o rozmowie wideo zwróconych przez usługę innej firmy, onCreateFunction musi utworzyć i zwrócić obiekt ConferenceData. Zawartość tego obiektu jest opisana w sekcji Dane konferencji. Kalendarz Google wykorzystuje te informacje, 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 oraz dozwolonych kombinacji punktów wejścia. Na przykład w pojedynczym ConferenceData może być maksymalnie 1 punkt wejścia VIDEO. Te ograniczenia są takie same jak ograniczenia opisane w artykule Calendar API Event (Zdarzenie interfejsu Calendar API) dla odpowiedniego pola conferenceData, ale nie wszystkie opisane tam pola wydarzeń interfejsu API są dostępne w Apps Script.

Obsługa błędów

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

Gdy tworzysz obiekt ConferenceData w celu zgłoszenia błędu, nie musisz uwzględniać żadnych komponentów ConferenceData poza obiektem ConferenceError. ConferenceErrors może wyświetlać ConferenceErrorType, komunikat o błędzie, a w przypadku problemów z uwierzytelnianiem – adres URL, który umożliwia użytkownikom logowanie się w systemie do obsługi rozmów wideo innej firmy.

Przykład

Poniżej znajduje się przykład wartości onCreateFunction (zwróć uwagę, że nazwa funkcji może być dowolna – wystarczy ją zdefiniować w manifeście w projekcie dodatku).

Funkcja create3rdPartyConference() kontaktuje się z systemem firmy zewnętrznej, aby utworzyć w nim rozmowę wideo, a funkcja getAuthenticationUrl() tworzy adres URL uwierzytelniania systemu firmy zewnętrznej. Nie można tego zrobić w pełni, ponieważ w dużym stopniu zależą od szczegółów systemu firmy zewnętrznej.

Funkcja initializeSyncing() nie jest tu pokazana. Obsługuje ona wszelkie 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;
}