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 manifestu ma powiązany onCreateFunction. Dodatek wywołuje tę funkcję, aby utworzyć rozmowę wideo, gdy użytkownik próbuje wybrać to rozwiązanie do rozmów wideo w wydarzeniu.

Musisz zaimplementować każdy element onCreateFunction opisany w manifeście dodatku. Ogólnie rzecz biorąc, funkcje te muszą wykonywać te czynności:

pobierać informacje o wydarzeniach w Kalendarzu Google, takie jak identyfikator wydarzenia lub lista uczestników, które mogą być potrzebne systemowi konferencyjnemu innej firmy do utworzenia konferencji;
Połącz się z zewnętrzną usługą konferencyjną i utwórz w niej nową konferencję na podstawie informacji o wydarzeniu w Kalendarzu Google.
Jeśli żądanie utworzenia rozmowy wideo nie powiodło się z jakiegoś powodu, 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 usługę konferencyjną innej firmy, aby utworzyć i zwrócić nowy obiekt ConferenceData.

Pobieranie informacji o wydarzeniu

Aby utworzyć konferencję zewnętrzną, potrzebne są określone informacje o odpowiednim wydarzeniu w Kalendarzu Google. Wymagane informacje o wydarzeniu różnią się w zależności od systemu konferencyjnego innej firmy, ale często obejmują godzinę 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. Za pomocą tych identyfikatorów możesz pobrać pełne informacje o wydarzeniu, korzystając z usługi zaawansowanej Kalendarza Google.

Kalendarz Google może dodać szczegóły rozmowy wideo do wydarzenia, zanim ono powstanie. W takich przypadkach Kalendarz Google przekazuje onCreateFunction a valid eventId, ale kolejne wywołania Calendar.Events.get() mogą skutkować odpowiedzią o błędzie, która informuje, że wydarzenie nie istnieje. W takich przypadkach najlepiej utworzyć konferencję zewnętrzną, używając danych zastępczych. Te dane zostaną zastąpione przy następnej synchronizacji zdarzenia.

Tworzenie konferencji innej firmy

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. Zapoznaj się z dokumentacją rozwiązania do obsługi konferencji innej firmy, aby dowiedzieć się, jakich żądań interfejsu API możesz używać do tworzenia konferencji.

W 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 podania 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

Po utworzeniu konferencji w systemie zewnętrznym dodatek powinien wykonać kilka czynności, aby włączyć synchronizację, dzięki czemu zmiany w wydarzeniu w Kalendarzu Google będą odzwierciedlane w konferencji.

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, 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ę po jej rozpoczęciu.

Podczas tworzenia obiektu ConferenceData pamiętaj, ż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 VIDEO może być maksymalnie 1 punkt wejścia ConferenceData. Te ograniczenia są identyczne z ograniczeniami opisanymi w conferenceDatapolu interfejsu Calendar API EventconferenceData, chociaż nie wszystkie pola zdarzeń interfejsu API opisane w tym dokumencie są dostępne w Apps Script.

Obsługa błędów

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 solidnie obsługiwać stan błędu, tworząc i zwracając obiekt ConferenceData zawierający szczegóły ConferenceError, aby Kalendarz Google 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 konferencyjnym innej firmy.

Przykład

Poniżej znajdziesz przykład funkcji 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 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 szczegółów systemu innej firmy.

Funkcja initializeSyncing() nie jest tu widoczna. Wykonuje 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;
}