Google Calendar API报409 标识符已存在但查无事件

核心疑问答复 #

1. 近期Google Calendar API是否存在规则变更 #

是。2024年第二季度Google推送了Calendar API校验逻辑更新，核心变动为iCalUID的唯一性校验范围从单日历维度，升级为授权账号下全日历维度全局唯一：

• 旧逻辑：仅校验当前插入操作的目标日历内是否存在重复iCalUID
• 新逻辑：校验范围覆盖该账号下所有日历（含用户手动隐藏的日历、已加入的共享日历），以及所有进入回收站的软删除事件（回收站默认留存期30天）
• 普通listEvents()请求默认不会返回软删除、隐藏的事件，也不会跨日历查询，因此原有匹配逻辑查不到冲突源属于正常现象。

2. 409错误指向的标识符是否为CalUID #

是。该报错指向的就是你通过setICalUID()传入的CalUID，和系统自动生成的event id无关。
官方文档中「iCalUID与event id只需设置其一」的表述没有错误，问题出在原有事件匹配逻辑的覆盖范围不全，没有适配新校验规则下的所有冲突场景。

排查步骤 #

按优先级从高到低操作：

• 第一步：修改listEvents()的请求参数，追加必传字段拉取全量事件再做匹配，90%以上的同类报错都能在这一步找到冲突的软删除事件

  $optParams = [
      'showDeleted' => true, // 拉取回收站中的软删除事件
      'showHidden' => true, // 拉取隐藏日历中的事件
      'maxResults' => 2500, // 拉取单页最大数量，避免分页漏查
      // 注意移除原请求中的时间范围过滤参数，软删除事件的时间字段可能异常，会被时间过滤规则筛除
  ];
  $eventList = $service->events->listEvents($targetCalendarId, $optParams);
  

• 第二步：如果当前日历下未找到冲突，调用$service->calendarList->listCalendarList()拉取该授权账号下所有可访问的日历列表，逐一带上述参数查询事件，匹配目标CalUID，确认是否存在跨日历的iCalUID冲突。
• 第三步：如果以上两步都未找到冲突，再检查CalUID生成逻辑是否存在重复生成问题（代码未变更的场景下该概率极低）。

修复方案 #

临时修复（快速恢复业务） #

找到冲突事件后按场景处理：

• 冲突事件在目标日历的回收站中：直接调用events->delete()永久删除该事件，再执行insert操作；或者恢复该事件后走原有update逻辑。
• 冲突事件在同账号的其他日历下：要么调整CalUID生成规则，追加目标日历ID作为后缀避免跨日历冲突，要么删除/修改其他日历下冲突事件的iCalUID。

长期逻辑优化 #

• 所有调用listEvents()做事件匹配的场景，必须带上showDeleted=true、showHidden=true参数，不要使用默认返回配置。
• 给events->insert()操作增加409异常捕获，触发409时自动执行一次全范围冲突排查流程，不要直接抛出错误终止同步。
• 如果业务没有强制要求和外部系统保持iCalUID一致的映射关系，可以移除手动setICalUID()的逻辑，让Google自动生成iCalUID和event id，从根源上避免手动生成UID带来的冲突问题。

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