カレンダー会議クイックスタート

重要: このクイックスタートは、ウェブ会議プロバイダのみを対象としています。

以下の Google Workspace アドオン クイックスタートでは、Google カレンダーを拡張して、「My Web Confound」という架空のウェブ会議サービスと同期させます。カレンダーの予定を編集するときに、アドオンを使用すると、ユーザーは会議オプションとして [マイウェブ会議] を表示できます。

このクイックスタートでは、会議の作成とイベントの同期について説明しますが、会議ソリューションの API に接続するまで機能しません。

目標

  • 環境を設定する。
  • スクリプトを設定します。
  • スクリプトを実行します。

前提条件

環境を設定する

Google Cloud コンソールで Cloud プロジェクトを開く

まだ開いていない場合は、このサンプルで使用する Cloud プロジェクトを開きます。

  1. Google Cloud コンソールで [プロジェクトの選択] ページに移動します。

    Cloud プロジェクトを選択

  2. 使用する Google Cloud プロジェクトを選択します。または、[プロジェクトを作成] をクリックし、画面の指示に従います。Google Cloud プロジェクトを作成する場合は、プロジェクトの課金を有効にすることが必要な場合があります。

Calendar API を有効にする

このクイックスタートでは、Calendar API にアクセスするカレンダーの拡張サービスを使用します。Google API を使用する前に、Google Cloud プロジェクトで API を有効にする必要があります。1 つの Google Cloud プロジェクトで 1 つ以上の API を有効にできます。

Google Workspace アドオンには、同意画面の構成が必要です。Google Workspace アドオンの OAuth 同意画面を構成すると、Google がユーザーに表示する内容が決まります。

  1. Google Cloud コンソールで、メニュー > [API とサービス] > [OAuth 同意画面] に移動します。

    OAuth 同意画面に移動

  2. [ユーザーの種類] で [内部] を選択し、[作成] をクリックします。
  3. アプリ登録フォームに入力し、[保存して次へ] をクリックします。
  4. 現時点では、スコープの追加をスキップして、[Save and Continue] をクリックします。今後、Google Workspace 組織外で使用するアプリを作成する場合は、[ユーザータイプ] を [外部] に変更してから、アプリに必要な認証スコープを追加する必要があります。

  5. アプリ登録の概要を確認します。変更するには、[編集] をクリックします。アプリ登録に問題がない場合は、[Back to Dashboard] をクリックします。

スクリプトを設定する

Apps Script プロジェクトを作成する

  1. 新しい Apps Script プロジェクトを作成するには、script.new に移動します。
  2. [無題のプロジェクト] をクリックします。
  3. Apps Script プロジェクトの Conference アドオンの名前を変更し、[名前を変更] をクリックします。
  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 と管理] の設定に移動

  2. [プロジェクト番号] フィールドで、値をコピーします。

Apps Script プロジェクトの Cloud プロジェクトを設定する

  1. Apps Script プロジェクトで、[プロジェクトの設定] プロジェクト設定のアイコン をクリックします。
  2. [Google Cloud Platform(GCP)プロジェクト] で、[プロジェクトを変更] をクリックします。
  3. [GCP のプロジェクト番号] に、Google Cloud のプロジェクト番号を貼り付けます。
  4. [プロジェクトを設定] をクリックします。

テストデプロイをインストールする

  1. Apps Script プロジェクトで、編集者アイコン をクリックします。
  2. CreateConf.gs ファイルを開き、[Run] をクリックします。プロンプトが表示されたら、スクリプトを承認します。
  3. [デプロイ] > [デプロイをテスト] をクリックします。
  4. [インストール] > [完了] をクリックします。

スクリプトを実行する

  1. calendar.google.com にアクセスします。
  2. 新しい予定を作成するか既存の予定を開きます。
  3. [Google Meet のビデオ会議を追加] の横にある下矢印 > [ウェブ会議] をクリックします。アドオンが実際のサードパーティの会議ソリューションに接続されていないため、「Failed to create conference」エラーが表示されます。

次のステップ