서드 파티 회의 만들기

스크립트 프로젝트 매니페스트에 정의한 각 회의 솔루션에는 연결된 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 일정 변경사항이 회의에 반영되도록 동기화를 사용 설정하기 위한 몇 가지 단계를 거쳐야 합니다.

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

회의 데이터 응답 빌드

그런 다음 onCreateFunction는 서드 파티 서비스에서 반환한 회의 정보를 사용하여 ConferenceData 객체를 빌드하고 반환해야 합니다. 회의 데이터 섹션에서는 이 객체의 콘텐츠를 설명합니다. Google Calendar는 이 정보를 사용하여 회의가 시작되면 사용자를 회의로 안내합니다.

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

오류 처리

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

오류를 보고하기 위해 ConferenceData 객체를 구성할 때 ConferenceError 객체 외의 ConferenceData 구성요소를 포함할 필요가 없습니다. ConferenceErrors에는 ConferenceErrorType, 오류 메시지, 인증 문제의 경우 사용자가 서드 파티 회의 시스템에 로그인할 수 있는 URL이 포함될 수 있습니다.

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

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

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

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