如何监听Google Calendar变更事件实现双向同步与增量同步

1. 请求URL构造 #

watch请求的URL为固定格式，仅需替换对应日历ID即可：
https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events/watch
其中{calendarId}为目标日历的唯一标识，监听用户主日历时可直接填primary，其他共享日历替换为对应日历ID即可。
如果需要监听特定范围的事件变更，可在URL后追加和events.list接口一致的查询参数，比如timeMin、maxResults等，仅匹配参数条件的事件变更才会触发推送。

2. 前置校验要求 #

• 你使用的Google Cloud项目需提前完成推送接收域名的所有权验证，不支持未验证的域名作为推送地址
• 接收推送的address必须为公网可访问的HTTPS接口，不支持HTTP协议和自定义端口
• 调用接口的OAuth2令牌需至少拥有https://www.googleapis.com/auth/calendar.events.readonly及以上权限的日历授权范围

3. 请求必填参数说明 #

所有核心参数放在POST请求的JSON Body中传递，必填参数如下：

• id：自定义的唯一通道标识，建议用UUID生成，用于后续区分不同日历的推送通知，最长可填64位字符
• type：固定值，填web_hook即可
• address：你的服务接收推送通知的HTTPS接口地址

可选扩展参数推荐添加：

• token：自定义的校验字符串，后续Google推送请求会在请求头中携带该值，可用于校验请求合法性
• expiration：通道过期时间戳（毫秒级），最长可设置为当前时间加1个月，到期后通道自动失效

4. POST请求发送示例 #

以下为curl调用示例，替换对应占位符即可直接测试：

curl -X POST \
  'https://www.googleapis.com/calendar/v3/calendars/primary/events/watch' \
  -H "Authorization: Bearer 你的OAuth2访问令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "web_hook",
    "address": "https://你的服务域名/calendar/push-receiver",
    "token": "自定义校验token_xxx123",
    "expiration": 1735689600000
}'

5. 后续处理逻辑 #

• 接口调用成功会返回200状态码，响应体中包含resourceId、expiration等字段，需将id（通道ID）、resourceId、过期时间存储到数据库，后续停止监听或重建通道时需要使用
• 日历有符合条件的变更时，Google会发送POST请求到你填写的address，可通过请求头的X-Goog-Channel-ID匹配对应日历，触发增量同步逻辑即可
• 通道到期前需要重新调用watch接口创建新的推送通道，避免漏收变更通知
• 同一日历+同一接收地址多次发起watch请求，旧的同配置通道会自动失效，无需手动调用停止接口

内容的提问来源于stack exchange，提问作者Mohamed Riyazath R