在 Google 日曆中新增視訊會議服務

重要事項：本快速入門指南僅適用於視訊會議服務供應商。

下列 Google Workspace 外掛程式快速入門導覽課程會擴充 Google 日曆，與名為「My Web Conferencing」的虛構網路會議服務同步。編輯日曆活動時，使用者可以透過外掛程式，在會議選項中看到「我的網路會議」。

快速入門導覽課程會顯示會議建立和活動同步作業，但必須先連結至會議解決方案 API，才能實際運作。

目標

  • 設定環境。
  • 設定指令碼。
  • 執行指令碼。

必要條件

設定環境

在 Google Cloud 控制台中開啟 Cloud 專案

如果尚未開啟，請開啟您打算用於這個範例的 Cloud 專案：

  1. 前往 Google Cloud 控制台的「選取專案」頁面。

    選取 Cloud 專案

  2. 選取要使用的 Google Cloud 專案。或者，按一下「建立專案」，然後按照畫面上的指示操作。建立 Google Cloud 專案後，您可能需要為專案啟用計費功能。

開啟 Calendar API

本快速入門導覽課程會使用 Calendar 進階服務，存取 Calendar API。

使用 Google API 前，請先在 Google Cloud 專案中啟用這些 API。您可以在單一 Google Cloud 專案中啟用一或多個 API。

    在 Google Cloud 專案中啟用 Calendar API。

    啟用 API

Google Workspace 外掛程式需要設定同意畫面。設定 Google Workspace 外掛程式的 OAuth 同意畫面，可定義 Google 向使用者顯示的內容。

  1. 在 Google Cloud 控制台中，依序前往「選單」 > Google Auth platform >「品牌」。

    前往「品牌宣傳」

  2. 如果您已設定 Google Auth platform，可以在「品牌」、「目標對象」和「資料存取權」中，設定下列 OAuth 同意畫面設定。如果看到「尚未設定」Google Auth platform 訊息，請按一下「開始使用」：
    1. 在「App Information」(應用程式資訊) 下方的「App name」(應用程式名稱) 欄位中，輸入應用程式名稱。
    2. 在「使用者支援電子郵件」中，選擇支援電子郵件地址，方便使用者在同意聲明方面有任何疑問時與您聯絡。
    3. 點選 [下一步]。
    4. 在「目標對象」下方，選取「內部」。
    5. 點選 [下一步]。
    6. 在「聯絡資訊」下方，輸入可接收專案異動通知的電子郵件地址。
    7. 點選 [下一步]。
    8. 在「完成」部分，請詳閱《Google API 服務使用者資料政策》，然後選取「我同意《Google API 服務：使用者資料政策》」。
    9. 按一下 [繼續]。
    10. 按一下「Create」(建立)。
  3. 目前可以略過新增範圍。 日後為 Google Workspace 機構以外的使用者建立應用程式時，請務必將「使用者類型」變更為「外部」。然後新增應用程式需要的授權範圍。詳情請參閱完整的「設定 OAuth 同意畫面」指南。

設定指令碼

建立 Apps Script 專案

  1. 如要建立新的 Apps Script 專案，請前往 script.new。
  2. 按一下「未命名專案」。
  3. 將 Apps Script 專案重新命名為「會議外掛程式」，然後按一下「重新命名」。
  4. 找出 Code.gs 檔案，然後依序點選「更多」圖示 >「重新命名」。將檔案命名為 CreateConf。
  5. 依序點選「新增檔案」圖示 >「指令碼」。
  6. 命名檔案 Syncing。

  7. 將每個檔案的內容替換成下列對應的程式碼：

    CreateConf.gs

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

    Syncing.gs

    /**
 *  Initializes syncing of conference data by creating a sync trigger and
 *  sync token if either does not exist yet.
 *
 *  @param {String} calendarId The ID of the Google Calendar.
 */
