서드 파티 회의 만들기

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

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

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

일정 정보 가져오기

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

호출되면 정의한 각 onCreateFunction에는 캘린더 및 이벤트 ID가 포함된 인수가 전달됩니다. 이 ID를 사용하면 Google 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 일정의 변경사항이 회의에 반영되도록 몇 가지 단계를 거쳐 동기화를 사용 설정해야 합니다.

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

회의 데이터 응답 빌드

그런 다음 onCreateFunction는 서드 파티 서비스에서 반환한 회의 정보를 사용하여 ConferenceData 객체를 빌드하고 반환해야 합니다. 회의 데이터 섹션에서는 이 객체의 콘텐츠를 설명합니다. 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
 *  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;
}