スクリプト プロジェクトのマニフェストで定義した各会議ソリューションには、onCreateFunction
が関連付けられています。ユーザーがその会議ソリューションを予定に選択しようとすると、アドオンはこの関数を呼び出して会議を作成します。
アドオン マニフェストで記述されている各 onCreateFunction
を実装する必要があります。一般に、これらの関数は次のことを行う必要があります。
- サードパーティのビデオ会議システムが会議を作成するために必要とする Google カレンダーの予定情報(予定 ID や参加者のリストなど)を取得します。
- サードパーティの会議サービスに接続し、Google カレンダーの予定情報を使用して新しい会議を作成します。
- なんらかの理由で会議作成リクエストが失敗した場合は、エラー情報を使用して
ConferenceError
を含むConferenceData
オブジェクトを作成して返します。それ以外の場合は、次の手順を行います。- 会議の同期を初期化します。
- サードパーティのビデオ会議サービスから返された情報を使用して、新しい
ConferenceData
オブジェクトを作成して返します。
イベント情報の取得
サードパーティ製ツールでの会議を作成するには、対応する Google カレンダーの予定に関する特定の情報が必要です。必要なイベント情報は、サードパーティのカンファレンス システムによって異なりますが、多くの場合、イベントの開始時間、終了時間、概要、参加者リスト、ID が含まれます。
定義した各 onCreateFunction
が呼び出されると、カレンダー ID とイベント 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
に VIDEO
エントリ ポイントは 1 つだけ存在できます。これらの制限は、対応する 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; }