サイレント モード、不在、勤務場所の予定を管理する

このページでは、Google Calendar API を使用して、Google カレンダー ユーザーのステータスを表示する予定を作成する方法について説明します。ステータス イベントは、ユーザーがどこにいるか、何をしているか（サイレント モード、不在設定、特定の場所での勤務など）を示します。

Google カレンダーでは、サイレント モード、不在、勤務地の予定を作成して、カスタム ステータスと勤務地を示すことができます。これらの機能は、メイン カレンダーでのみ、一部の Google カレンダー ユーザーにのみ提供されます。

詳しくは、Google カレンダーでサイレント モードを使用するとユーザーの勤務場所を有効または無効にするをご覧ください。

カレンダーのステータス イベントを読み取って一覧表示する

Calendar API の Events リソースで、カレンダーのステータス イベントを読み取って一覧表示できます。

ステータス イベントを読み取るには、イベントの eventId を指定して events.get メソッドを使用します。

ステータス イベントを一覧表示するには、events.list メソッドを使用し、eventTypes フィールドに次のいずれかの値を指定します。

• 'focusTime'
• 'outOfOffice'
• 'workingLocation'

次に、返された Event オブジェクトで、eventType フィールドにリクエストされた値が含まれていることを確認し、対応するフィールドを参照して、Google カレンダーでユーザーが作成したステータスの詳細を確認します。

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

ステータス イベントの変更をサブスクライブする

Calendar API の Events リソースで、ステータス イベントの変更をサブスクライブできます。

events.watch メソッドを使用し、登録するカレンダーの calendarId と、eventTypes フィールドに次の値の 1 つ以上を指定します。

• 'focusTime'
• 'outOfOffice'
• 'workingLocation'

カレンダーのステータス イベントを作成、更新する

ステータス イベントを作成するには、events.insert メソッドを使用して Events リソースのインスタンスを作成し、イベントタイプに必要なフィールドを設定します。

events.update メソッドを使用してステータス イベントを更新する場合、イベントは必須フィールドを維持する必要があります。

サイレント モードを作成する

サイレント モードの予定を作成するには:

• eventType を 'focusTime' に設定します。
• focusTimeProperties フィールドを含めます。
• transparency フィールドを 'opaque' に設定します。
• イベントの start フィールドと end フィールドを、時間指定イベント（開始時刻と終了時刻が指定されている）になるように設定します。
  サイレント モードの予定は終日イベントにできません。

機能の詳細については、Google カレンダーでサイレント モードを使用するをご覧ください。

不在設定を作成する

不在イベントを作成するには:

• eventType を 'outOfOffice' に設定します。
• outOfOfficeProperties フィールドを含めます。
• transparency フィールドを 'opaque' に設定します。
• イベントの start フィールドと end フィールドを、時間指定イベント（開始時刻と終了時刻が指定されている）になるように設定します。
  不在の予定は終日の予定にできません。

機能の詳細については、不在にする日付を指定するをご覧ください。

勤務場所を作成する

勤務場所のイベントを作成するには:

• eventType を 'workingLocation' に設定します。
• workingLocationProperties フィールドを含めます。
• visibility フィールドを 'public' に設定します。
• transparency フィールドを 'transparent' に設定します。

• 予定の start フィールドと end フィールドを次のいずれかに設定します。

  • 時間指定イベント（開始時間と終了時間が指定されている場合）。
  • 1 日にまたがる終日イベント（開始日と終了日が指定されている）。

  終日の勤務場所イベントは複数日にまたがることはできませんが、時間指定のイベントは可能です。

次のフィールドは省略可能ですが、officeLocation を挿入する際に、最良のユーザー エクスペリエンスを実現するために指定することをおすすめします。