function initializeSyncing(calendarId) {
  // Create a syncing trigger if it doesn't exist yet.
  createSyncTrigger(calendarId);

  // Perform an event sync to create the initial sync token.
  syncEvents({'calendarId': calendarId});
}

/**
 *  Creates a sync trigger if it does not exist yet.
 *
 *  @param {String} calendarId The ID of the Google Calendar.
 */
function createSyncTrigger(calendarId) {
  // Check to see if the trigger already exists; if does, return.
  var allTriggers = ScriptApp.getProjectTriggers();
  for (var i = 0; i < allTriggers.length; i++) {
    var trigger = allTriggers[i];
    if (trigger.getTriggerSourceId() == calendarId) {
      return;
    }
  }

  // Trigger does not exist, so create it. The trigger calls the
  // 'syncEvents()' trigger function when it fires.
  var trigger = ScriptApp.newTrigger('syncEvents')
      .forUserCalendar(calendarId)
      .onEventUpdated()
      .create();
}

/**
 *  Sync events for the given calendar; this is the syncing trigger
 *  function. If a sync token already exists, this retrieves all events
 *  that have been modified since the last sync, then checks each to see
 *  if an associated conference needs to be updated and makes any required
 *  changes. If the sync token does not exist or is invalid, this
 *  retrieves future events modified in the last 24 hours instead. In
 *  either case, a new sync token is created and stored.
 *
 *  @param {Object} e If called by a event updated trigger, this object
 *      contains the Google Calendar ID, authorization mode, and
 *      calling trigger ID. Only the calendar ID is actually used here,
 *      however.
 */
function syncEvents(e) {
  var calendarId = e.calendarId;
  var properties = PropertiesService.getUserProperties();
  var syncToken = properties.getProperty('syncToken');

  var options;
  if (syncToken) {
    // There's an existing sync token, so configure the following event
    // retrieval request to only get events that have been modified
    // since the last sync.
    options = {
      syncToken: syncToken
    };
  } else {
    // No sync token, so configure to do a 'full' sync instead. In this
    // example only recently updated events are retrieved in a full sync.
    // A larger time window can be examined during a full sync, but this
    // slows down the script execution. Consider the trade-offs while
    // designing your add-on.
    var now = new Date();
    var yesterday = new Date();
    yesterday.setDate(now.getDate() - 1);
    options = {
      timeMin: now.toISOString(),          // Events that start after now...
      updatedMin: yesterday.toISOString(), // ...and were modified recently
      maxResults: 50,   // Max. number of results per page of responses
      orderBy: 'updated'
    }
  }

  // Examine the list of updated events since last sync (or all events
  // modified after yesterday if the sync token is missing or invalid), and
  // update any associated conferences as required.
  var events;
  var pageToken;
  do {
    try {
      options.pageToken = pageToken;
      events = Calendar.Events.list(calendarId, options);
    } catch (err) {
      // Check to see if the sync token was invalidated by the server;
      // if so, perform a full sync instead.
      if (err.message ===
            "Sync token is no longer valid, a full sync is required.") {
        properties.deleteProperty('syncToken');
        syncEvents(e);
        return;
      } else {
        throw new Error(err.message);
      }
    }

    // Read through the list of returned events looking for conferences
    // to update.
    if (events.items && events.items.length > 0) {
      for (var i = 0; i < events.items.length; i++) {
         var calEvent = events.items[i];
         // Check to see if there is a record of this event has a
         // conference that needs updating.
         if (eventHasConference(calEvent)) {
           updateConference(calEvent, calEvent.conferenceData.conferenceId);
         }
      }
    }

    pageToken = events.nextPageToken;
  } while (pageToken);

  // Record the new sync token.
  if (events.nextSyncToken) {
    properties.setProperty('syncToken', events.nextSyncToken);
  }
}

/**
 *  Returns true if the specified event has an associated conference
 *  of the type managed by this add-on; retuns false otherwise.
 *
 *  @param {Object} calEvent The Google Calendar event object, as defined by
 *      the Calendar API.
 *  @return {boolean}
 */
