使用Google Calendar API的events.list接口返回空结果集并无限循环问题

我有一个包含单次事件和重复事件的Google Calendar，偶尔会通过Google Calendar API运行脚本，删除所有现有事件并添加新事件来刷新日历：

• 调用无额外参数的events.list接口：https://www.googleapis.com/calendar/v3/calendars/calendarId/events，返回空结果集但附带nextPageToken，使用该token请求下一页仍返回空结果，循环会无限进行。
• 添加singleEvents=true参数可正常获取结果，但重复事件会被展开为单次事件，导致需要删除的日历条目大幅增多。

无参数调用时的API响应示例：

{
  "kind": "calendar#events",
  "etag": "\"p329vtmnsvedos0o\"",
  "summary": "Events",
  "description": "",
  "updated": "2025-07-01T12:26:06.035Z",
  "timeZone": "Europe/London",
  "accessRole": "owner",
  "defaultReminders": [],
  "nextPageToken": "CkwKPAo6CkwIvfvvwgYQmLiFigMSKhooChwKGmZxa2tzMmRjaGdodGtucmt1Mm5xc2pobDFjEggKBgiAhZm-BhoMCPenj8MGENCSitACwD4B",
  "items": []
}

这是Google Calendar API events.list接口的默认行为导致的：

1. 默认参数showDeleted=false，不会返回已被标记为删除的事件；
2. 当日历中存在大量已删除事件（包括重复事件的母事件被软删除）时，API的分页机制会基于**所有事件（含已删除）**的总数生成nextPageToken，但当前页过滤掉已删除事件后无有效条目可返回，就会出现空items但带nextPageToken的情况，进而触发无限循环。
3. 无参数调用时，接口仅返回重复事件的母事件而非所有实例，若母事件已被标记为删除但未彻底清除，也会出现空结果但分页token存在的问题。

1. 添加showDeleted=true参数：调用接口时带上该参数，会返回所有事件（包括已删除的），分页token会在遍历完所有事件后消失，避免无限循环。同时可通过事件的status字段区分已删除和有效事件，针对性处理。
   示例请求：https://www.googleapis.com/calendar/v3/calendars/calendarId/events?showDeleted=true
2. 明确指定maxResults参数：虽然默认值为250，但显式设置maxResults=250可确保每页返回条目数符合预期，降低分页异常概率。
3. 直接处理重复事件母事件：若目标是删除所有事件，无需展开重复实例，只需获取所有主事件（不带singleEvents=true参数），结合showDeleted=true拿到所有需删除的母事件，删除母事件后其所有重复实例会被自动移除，大幅减少删除操作次数。

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