使用PHP设置Google Calendar自定义ID时始终提示无效ID问题

这个问题我之前帮不少开发者解决过——Google Calendar API对自定义日历ID的格式要求非常严格，你遇到的无效ID报错几乎都是因为ID不符合官方的规则。下面我给你拆解下问题和解决方案：

核心原因：自定义ID的硬性规则 #

Google Calendar不允许随意设置自定义ID，必须满足以下全部条件：

• 长度在5到100个字符之间
• 只能包含小写字母、数字、连字符(-)、下划线(_)、点(.)和@符号
• ID必须全局唯一，不能和任何已存在的日历ID重复
• 注意：不能使用Google默认生成的那种长随机字符串格式（比如abc123xyz@group.calendar.google.com这种系统自动生成的ID结构）

排查与修复步骤 #

1. 检查ID格式合法性 #

先把你的$calendarId对照上面的规则检查一遍：

• 把所有大写字母转成小写
• 移除所有非允许的特殊字符（比如!、#、$等）
• 确保长度在5-100位之间

2. 确认ID唯一性 #

可以先调用CalendarList的查询接口，检查你要设置的ID是否已经被使用：

try {
    $calendar = $service->calendars->get($calendarId);
    echo "该ID已存在：" . $calendar->getSummary();
} catch (Google_Service_Exception $e) {
    // 如果返回404错误，说明ID未被使用
    if ($e->getCode() == 404) {
        echo "ID可用";
    } else {
        echo "检查出错：" . $e->getMessage();
    }
}

3. 正确的代码示例 #

修改后的PHP代码（确保$calendarId符合规则）：

// 符合要求的自定义ID示例：user_001_schedule@yourcompany.com
$calendarId = "user_001_schedule@yourcompany.com";

$newCalendar = new Google_Service_Calendar_Calendar();
$newCalendar->setSummary("用户001的日程日历");
$newCalendar->setDescription("用于同步用户001的工作与个人日程");

// 仅当ID符合所有规则时，调用setId才会成功
$newCalendar->setId($calendarId);

try {
    $createdCalendar = $service->calendars->insert($newCalendar);
    echo "日历创建成功，ID：" . $createdCalendar->getId();
} catch (Google_Service_Exception $e) {
    // 捕获异常查看具体错误原因，API会明确指出是长度/字符/重复问题
    echo "创建失败：" . $e->getMessage();
}

常见错误案例（避坑） #

• User001Calendar：包含大写字母，非法
• cal-001!：包含感叹号，非法字符
• ab：长度仅2位，太短
• existing-calendar@group.calendar.google.com：已被其他日历使用
• a_very_long_id_that_exceeds_one_hundred_characters_abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz：超过100位长度

如果还是报错，一定要查看异常返回的具体信息——Google API会在错误消息里明确说明是哪条规则没满足，比如“Invalid id value: 'User001' (must be lowercase letters, numbers, and -_.@ only)”，根据提示调整即可。

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