function eventHasConference(calEvent) {
  var name = calEvent.conferenceData.conferenceSolution.name || null;

  // This version checks if the conference data solution name matches the
  // one of the solution names used by the add-on. Alternatively you could
  // check the solution's entry point URIs or other solution-specific
  // information.
  if (name) {
    if (name === "My Web Conference" ||
        name === "My Recorded Web Conference") {
      return true;
    }
  }
  return false;
}

/**
 *  Update a conference based on new Google Calendar event information.
 *  The exact implementation of this function is highly dependant on the
 *  details of the third-party conferencing system, so only a rough outline
 *  is shown here.
 *
 *  @param {Object} calEvent The Google Calendar event object, as defined by
 *      the Calendar API.
 *  @param {String} conferenceId The ID used to identify the conference on
 *      the third-party conferencing system.
 */
function updateConference(calEvent, conferenceId) {
  // Check edge case: the event was cancelled
  if (calEvent.status === 'cancelled' || eventHasConference(calEvent)) {
    // Use the third-party API to delete the conference too.


  } else {
    // Extract any necessary information from the event object, then
    // make the appropriate third-party API requests to update the
    // conference with that information.

  }
}

  8. 按一下「專案設定」專案設定圖示。

  9. 勾選「在編輯器中顯示『appsscript.json』資訊清單檔案」方塊。

  10. 按一下「編輯器」圖示 。

  11. 開啟 appsscript.json 檔案，然後將內容替換為下列程式碼，再按一下「儲存」圖示 「儲存」圖示。

    appsscript.json

    {
  "addOns": {
    "calendar": {
      "conferenceSolution": [{
        "id": 1,
        "name": "My Web Conference",
        "logoUrl": "https://lh3.googleusercontent.com/...",
        "onCreateFunction": "createConference"
      }],
      "currentEventAccess": "READ_WRITE"
    },
    "common": {
      "homepageTrigger": {
        "enabled": false
      },
      "logoUrl": "https://lh3.googleusercontent.com/...",
      "name": "My Web Conferencing"
    }
  },
  "timeZone": "America/New_York",
  "dependencies": {
    "enabledAdvancedServices": [
    {
      "userSymbol": "Calendar",
      "serviceId": "calendar",
      "version": "v3"
    }
    ]
  },
  "webapp": {
    "access": "ANYONE",
    "executeAs": "USER_ACCESSING"
  },
  "exceptionLogging": "STACKDRIVER",
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.events.readonly",
    "https://www.googleapis.com/auth/calendar.addons.current.event.read",
    "https://www.googleapis.com/auth/calendar.addons.current.event.write",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/script.scriptapp"
  ]
}

複製 Cloud 專案編號

  1. 在 Google Cloud 控制台中，依序前往「選單」圖示 >「IAM 與管理」 >「設定」。

    前往「IAM & Admin Settings」(IAM 與管理員設定)

  2. 在「專案編號」欄位中，複製該值。

設定 Apps Script 專案的 Cloud 專案

  1. 在 Apps Script 專案中，按一下「專案設定」圖示 專案設定圖示。
  2. 在「Google Cloud Platform (GCP) 專案」下方，按一下「變更專案」。
  3. 在「GCP 專案編號」中，貼上 Google Cloud 專案編號。
  4. 點選「設定專案」。

安裝測試部署作業

  1. 在 Apps Script 專案中，按一下「編輯器」 。
  2. 開啟 CreateConf.gs 檔案，然後按一下「執行」。出現提示訊息時，請授權執行指令碼。
  3. 依序點選「部署」>「測試部署作業」。
  4. 依序點選「安裝」>「完成」。

執行指令碼

  1. 前往 calendar.google.com。
  2. 建立新活動或開啟現有活動。
  3. 依序按一下「新增 Google Meet 視訊會議」旁邊的向下箭頭 >「我的網路會議」。由於外掛程式未連結至實際的第三方會議解決方案，因此會顯示「無法建立會議」錯誤。

後續步驟