公司行政最近提了个需求:二十多间会议室都挂在Google Workspace日历上,前台和每层电梯口要放个屏幕,实时显示会议室当前有没有人订、下一场几点开始。接Google Workspace API来做这个“预订房间展示”的项目,前后花了差不多一周,把权限、接口、前端渲染整条链路跑通了。这篇文章不聊虚的,直接把方案选型、代码、报错排查全部摊开讲,准备用Google Workspace API做会议室预订/展示的同学可以直接照着抄。
先给一个整体结论:展示预订房间这件事,核心不是“写一个页面”,而是想清楚怎么用Google Calendar API读取会议室的实时占用状态,再决定是自己写接口还是用别人封装好的方案。房间能不能被API查到、服务账号有没有权限读日历,这两步决定了项目80%的成败。下面我按实际开发顺序来拆解。
1. 先理清需求边界:展示预订房间到底要展示什么
1.1 从最终效果反推API能力
接到需求别急着写代码,先花半天把“展示什么”问清楚。会议室展示屏,常见的展示内容有四类:全部房间列表、当前时刻每个房间的空闲/占用状态、每个房间当天的完整预订排期、未来的可预订时间段。这四类需求对应的API能力完全不一样。
- 房间列表:来自Admin SDK Directory API的“资源日历”接口。
- 空闲/占用状态:用Calendar API的freebusy一次批量查询,效率最高。
- 当天排期:用Calendar API的events.list,按时间范围拉事件列表。
- 未来可预订时间段:需要在events.list基础上自己算空档区间,稍微复杂一点。
我这次做的版本是前三者的组合:一层楼一块屏,屏幕默认展示该楼层所有房间的“当前状态”,点进去某个房间,再展示今天的会议排期。后来加了一个“未来两小时可预订”的快捷入口,需要在events.list返回的数据里做时间区间合并,这个后面细说。
1.2 为什么不自建数据库,而是直接读Google日历
很多人第一反应是:把Google日历的预订数据同步到自己的MySQL/PostgreSQL里,然后展示屏读自己的库。这个思路在“数据量极大、需要复杂报表”的场景下成立,但在会议室预订这个场景下纯属自找麻烦。
原因在于:预订行为的发生地是Google日历。用户在Outlook、手机日历、或自己的OA里发起会议邀请时,以“会议室资源”为参与人的事件会实时写入会议室的资源日历。你如果同步到自建库,就必然面临两个问题——实时性(同步延迟)和一致性(改期/取消的增量同步)。与其维护一套同步任务,不如展示层直接走API,Google日历就是唯一的真相源。
当然,纯API方案也有代价:每次页面刷新都要请求Google,对配额敏感。所以展示层要做缓存和合理的轮询周期,这个我在第4部分会讲。
1.3 链路选型:直连API还是套一层服务端
能不能在浏览器里直接调Google Calendar API?技术上可以,但我不建议。第一,前端直连必须暴露API Key,虽然可以把Key限制到指定域名,但会议室数据毕竟是公司内部信息,暴露Key等于把读取权限开放给了任何能访问页面的人。第二,Google API的CORS策略、配额管理,在纯前端场景很难精细控制。第三,你迟早要加“创建预订”“取消预订”这类写操作,写操作不能靠前端直连。
所以推荐的架构是:浏览器 → 自己的后端服务 → Google Workspace API → 返回JSON → 前端渲染。后端只暴露几个业务接口,比如“获取房间列表”“获取某房间当天排期”,Google的鉴权信息全部收在后端,前端只拿业务数据。这个架构一开始就定型,后面加功能非常顺。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 开工前必须做好的账号与权限准备
2.1 Google Cloud项目与API启用
打开Google Cloud控制台(console.cloud.google.com),新建一个项目,比如“room-display”。这个项目就是你和Google API之间的“租户”,所有的凭据、配额、API开关都在这里管理。
接下来要启用两个API:
- Google Calendar API:房间日历事件的读写,核心中的核心。
- Admin SDK API:用来读取会议室资源列表,也就是“哪些房间存在”。
如果你只需要读不需要写,Calendar API可以只开读权限范围的凭据,但API本身还是要启用。在“已启用的API和服务”里搜索这两个API,逐个Enable。这一步不做,后面所有请求都会返回404或403。
2.2 三种凭据怎么选:API Key、OAuth还是服务账号
Google提供了几种凭据类型,很多人第一次做容易混。我的选择逻辑是这样的:
| 凭据类型 | 适用场景 | 是否能读会议室日历 | 是否要人工授权 |
|---|---|---|---|
| API Key | 访问公开数据、地图等 | 不能,Calendar API不支持纯Key访问私人日历 | 不需要 |
| OAuth 2.0 | 代表某个用户操作 | 能,但需要用户手动同意授权弹窗 | 需要 |
| 服务账号 | 代表应用自身访问域内数据 | 能,配合域范围委派后无需弹窗 | 需要在管理后台授权一次 |
会议室展示屏是一个“无人值守”的后台程序,没有用户坐在那里点“授权”。所以服务账号是唯一正确选择。在Cloud控制台创建服务账号,下载JSON格式的私钥,这个JSON文件就是后端程序的身份证明。注意,服务账号本身有自己的邮箱地址,格式类似 room-display@your-project.iam.gserviceaccount.com,后面授权要用到。
2.3 Scope:最容易翻车的权限声明
Google API的权限控制用的是OAuth Scope机制。Sco
