管理专注时间、不在办公室和工作地点活动

本页面介绍了如何使用 Google Calendar API 创建显示 Google 日历用户状态的活动。状态活动描述了用户所在的位置或正在做的事情，包括用户是否处于专注时间、不在办公室或在特定地点工作。

在 Google 日历中，用户可以创建专注时间、不在办公室和工作地点活动，以表明其自定义状态和地点。这些功能仅适用于主要日历，并且仅适用于部分 Google 日历用户。

如需了解详情，请参阅在 Google 日历中使用专注时间 以及为 用户启用或停用工作地点。

读取和列出日历状态活动

您可以在 Events resource of the Calendar API 中读取和列出日历状态活动。

如需读取状态活动，请使用 events.get 方法，并指定活动的 eventId。

如需列出状态活动，请使用 events.list 方法，并在 eventTypes 字段中指定以下一个或多个值：

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

然后，在返回的 Event 对象中，检查 eventType 字段是否具有 请求的值，并参阅相应字段，详细了解用户在 Google 日历中创建的 状态：

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

订阅状态活动变更

您可以在 Events resource of the Calendar API 中订阅状态活动变更。

使用 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 匹配。这有助于用户充分利用所有日历功能，例如会议室建议。
• workingLocationProperties.officeLocation.label：这是在日历 Web 客户端和移动客户端上显示的标签。您 可以使用 resources.buildings.list 方法提取建筑物的 ID 和建筑物标签。

不支持通过批处理端点创建和更新工作地点活动。

如需了解功能详情，请参阅设置工作时间和 地点 以及为 用户启用或停用工作地点

如何显示重叠的工作地点活动

用户可以在日历中同时设置多个重叠的工作地点活动，这意味着任何给定时间都可能设置多个工作地点。如果只能向用户显示一个地点，则应在多个应用中始终向用户显示该地点。执行此操作时，请按照以下准则选择要显示的活动：

• 定时活动的优先级高于全天活动。
• 单次活动的优先级高于周期性活动及其 例外情况。
• 开始时间较晚的活动的优先级高于开始时间较早的活动。
• 时长较短的活动的优先级高于时长较长的活动。
• 最近创建的活动的优先级高于之前创建的活动。
• 部分重叠的活动应显示为两个不同的活动，每个活动都有自己的工作地点。

在 Google Apps 脚本中创建状态活动

Google Apps 脚本是一种基于 JavaScript 的云 脚本语言，可让您构建与 Google Workspace 集成的商务应用。脚本在基于浏览器的代码编辑器中开发，并存储在 Google 的服务器上运行。另请参阅 Google Apps 脚本 快速入门，开始使用 Apps 脚本向 Google 日历 API 发送请求。

以下说明介绍了如何在 Google Apps 脚本中使用 Google Calendar API作为高级服务来管理状态活动。如需查看 Google 日历 API 资源和方法的完整列表， 请参阅参考文档。

创建和设置脚本

1. 前往 script.google.com/create创建脚本。
2. 在左侧窗格中，点击服务旁边的“添加服务”图标 。
3. 选择 Google Calendar API ，然后点击添加 。
4. 启用后，API 会显示在左侧窗格中。您可以使用编辑器中的 Calendar 关键字列出 API 中的可用方法和类。

（可选）更新 Google Cloud 项目

每个 Google Apps 脚本项目都有一个关联的 Google Cloud 项目。您的脚本可以使用 Google Apps 脚本自动创建的默认项目。如果您想使用自定义 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 脚本访问您的日历。
3. 您可以在窗口底部显示的执行日志 中检查脚本执行结果。