做企业内部工具的人,大概率都接到过这样一个需求:把会议室预订情况放到一个电视大屏上,让大家一进门就能看到哪个房间空着、哪个房间马上开始。这个需求听起来简单,真正做起来要处理的东西不少,核心就是把 Google Workspace 里的资源日历(Resource Calendar)数据拉出来,通过 API 读成结构化数据,再交给前端渲染成看板。我这次用的是 Google Workspace Calendar API 的 freebusy 查询和 events.list 两个接口,外加 Admin SDK Directory API 拉房间元数据,整套流程从零跑通,半天时间足够。
如果你之前只写过业务 CRUD,没碰过 Google Workspace 的 API,这篇文章刚好可以当一份可直接抄的作业。我会按“整体思路 -> 前置准备 -> 核心实现 -> 错误排查 -> 扩展方案”的顺序来写,里面所有代码和配置都是我在真实项目里验证过的。
1. 整体设计:一个会议室看板背后的接口组合
1.1 选 Calendar API 而不是自己造轮子
会议室预订在日常里最常用的载体就是日历系统,Google Workspace 的 Calendar 天然支持“资源”这个概念。也就是说,管理员可以把每个会议室建成一个“资源日历”,它有自己的日历 ID、名称、容量、楼层等属性,别人预订会议室时通过邀请这个资源日历完成占用。这种方式比自建数据库存预订记录要稳得多,因为日历本身就处理了冲突检测、循环事件、参会人提醒这些复杂逻辑,我们只要负责把数据捞出来展示即可。
所以选型上我没有用数据库表存预订,也没有去解析 CSV 导出,而是直接面向 Calendar API 开发。这样做的好处有三个:第一是数据实时性有保证,任何人通过日历客户端改了预订,API 立刻能查到;第二是不用维护一套数据同步逻辑,避免两边数据不一致;第三是 API 本身免费,只要控制好配额,运营成本几乎为零。坏处也有,其中一个就是 API 的权限模型比较绕,尤其是服务账号访问资源日历时,坑不少,这个后面会展开讲。
有朋友可能会问,Google Apps Script 不是也能读取日历数据吗?确实能,而且写起来更简单。但 Apps Script 不容易承载一个独立的网页服务,而且它的触发器和执行时间限制比较多,适合做轻量自动化,不适合做 7 x 24 小时运行的看板后端。从稳定性和可维护性角度,我选择了写一个小服务,通过 RESTful API 接口调 Calendar API,然后前端定时拉取数据。
1.2 两种鉴权方式和服务账号方案
Google Workspace 的 API 鉴权常见是两种方式:OAuth 2.0 用户授权和服务账号。
OAuth 2.0 用户授权适合有“当前登录用户”的场景,比如用户自己点击“登录”按钮,浏览器弹出授权页,应用拿到一个短期有效期 token,再拿 token 去访问“这个用户”的数据。会议室展示终端这种无人值守的场景用起来很别扭,因为 token 会过期,不能总让保洁阿姨去帮忙重新授权。
服务账号则是应用自己拥有一套密钥,不依赖人的操作。只要你在 Google Workspace 管理后台配置好域范围委派(domain-wide delegation),服务账号就可以模拟某个有权限的账号去访问域内数据。我最终用的是服务账号加模拟用户(impersonate)的方式:服务账号本身不是真人,但通过管理员提前授权,它可以“扮演”一个拥有会议室查看权限的账号,去读取资源日历。
这里必须提醒一句:有人在网上说服务账号可以直接访问任意日历,这是不对的。服务账号模拟的目标用户,必须在目标日历上有适当权限。最简单的做法是用一个超级管理员账号作为模拟目标,但在真实企业里权限不宜给这么大,更稳妥的办法是创建一个专门的服务账号,在管理后台给它授予读取日历资源的权限,或者把目标日历共享给它。看板类应用只读就够了,不要申请写权限。
1.3 整体数据流
- 第一步,从 Admin SDK Directory API 拉取全部房间资源,得到每个房间的资源名称、容量、楼层和资源邮箱(这其实就是日历 ID)。
- 第二步,用 Calendar API 的 freebusy 接口,一次查询多个房间在某个时间段内的 busy 区间。
- 第三步,如果只想显示“占用/空闲”,第二步就已经够了;如果还想显示预订标题、预订人、开始结束时间,就用 events.list 把每个资源日历的事件拉出来。
- 第四步,后端把数据整合成 JSON 返回给前端,前端按“房间 x 时间”二维表格渲染,定时刷新。
这个数据流按天跑、按分钟跑都行,完全看你的展示精度需求。我最后做的是每 60 秒刷新一次当前时间和占用状态,事件列表每 5 分钟刷新一次,这样既保证实时性,又不浪费配额。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 准备:资源日历、项目与权限配置
2.1 把每个房间变成“资源日历”
如果你的企业已经通过 Google Workspace 管理后台创建了会议室资源,那这一步可以跳过。我实际遇到的情况是,很多团队的会议室是在日历客户端里手工建一个日历当房间用,这种方式不是不行,但拿不到结构化的房间元数据,比如所在楼层和容量。所以我建议走正规路线:让 Workspace 管理员在管理控制台里创建资源。
具体路径一般是:管理控制台 -> 日历 -> 资源和日历(不同版本入口名称略有差异)。在这里可以创建建筑物(Building)、楼层(Floor)和房间资源(Resource)。创建房间资源时,系统会要求填名称、容量、所属建筑和楼层,部分版本还支持填入房间邮箱。创建完成后,该资源会对应一个资源日历,有一个类似 conference-room-astana@yourdomain.com 的地址,这就是后续调用 Calendar API 时要用的日历 ID。
如果你现在是测试环境、没有管理控制台权限,也可以先手工建一个普通日历当作房间日历,照样能跑通后面的代码。真正区别只是少了一些元数据字段。建议先用手工日历完成开发,最后再让管理员补资源数据。
