서드 파티 회의 만들기

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

스크립트 프로젝트 매니페스트에 정의된 각 회의 솔루션에는 연결된 onCreateFunction가 있습니다. 부가기능은 사용자가 이 회의 솔루션을 선택하려고 할 때마다 회의를 만들기 위해 이 함수를 호출합니다.

부가기능 매니페스트에 설명된 각 onCreateFunction를 구현해야 합니다. 일반적으로 이러한 함수는 다음을 실행해야 합니다.

  1. 회의를 만들기 위해 타사 회의 시스템에서 필요할 수 있는 일정 ID 또는 참석자 목록과 같은 Google Calendar 일정 정보를 검색합니다.
  2. 서드 파티 회의 서비스에 연결하고 Google Calendar 일정 정보를 사용하여 새 회의를 만듭니다.
  3. 어떤 이유로든 회의 생성 요청이 실패한 경우 오류 정보를 사용하여 ConferenceError가 포함된 ConferenceData 객체를 빌드하고 반환합니다. 그렇지 않은 경우 다음 단계를 완료합니다.
    1. 회의 동기화를 초기화합니다.
    2. 타사 회의 서비스에서 반환한 정보를 사용하여 새 ConferenceData 객체를 빌드하고 반환합니다.

이벤트 정보를 가져오는 중

타사 회의를 만들려면 해당 Google Calendar 일정에 대한 특정 정보가 필요합니다. 필요한 정확한 이벤트 정보는 여러 타사 회의 시스템에 따라 다르지만, 여기에는 이벤트 시작 시간, 종료 시간, 요약, 참석자 목록, ID가 포함되는 경우가 많습니다.

이 메서드를 호출하면 정의한 각 onCreateFunction에 캘린더와 이벤트 ID가 포함된 인수가 전달됩니다. 이러한 ID를 사용하면 Calendar 고급 서비스를 통해 전체 이벤트 정보를 검색할 수 있습니다.

Google Calendar가 존재하기 전에 일정에 회의 세부정보를 추가할 수 있습니다. 이러한 경우 Google Calendar는 onCreateFunction에 유효한 eventId를 전달하지만 이후에 Calendar.Events.get()를 호출하면 이벤트가 존재하지 않는다는 오류 응답이 발생할 수 있습니다. 이러한 경우 자리표시자 데이터를 사용하여 타사 회의를 만드는 것이 가장 좋습니다. 이 데이터는 다음에 이벤트가 동기화될 때 대체됩니다.

서드 파티 회의 만들기

onCreateFunction에서 필요한 이벤트 데이터를 가져오면 타사 회의 시스템에 연결하여 회의를 만들어야 합니다. 이를 위해 일반적으로 타사 회의 시스템에서 지원하는 API 요청을 실행합니다. 타사 회의 솔루션 문서를 확인하여 회의를 만드는 데 사용할 수 있는 API 요청을 결정합니다.

Apps Script에서 외부 API 요청을 처리하는 가장 쉬운 방법은 Apps Script용 OAuth2 또는 Apps Script용 OAuth1 오픈소스 라이브러리를 사용하는 것입니다. UrlFetch 서비스를 사용하여 외부 API에 연결할 수도 있지만 이 경우 승인 세부정보를 명시적으로 처리해야 합니다.

회의 생성을 요청한 후 새 회의 세부정보를 검색하기 위해 추가 요청을 해야 할 수 있습니다.

회의 동기화 초기화

부가기능이 타사 시스템에서 회의를 만든 후에는 Google Calendar 일정의 변경사항이 회의에 반영되도록 몇 가지 단계를 거쳐 동기화를 사용 설정해야 합니다.

회의 생성 후 동기화 설정에 관한 자세한 내용은 Calendar 변경사항 동기화를 참고하세요.

회의 데이터 빌드

그러면 onCreateFunction는 타사 서비스에서 반환한 회의 정보를 사용하여 ConferenceData 객체를 빌드하고 반환해야 합니다. Conference data 섹션은 이 객체의 콘텐츠를 설명합니다. Google Calendar는 이 정보를 사용하여 회의가 시작된 후 사용자를 회의로 안내합니다.

ConferenceData 객체를 빌드할 때는 필드 길이, 진입점 URI의 형식, 허용된 진입점 조합에 몇 가지 제한사항이 있습니다. 예를 들어 단일 ConferenceData에 최대 VIDEO개의 진입점이 있을 수 있습니다. 이러한 제한은 해당 conferenceData 필드의 Calendar API 이벤트에 설명된 제한사항과 동일하지만 Apps Script에서 설명된 모든 API 이벤트 필드를 사용할 수 있는 것은 아닙니다.

오류 처리

경우에 따라 서드 파티 회의 시스템에서 반환된 오류로 인해 회의 생성을 완료할 수 없습니다. 이러한 경우 부가기능은 Google Calendar가 적절히 작동할 수 있도록 ConferenceError 세부정보를 포함하는 ConferenceData 객체를 빌드하고 반환하여 오류 조건을 강력하게 처리해야 합니다.

오류를 보고하도록 ConferenceData 객체를 구성할 때 ConferenceError 객체 외에 ConferenceData 구성요소를 포함하지 않아도 됩니다. ConferenceErrors에는 ConferenceErrorType(오류 메시지)가 있을 수 있습니다. 인증의 경우 사용자가 타사 회의 시스템에 로그인할 수 있는 URL이 필요합니다.

다음은 onCreateFunction의 예시입니다. 함수의 이름은 무엇이든 지정할 수 있으며 부가기능 프로젝트 매니페스트에 정의하기만 하면 됩니다.

create3rdPartyConference() 함수는 타사 시스템에 연결하여 회의를 만들고 getAuthenticationUrl() 함수는 타사 시스템 인증 URL을 만듭니다. 서드 파티 시스템 세부정보는 타사 시스템 세부정보에 따라 크게 달라지므로 완전히 구현되지는 않습니다.

initializeSyncing() 함수는 여기에 표시되지 않으며 동기화에 필요한 예비 작업을 처리합니다. 자세한 내용은 캘린더 변경사항 동기화를 참고하세요.

/**
 *  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
 *  you 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 = {};

  // Get the add-on settings information to pass to the third-party system.
  // Alternatively, store the add-on setting information on the third-party
  // system.
  var props = PropertiesService.getUserProperties();
  var disableVideo = props.getProperty('disableVideo') || "false";
  var namePrefix = props.getProperty('namePrefix')

  // 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;
}