本文详解如何使用 Google Calendar API 的 events.watch 方法实现实时事件变更通知，重点解决因仅使用 API Key 导致的 401 Invalid Credentials 错误，并提供基于 OAuth 2.0 访问令牌的完整可运行方案。
本文详解如何使用 google calendar api 的 `events.watch` 方法实现实时事件变更通知，重点解决因仅使用 api key 导致的 401 invalid credentials 错误，并提供基于 oauth 2.0 访问令牌的完整可运行方案。
Google Calendar API 的 events.watch 接口允许前端应用在日历事件发生新增、修改或删除时，通过 Webhook 实时接收变更通知——这远优于轮询（polling）方式，既降低服务端压力，又提升响应时效性。但需特别注意：watch 是一个需要身份认证的写操作（POST 请求），仅凭公开的 API Key 无法调用，必须使用有效的 OAuth 2.0 访问令牌（access token）。
❗ 为什么原代码会返回 401 错误？
在您的 watchCalendar() 函数中，gapi.client.init 仅传入了 apiKey 和 discoveryDocs，而未注入用户授权凭证。虽然 events.list（GET）对公开日历支持 API Key 调用，但 events.watch（POST）属于受保护的写操作，强制要求 Authorization: Bearer
✅ 正确实现步骤
-
启用 Calendar API 并配置 OAuth 凭据
在 Google Cloud Console 中：- 启用 Google Calendar API；
- 创建 OAuth 2.0 凭据（类型为 Web application），设置已获授权的 JavaScript 源（如 http://localhost:8000）；
- 记录 Client ID（后续用于登录授权）。
获取并注入访问令牌
使用 gapi.auth2 初始化登录流程，确保用户完成授权后获得有效 access_token：
function initAuthAndWatch() {
gapi.load('client:auth2', () => {
gapi.client.init({
clientId: 'YOUR_CLIENT_ID.apps.googleusercontent.com',
discoveryDocs: ['https://www.googleapis.com/discovery/v1/apis/calendar/v3/rest'],
scope: 'https://www.googleapis.com/auth/calendar.readonly'
}).then(() => {
// 尝试自动登录（若已授权过）
return gapi.auth2.getAuthInstance().signIn();
}).then(() => {
// 此时 token 已就绪，可安全调用 watch
return gapi.client.calendar.events.watch({
calendarId: 'your-calendar-id@group.calendar.google.com',
resource: {
id: 'unique-watch-id-123', // 全局唯一，建议用 UUID
type: 'web_hook',
address: 'https://your-domain.com/webhook-handler' // ⚠️ 必须是 HTTPS + 已验证的网域
}
});
}).then(response => {
console.log('Watch successfully created:', response.result);
console.log('Expiration (ms):', response.result.expiration);
// 保存 channel ID 和 expiration，用于后续续订
}).catch(err => {
console.error('Watch failed:', err);
if (err.status === 403) {
console.warn('Check: scope permissions, calendar sharing settings, and webhook domain verification.');
}
});
});
}⚠️ 关键注意事项
- Webhook 地址限制严格：address 必须是 HTTPS 协议，且域名需在 Google Cloud Console 的「OAuth 同意屏幕」中预先验证（Verification requirements）；本地开发可暂用 http://localhost:port（需在凭据中添加），但生产环境不可用。
- Token 有效期：OAuth 访问令牌默认 1 小时过期，需监听 gapi.auth2.getAuthInstance().isSignedIn.listen() 并在过期前刷新或重新登录。
- Channel 管理：每个 watch 请求返回一个 resourceId 和 expiration。务必在过期前调用 events.stop 或发送新 watch 请求续订，否则通知将中断。
- 权限范围（Scope）：https://www.googleapis.com/auth/calendar.readonly 足以监听事件变更；如需响应式操作（如自动处理更新），请升级为 .../auth/calendar。
? 替代方案：轻量级轮询（适用于原型或低频场景）
若暂时无法部署合规 Webhook 或完成 OAuth 验证，可采用带 ETag 缓存的智能轮询：
let lastETag = null;
function pollCalendar() {
gapi.client.calendar.events.list({
calendarId: 'your-calendar-id@group.calendar.google.com',
timeMin: new Date().toISOString(),
fields: 'etag,items(id,updated,summary,start)',
showDeleted: false
}).then(res => {
const currentETag = res.result.etag;
if (currentETag !== lastETag) {
console.log('Calendar changed! Processing', res.result.items.length, 'events.');
lastETag = currentETag;
// 触发 UI 更新或业务逻辑
}
});
}
// 每 5 分钟检查一次（可根据需求调整）
setInterval(pollCalendar, 5 * 60 * 1000);? 提示：利用响应头中的 ETag 可避免传输冗余数据，大幅提升轮询效率。
综上，events.watch 是构建实时日历同步能力的核心能力，其成功落地依赖于正确的 OAuth 流程与合规的 Webhook 基础设施。跳过授权直接使用 API Key 是常见误区，务必以用户身份（而非应用身份）发起请求。完成配置后，您将获得毫秒级的事件变更感知能力，为协作类应用奠定坚实基础。