• workingLocationProperties.officeLocation.buildingId: 組織のリソース データベースの buildingId と一致する必要があります。これにより、会議室の候補など、カレンダーのすべての機能をユーザーが利用できるようになります。
• workingLocationProperties.officeLocation.label: カレンダーのウェブ クライアントとモバイル クライアントに表示されるラベルです。resources.buildings.list メソッドを使用して、建物の ID と建物のラベルを取得できます。

バッチ エンドポイントを介した勤務地のイベントの作成と更新はサポートされていません。

機能の詳細については、業務時間と勤務場所を設定するとユーザーの勤務場所を有効または無効にするをご覧ください。

勤務場所の重複する予定を表示する方法

ユーザーは、カレンダーに複数の勤務地イベントを同時に設定できます。これらのイベントは重複する可能性があり、特定の時間に複数の勤務地が設定されることもあります。ユーザーに 1 つの現在地のみを表示できる状況では、複数のアプリでその現在地が一貫して表示されるようにすべきです。このとき、次のガイドラインに沿って表示するイベントを選択します。

• 時間指定の予定は、終日の予定よりも優先されます。
• 1 回限りの予定は、定期的な予定とその例外よりも優先されます。
• 開始時間が遅いイベントは、開始時間が早いイベントよりも優先されます。
• 期間の短いイベントは、期間の長いイベントよりも優先されます。
• 最近作成されたイベントは、以前に作成されたイベントよりも優先されます。
• 部分的に重複するイベントは、それぞれ独自の勤務地を持つ 2 つの異なるイベントとして表示されます。

Google Apps Script でステータス イベントを作成する

Google Apps Script は、JavaScript ベースのクラウド スクリプト言語で、Google Workspace と統合するビジネス アプリケーションを構築できます。スクリプトはブラウザベースのコードエディタで開発され、Google のサーバーに保存されて実行されます。Google Apps Script のクイックスタートもご覧ください。Apps Script を使用して Google Calendar API にリクエストを送信する方法が説明されています。

次の手順では、Google Apps Script の高度なサービスとして Google Calendar API を使用してステータス イベントを管理する方法について説明します。Google Calendar API のリソースとメソッドの一覧については、リファレンス ドキュメントをご覧ください。

スクリプトを作成して設定する

1. script.google.com/create にアクセスしてスクリプトを作成します。
2. 左側のペインで、[サービス] の横にある [サービスを追加] をクリックします。
3. [Google Calendar API] を選択し、[追加] をクリックします。
4. 有効にすると、API が左側のペインに表示されます。API で使用可能なメソッドとクラスは、エディタで Calendar キーワードを使用して一覧表示できます。

（省略可）Google Cloud プロジェクトを更新する

各 Google Apps Script プロジェクトには、関連付けられた Google Cloud プロジェクトがあります。スクリプトでは、Google Apps Script が自動的に作成するデフォルト プロジェクトを使用できます。カスタムの Google Cloud プロジェクトを使用する場合は、次の手順でスクリプトに関連付けられているプロジェクトを更新します。

1. エディタの左側にある [プロジェクト設定] をクリックします。
2. [Google Cloud Platform（GCP）プロジェクト] で、[プロジェクトを変更] をクリックします。
3. デベロッパー プレビュー プログラムに参加している Google Cloud プロジェクトのプロジェクト番号を入力し、[プロジェクトを設定] をクリックします。
4. 左側の [エディタ] を選択して、コードエディタに戻ります。

スクリプトにコードを追加する

次のコードサンプルは、メインのカレンダーでステータス イベントを作成、読み取り、一覧表示する方法を示しています。

