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

此页面介绍了如何使用 Google 日历 API 创建显示 Google 日历用户的状态。状态事件用于说明用户所在的位置或 他们正在做什么，包括他们是在专注时间、不在办公室，还是 在特定地点办公

在 Google 日历中，用户可以创建专注时间、不在办公室状态和工作状态 位置事件来指明其自定义状态和位置。这些功能包括 仅适用于主日历，且仅适用于部分 Google 日历用户。

有关详情，请参阅在 Google 中使用专注时间 日历 以及为 用户。

读取和列出 Google 日历状态活动

您可以在 Events 资源的 日历 API。

要读取状态事件，请使用 events.get 方法，用于指定 eventId。

如需列出状态事件，请使用 events.list 方法，指定一个 一个或多个 eventTypes 字段：

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

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

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

订阅状态更改事件

您可以在 Events 资源的 日历 API。

使用 events.watch 方法，用于指定 calendarId的 要订阅的日历以及 eventTypes 字段：

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

创建和更新 Google 日历状态活动

要创建状态事件，您需要创建 Events 资源（使用 events.insert 方法，设置 事件类型的必填字段。

如果您使用 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: 此 ID 应与组织的buildingId 资源 数据库。这有助于用户从所有日历功能中受益，例如： 会议室建议。
• workingLocationProperties.officeLocation.label: 这是 Google 日历网页版和移动客户端上显示的标签。您 您可以使用 resources.buildings.list 方法。

无法通过批量端点创建和更新工作地点活动 支持。

有关功能的详细信息，请参阅设置工作时间和 地点 以及为 用户

如何显示工作地点重叠的事件

用户可以在其日历中同时拥有多个工作地点活动 时间重叠，这意味着在任意给定时间， 为其设置的位置。在仅显示一个营业地点的情况下 应以统一的方式在多个位置向用户展示该营业地点 应用。执行此操作时，请遵循以下准则来选择 事件来显示：

• 计时事件 优先级高于全天活动
• 单个活动的优先级高于周期性活动，并且 异常。
• 较晚开始的事件优先于较早开始的事件。
• 持续时间较短的事件优先于持续时间较长的事件 时长。
• 最近创建的活动优先于已创建的活动 。
• 部分重叠的活动应分别显示为两个不同的活动 有自己的工作地点

在 Google Apps 脚本中创建状态事件

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

以下说明介绍了如何使用 Google 日历 API 是 Google Cloud 中的一项高级服务， Google Apps 脚本。如需查看 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/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/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/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/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. 您可以在 窗口底部显示的 Execution Log。