サードパーティの会議を作成する

注: この機能は会議プロバイダ向けに特別に構築されたもので、当初はカレンダーの会議用アドオンとして提供されていました。

スクリプト プロジェクトのマニフェストで定義した各会議ソリューションには、関連付けられた onCreateFunction があります。ユーザーがイベントでその会議ソリューションを選択しようとすると、アドオンはこの関数を呼び出して会議を作成します。

アドオン マニフェストに記述されている各 onCreateFunction を実装する必要があります。一般に、これらの関数は次の処理を行う必要があります。

1. サードパーティの会議システムが会議の作成に必要な、予定 ID や参加者リストなどの Google カレンダーの予定情報を取得します。
2. サードパーティの会議サービスに接続し、Google カレンダーの予定情報を使用して新しい会議を作成します。
3. 会議の作成リクエストが何らかの理由で失敗した場合は、エラー情報を使用して ConferenceError を含む ConferenceData オブジェクトを構築して返します。それ以外の場合は、次の手順を行います。
   1. 会議の同期を初期化します。
   2. サードパーティの会議サービスから返された情報を使用して、新しい ConferenceData オブジェクトを構築して返します。

イベント情報の取得

サードパーティの会議を作成するには、対応する Google カレンダーの予定に関する特定の情報が必要です。必要なイベント情報の詳細は、サードパーティの会議システムによって異なりますが、多くの場合、イベントの開始時間、終了時間、概要、参加者リスト、ID などが含まれます。

呼び出されると、定義した各 onCreateFunction に、カレンダーとイベントの ID を含む引数が渡されます。これらの ID を使用して、Google カレンダーの高度なサービスでイベントの完全な情報を取得できます。

Google カレンダーでは、予定が存在する前に会議の詳細情報を追加できます。このような場合、Google カレンダーは onCreateFunction に有効な eventId を渡しますが、後続の Calendar.Events.get() の呼び出しで、予定が存在しないというエラー レスポンスが返されることがあります。このような場合は、プレースホルダ データを使用してサードパーティの会議を作成することをおすすめします。このデータは、次回イベントが同期されたときに置き換えられます。

サードパーティ会議の作成

onCreateFunction が必要なイベントデータを取得したら、サードパーティ製会議システムに接続して会議を作成する必要があります。通常、これはサードパーティの会議システムでサポートされている API リクエストを行うことで実現されます。サードパーティの会議ソリューションのドキュメントで、会議の作成に使用できる API リクエストを確認します。

Apps Script で外部 API リクエストを処理する最も簡単な方法は、OAuth2 for Apps Script または OAuth1 for Apps Script オープンソース ライブラリを使用することです。UrlFetch サービスを使用して外部 API に接続することもできますが、この場合は認証の詳細を明示的に処理する必要があります。

会議の作成をリクエストした後、新しい会議の詳細を取得するために追加のリクエストが必要になる場合があります。

会議の同期を初期化する

アドオンがサードパーティ システムで会議を正常に作成したら、同期を有効にして、Google カレンダーの予定の変更が会議に反映されるようにする必要があります。

会議の作成後に同期を設定する方法については、カレンダーの変更を同期するをご覧ください。

会議データのレスポンスを構築する

サードパーティ サービスから返された会議情報を使用して、onCreateFunction は ConferenceData オブジェクトを構築して返す必要があります。会議データのセクションで、このオブジェクトの内容について説明します。Google カレンダーでは、この情報を使用して、会議が開始されたらユーザーを会議に誘導します。

ConferenceData オブジェクトをビルドする際は、フィールドの長さ、エントリ ポイント URI の形式、許可されるエントリ ポイントの組み合わせに制限があることに注意してください。たとえば、1 つの ConferenceData には 1 つの VIDEO エントリ ポイントしか存在できません。これらの制限事項は、対応する conferenceData フィールドの Calendar API イベントで説明されている制限事項と同じです。ただし、そこで説明されている API イベント フィールドのすべてが Apps Script で使用できるわけではありません。

エラー処理

サードパーティの会議システムから返されたエラーが原因で、会議の作成を完了できないことがあります。このような場合、アドオンは ConferenceError の詳細を含む ConferenceData オブジェクトを構築して返すことで、エラー条件を堅牢に処理する必要があります。これにより、Google カレンダーが適切に対応できるようになります。

エラーを報告する 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;
}