1. 次のコードをコードエディタに貼り付けます。

   primary は、ログインしているユーザーのメイン カレンダーにアクセスするためのキーワードです。別のカレンダーの予定を取得するには、calendarId パラメータをメールアドレスに設定します。これにより、少なくとも予定の有無のアクセス権を持つ他のユーザーのカレンダーのステータス イベントを読み取ることができます。セカンダリ カレンダーにステータス イベントを設定することはできません。

   /** Creates a focus time event. */
   function createFocusTime() {
     const event = {
       start: { dateTime: '2023-11-14T10:00:00+01:00' },
       end: { dateTime: '2023-11-14T12:00:00+01:00' },
       eventType: 'focusTime',
       focusTimeProperties: {
         chatStatus: 'doNotDisturb',
         autoDeclineMode: 'declineOnlyNewConflictingInvitations',
         declineMessage: 'Declined because I am in focus time.',
       }
     }
     createEvent(event);
   }
   
   /** Creates an out of office event. */
   function createOutOfOffice() {
     const event = {
       start: { dateTime: '2023-11-15T10:00:00+01:00' },
       end: { dateTime: '2023-11-15T18:00:00+01:00' },
       eventType: 'outOfOffice',
       outOfOfficeProperties: {
         autoDeclineMode: 'declineOnlyNewConflictingInvitations',
         declineMessage: 'Declined because I am on vacation.',
       }
     }
     createEvent(event);
   }
   
   /** Creates a working location event. */
   function createWorkingLocation() {
     const event = {
       start: { date: "2023-06-01" },
       end: { date: "2023-06-02" },
       eventType: "workingLocation",
       visibility: "public",
       transparency: "transparent",
       workingLocationProperties: {
         type: 'customLocation',
         customLocation: { label: "a custom location" },
       }
     }
     createEvent(event);
   }
   
   /**
     * Creates a Calendar event.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
     */
   function createEvent(event) {
     const calendarId = 'primary';
   
     try {
       var response = Calendar.Events.insert(event, calendarId);
       var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
       console.log(event);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Reads the event with the given eventId.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
     */
   function readEvent() {
     const calendarId = 'primary';
   
     // Replace with a valid eventId.
     const eventId = "sample-event-id";
   
     try {
       var response = Calendar.Events.get(calendarId, eventId);
       var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
       console.log(event);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /** Lists focus time events. */
   function listFocusTimes() {
     listEvents('focusTime');
   }
   
   /** Lists out of office events. */
   function listOutOfOffices() {
     listEvents('outOfOffice');
   }
   
   /** Lists working location events. */
   function listWorkingLocations() {
     listEvents('workingLocation');
   }
   
   /**
     * Lists events with the given event type.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
     */
   function listEvents(eventType = 'default') {
     const calendarId = 'primary'
   
     // Query parameters for the list request.
     const optionalArgs = {
       eventTypes: [eventType],
       showDeleted: false,
       singleEvents: true,
       timeMax: '2023-04-01T00:00:00+01:00',
       timeMin: '2023-03-27T00:00:00+01:00',
     }
     try {
       var response = Calendar.Events.list(calendarId, optionalArgs);
       response.items.forEach(event =>
         console.log(eventType === 'workingLocation' ? parseWorkingLocation(event) : event));
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Parses working location properties of an event into a string.
     * See https://developers.google.com/workspace/calendar/api/v3/reference/events#resource
     */
   function parseWorkingLocation(event) {
     if (event.eventType != "workingLocation") {
       throw new Error("'" + event.summary + "' is not a working location event.");
     }
   
     var location = 'No Location';
     const workingLocation = event.workingLocationProperties;
     if (workingLocation) {
       if (workingLocation.type === 'homeOffice') {
         location = 'Home';
       }
       if (workingLocation.type === 'officeLocation') {
         location = workingLocation.officeLocation.label;
       }
       if (workingLocation.type === 'customLocation') {
         location = workingLocation.customLocation.label;
       }
     }
     return `${event.start.date}: ${location}`;
   }
   

サンプルコードの実行

1. コードエディタの上にあるプルダウン メニューから実行する関数を選択し、[実行] をクリックします。
2. 初回実行時には、アクセスを承認するよう求めるメッセージが表示されます。Apps Script がカレンダーにアクセスすることを承認します。
3. スクリプト実行の結果は、ウィンドウの下部に表示される [実行ログ] で確認できます。