如何在Django中通过Google Calendar API获取日历事件？

首先先把前置准备做对，90%的新手卡壳都是前置步骤漏了：

• 先核对OAuth授权的权限范围（scope）：如果你之前做登录只申请了用户基础信息、邮箱的权限，是没法访问日历数据的。只读获取事件的话，给授权请求加上https://www.googleapis.com/auth/calendar.events.readonly权限即可；如果需要修改事件再换读写权限，不要一开始就申请全量日历权限，后续上线审核会更麻烦。改完scope之后要让用户重新走一遍授权流程，之前拿到的旧access token没有日历权限，直接调接口会报403。
• 去你创建OAuth凭证的Google Cloud项目后台，找到「API和服务」板块，搜索Google Calendar API手动点启用，很多人忘了开服务，哪怕token是对的也会报接口不存在/无权限的错误。
• 开发阶段记得把你用来测试的Google账号加到项目的测试用户列表里，不然授权的时候会直接被拦截。

接下来先验证凭证有效性，别上来就堆业务代码，减少排错成本：

• 走完OAuth流程拿到access token之后，先用接口测试工具发一个简单请求验证：请求地址填https://www.googleapis.com/calendar/v3/users/me/calendarList，请求头加Authorization: Bearer 你拿到的access_token，如果能正常返回你账号下的日历列表，说明凭证、权限、服务状态都没问题，可以开始写拉取事件的逻辑。
• 如果这一步报错，先看错误码：401查token是不是写错、过期；403查scope是不是对、API有没有启用、测试账号有没有加对，不用上来就搜博客瞎改代码。

拉取事件的核心逻辑非常简单，新手先从拉取主日历事件开始跑通流程：

• 每个Google账号的默认主日历ID固定为primary，不用先查日历列表，直接用这个ID调接口就行，等跑通了再扩展拉取其他自定义日历。
• 拉取事件的接口是GET请求，地址为https://www.googleapis.com/calendar/v3/calendars/primary/events，请求头和之前验证时一样，带Bearer格式的Authorization字段即可。
• 新手建议先加这几个常用参数减少后续处理成本：
  • singleEvents=true：会把重复生成的事件（比如每周例会）拆成单个独立事件返回，不用你自己解析复杂的重复规则
  • timeMin：传ISO格式的时间字符串，比如2024-06-01T00:00:00Z，只返回这个时间之后的事件，避免拉到太多历史无效数据
  • maxResults：设置单次拉取的事件条数，比如20、50，根据自己的业务需求定
• 接口返回的JSON结构里，items数组就是你要的事件列表，单条事件里summary是事件标题、start/end是开始/结束时间、description是事件备注，按业务需求取字段解析就行。

几个新手高频踩坑点提前说：

• access token默认有效期只有1小时，过期之后要用OAuth流程拿到的refresh token去换新的access token，不要每次过期都让用户重新登录授权。
• 解析时间的时候注意区分：返回字段里带dateTime的是带时区的具体时间点，带date的是全天事件，不要用同一套逻辑解析，容易出时区错误。
• 如果要做分页拉取所有事件，看返回结果里的nextPageToken字段，把这个值作为pageToken参数传进下一次请求就行，直到返回结果里没有这个字段就说明拉完了。

学习资源不用找零散的技术博客，优先看对应你所用开发语言的官方快速入门示例，里面从授权到调用接口的代码都是可直接运行的，替换成你自己项目的客户端ID、密钥就能跑通；遇到参数、报错问题直接查官方的API参考文档，每个字段、错误码的说明都写的很明确，比二手博客准确率高很多。

内容的提问来源于stack exchange，提问作者John Paul