管理專注時間、不在辦公室和工作地點活動

本頁說明如何使用 Google Calendar API 建立活動，顯示 Google 日曆使用者的狀態。狀態事件會說明使用者所在位置或正在執行的動作，包括是否處於專注時間、不在辦公室，或是在特定地點工作。

使用者可以在 Google 日曆中建立專注時間、不在辦公室和工作地點活動，指出自己的自訂狀態和地點。這些功能僅適用於主日曆，且僅開放部分 Google 日曆使用者。

詳情請參閱「在 Google 日曆中使用專注時間」和「為使用者開啟或關閉工作地點功能」。

讀取及列出日曆狀態事件

您可以在 Calendar API 的 Events 資源中讀取及列出日曆狀態活動。

如要讀取狀態事件，請使用 events.get 方法，並指定事件的 eventId。

如要列出狀態事件，請使用 events.list 方法，並在 eventTypes 欄位中指定一或多個下列值：

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

接著，在傳回的 Event 物件中，檢查 eventType 欄位是否具有要求的值，並參閱對應的欄位，瞭解使用者在 Google 日曆中建立的狀態詳細資料：

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

訂閱狀態事件的變更

您可以訂閱 Calendar API 的 Events 資源中狀態事件的變更。

使用 events.watch 方法，指定要訂閱的日曆 calendarId，並在 eventTypes 欄位中指定下列一或多個值：

• '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 欄位設為下列其中一項：

  • 有時間限制的活動 (指定開始和結束時間)；
  • 全天活動 (已指定開始和結束日期)，且活動時間正好為一天。

  全天工作地點活動無法跨越多天，但有時間的活動可以。

插入 officeLocation 時，建議填寫下列選填欄位，以獲得最佳使用者體驗：

• workingLocationProperties.officeLocation.buildingId： 這應與機構的資源資料庫中的 buildingId 相符。這樣一來，使用者就能充分運用 Google 日曆的所有功能，例如會議室建議。
• workingLocationProperties.officeLocation.label：這是日曆網頁和行動用戶端上顯示的標籤。您可以使用 resources.buildings.list 方法擷取建築物 ID 和建築物標籤。

系統不支援透過批次端點建立及更新工作地點事件。

如要瞭解這項功能的詳細資訊，請參閱「設定工作時間與地點」和「為使用者開啟或關閉工作地點功能」

如何顯示重疊的工作地點活動

使用者可以在日曆上同時有多個工作地點事件重疊，也就是說，任何時間都可能設定多個工作地點。如果只能向使用者顯示單一位置，則應在多個應用程式中一致顯示該位置。執行這項操作時，請按照下列規範選擇要顯示的活動：

• 設有時間的活動會優先於全天活動顯示。
• 單一活動的優先順序高於週期性活動及其例外狀況。
• 開始時間較晚的活動優先於開始時間較早的活動。
• 系統會優先顯示時間較短的活動，而非時間較長的活動。
• 系統會優先處理較晚建立的事件。
• 部分重疊的活動應顯示為兩個不同的活動，每個活動都有自己的工作地點。

在 Google Apps Script 中建立狀態事件

Google Apps Script 是以 JavaScript 為基礎的雲端指令碼設計語言，可讓您建立與 Google Workspace 整合的業務應用程式。您可以在瀏覽器型程式碼編輯器中開發指令碼，並在 Google 伺服器上儲存及執行指令碼。另請參閱 Google Apps Script 快速入門導覽，瞭解如何開始使用 Apps Script 向 Google Calendar API 傳送要求。

以下操作說明介紹如何使用 Google Calendar API (Google Apps Script 的進階服務) 管理狀態事件。如需 Google Calendar API 資源和方法的完整清單，請參閱參考說明文件。

建立及設定指令碼

1. 前往 script.google.com/create 建立指令碼。
2. 在左側窗格中，按一下「服務」旁的「新增服務」圖示 。
3. 選取「Google Calendar API」，然後按一下「新增」。
4. 啟用後，API 會顯示在左側窗格中。您可以在編輯器中使用 Calendar 關鍵字，列出 API 中的可用方法和類別。

(選用) 更新 Google Cloud 專案

每個 Google Apps Script 專案都有相關聯的 Google Cloud 專案。您的指令碼可以使用 Google Apps Script 自動建立的預設專案。如要使用自訂 Google Cloud 專案，請按照下列步驟更新與指令碼相關聯的專案。

1. 在編輯器左側，按一下「專案設定」圖示 。
2. 點選「Google Cloud Platform (GCP) 專案」下方的「變更專案」。
3. 輸入 Developer Preview 計畫中的 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. 您可以在視窗底部的「Execution Log」中檢查指令碼執行結果。