Synology Calendar API 技能

概述

使用官方 Calendar API 管理 Synology Calendar。

文档： CalendarAPIGuide_enu.pdf

连接

环境变量

bash
export SYNOLOGYURL=http://{nasip}:5000 # 内网地址
export SYNOLOGY_USER={username}
export SYNOLOGY_PASSWORD=your-password

快速开始

python
from client import SynologyCalendar

cal = SynologyCalendar()
cal.login()

列出日历

calendars = cal.get_calendars() for c in calendars: print(f{c[calid]}: {c[caldisplayname]})

cal.logout()

---

API 参考

日历操作 (SYNO.Cal.Cal)

方法	描述	状态
getcalendars()	列出所有日历	✅ 可用
getcalendar(cal_id)

获取日历详情 | ✅ 可用 | | create_calendar(...) | 创建日历 | ✅ 可用 | | deletecalendar(calid) | 删除日历 | ✅ 可用 |

事件操作 (SYNO.Cal.Event)

方法	描述	状态
listevents(calidlist)	列出事件	✅ 可用
getevent(evt_id)

获取事件详情 | ✅ 可用 | | create_event(...) | 创建事件 | ✅ 可用 | | deleteevent(evtid) | 删除事件 | ✅ 可用 |

事件创建说明：

✅ 可用：

• - 所有事件类型现均可通过 v1 API 正常工作

⚠️ 关键：SID 必须放在 URL 参数中，而非 JSON 请求体

Synology Calendar v1 API 要求 _sid 参数位于 URL 查询字符串中，而非 JSON 请求体。

create_event 参数：

参数	类型	必填	示例
cal_id	字符串	✅	/admin/home/
summary

字符串 | ✅ | 事件标题 |
| dtstart | 整数 | ✅ | 1770440000 |
| dtend | 整数 | ✅ | 1770443600 |
| isallday | 布尔值 | ✅ | false |
| isrepeatevt | 布尔值 | ✅ | false |
| color | 字符串 | ✅ | #D9AE00 |
| description | 字符串 | ✅ | 描述 |
| notify_setting | 数组 | ✅ | [] |
| participant | 数组 | ✅ | [] |
| timezone | 字符串 | (非全天事件时必填) | Asia/Shanghai |

示例：
python

非全天事件（可用）

cal.create_event(
cal_id=/{username}/home/,
summary=会议,
dtstart=now,
dtend=now + 3600,
isallday=False,
isrepeatevt=False,
description=团队会议,
color=#D9AE00,
timezone=Asia/Shanghai
)

待办事项操作 (SYNO.Cal.Todo)

方法	描述	状态
createtodo(...)	创建任务	✅ 可用
listtodos(...)

列出任务 | ✅ 可用 | | gettodo(evtid) | 获取任务详情 | ✅ 可用 | | deletetodo(evtid) | 删除任务 | ✅ 可用 | | completetodo(evtid) | 标记完成 | ✅ 可用 |

联系人操作 (SYNO.Cal.Contact)

方法	描述	状态
list_contacts()	列出参与者	✅ 可用

---

CLI 使用

bash

登录

python client.py login

列出日历

python client.py list-calendars

列出待办事项

python client.py list-todos --cal-id /{username}/home_todo/

创建待办事项

python client.py create-todo \ --cal-id /{username}/home_todo/ \ --title 任务名称

完成待办事项

python client.py complete-todo --evt-id 1012

---

已知问题

事件创建（已通过 v1 API 修复）

之前的问题： 事件创建返回错误 9009，原因如下：

1. 1. 使用了 v5 API 而非 v1 API
2. 缺少 originalcalid 参数
3. SID 传递位置错误（JSON 请求体而非 URL 参数）

解决方案： 使用 v1 API，并注意：

• - calid 来自 getcalendars() 的响应
• originalcalid = calid（针对非共享日历）
• SID 放在 URL 参数中：?sid=xxx

---

日历

ID	名称	类型
/{username}/home/	我的日历	事件
/{username}/home_todo/

收件箱 | 待办事项 |

---

链接

• - 官方 API 指南