# 日历概述
日历 API 基于飞书日历功能开放了对日历、日程、忙闲等资源的操作与查询能力。你能以应用或用户的身份调用日历 API 来实现多种功能。例如：
- 创建日程并预定会议室
- 邀请飞书用户或第三方用户参与日程
- 查看用户忙闲
- 同步用户的休假状态
- 绑定或解绑 Exchange 账户
## 客户案例
开放平台包含日历业务的集成方案：
- 货拉拉：[飞书智能会务，轻松搞定会议管理](https://open.feishu.cn/solutions/detail/meetings)
- 中国移动国际有限公司：[休假状态实时同步，沟通协作更高效](https://open.feishu.cn/solutions/detail/leave)
## 接入流程
日历 API 的基本接入流程如下图所示，如需了解详细的 API 接入流程，参见[流程概述](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)。
## 开发教程
体验场景化示例教程，了解如何搭配使用日历 API 来实现日历日程管理。
- [快速构建日历日程](https://open.feishu.cn/document/home/quickly-build-a-feishu-calendar-schedule/introduction)
- [自动获取日历日程](https://open.feishu.cn/document/home/calendar-event-sync/prepare)
## 使用限制
- 单个用户或者单个应用可订阅的日历数量上限为 1000。
- 每个日程可添加的参与人数量上限为 3000。
## 资源介绍
日历业务域以资源为中心进行开放。日历是一个用于聚合日程的实体，用户在订阅日历后，可以在日历内创建日程并邀请参与人。资源关系图如下：
日历业务域包含的资源以及资源定义如下表：
资源 | 定义
---|---
[日历](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/introduction) | 日历是包含一系列相关日程的容器，是同一类日程的聚合实体。
[日历访问控制](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/introduction) | 日历的成员列表，可以给不同成员授予不同的日历操作权限。
[日程](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/introduction) | 日程包含一个确定的日期或者时间范围，是会议预定的基本实体，分为普通日程和重复性日程。
此外，还存在以下类型的日程：
- 例外日程：重复性日程中的某一个日程被修改后，与其他重复日程产生了区别，则称该日程为例外日程。
- 请假日程：一种特殊日程，在用户请假时，会在日历上显示请假日程。
[日程参与人](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event-attendee/introduction) | 参与日程的对象，包括用户、群组、邮箱和会议室。
**注意事项**：**说明**：日程添加会议室的方式，也是通过添加参与人进行的。
[日程参与人群成员](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event-attendee-chat_member/list) | 参与日程的群成员。
[忙闲](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/freebusy/list) | 日历在某一时间段内的忙碌、空闲信息。
[请假](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/timeoff_event/introduction) | 给用户创建某一日期或者时间段的休假日程。
[日历设置](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/setting/generate_caldav_conf) | 给指定设备生成一个 CalDAV 账号密码，用于将客户端日历信息同步到本地设备日历。
[Exchange 绑定与解绑](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/exchange_binding/introduction) | 完成 Exchange 账户到客户端账户的绑定或解绑。
在飞书客户端中日历资源如下：
- 图中①区域展示了用户日历，包括用户管理的日历和订阅的日历。
- 图中②区域展示了当前日历时间段内的日程忙闲信息。选中某一日程后，可以查看日程的内容、参与人、会议室等详细信息。
## 方法列表
以下提供了日历业务域内所有资源的 API 和事件列表。
文中表格涉及的 **商店** 是指商店应用，**自建** 是指企业自建应用。应用类型说明参见[应用类型简介](https://open.feishu.cn/document/home/app-types-introduction/overview)。
### 日历
#### API 列表
**[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建
---|---|---|---|---
[获取主日历](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/primary)
`POST` /open-apis/calendar/v4/calendars/primary
> 获取用户的主日历实体信息 | 获取日历、日程及忙闲信息(calendar:calendar:readonly) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[创建日历](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/create)
`POST` /open-apis/calendar/v4/calendars
> 以当前身份创建一个日历实体 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[删除日历](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/delete)
`DELETE` /open-apis/calendar/v4/calendars/:calendar_id
> 以当前身份去删除指定日历实体 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[获取日历](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/get)
`GET` /open-apis/calendar/v4/calendars/:calendar_id
> 以当前身份获取指定日历实体 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[获取日历列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/list)
`GET` /open-apis/calendar/v4/calendars
>获取当前身份下的日历列表 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[更新日历](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/patch)
`PATCH` /open-apis/calendar/v4/calendars/:calendar_id
>以当前身份更新指定日历实体信息 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[搜索日历](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/search)
`POST` /open-apis/calendar/v4/calendars/search
>以应用身份搜索日历信息 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `tenant_access_token` | **✓** | **✓**
[订阅日历](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/subscribe)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/subscribe
>以当前身份订阅指定日历 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[取消订阅日历](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/unsubscribe)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/unsubscribe
>以当前身份取订指定日历 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[订阅日历变更事件](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/subscription)
`POST` /open-apis/calendar/v4/calendars/subscription
>与当前身份的日历资源建立事件订阅关系 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `user_access_token` | **✓** | **✓**
[取消订阅日历变更事件](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/unsubscription)
`POST` /open-apis/calendar/v4/calendars/unsubscription
>取消与当前身份的日历资源建立事件订阅关系 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `user_access_token` | **✓** | **✓**
#### 事件列表
**[事件 (Event)](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)** | 触发时机 | 权限要求（满足任一） | 事件类型 | 商店 | 自建
---|---|---|---|---|---
[日历变更](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/events/changed) | 当订阅用户的日历列表有日历变动时 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | calendar.calendar.changed_v4 | **✓** | **✓**
### 日历访问控制
#### API 列表
**[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建
---|---|---|---|---
[创建访问控制](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/create)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/acls
> 以当前身份添加访问控制权限，即添加日历成员 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[删除访问控制](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/delete)
`DELETE` /open-apis/calendar/v4/calendars/:calendar_id/acls/:acl_id
> 以当前身份删除日历的控制权限，即删除日历成员 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[获取访问控制列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/list)
`GET` /open-apis/calendar/v4/calendars/:calendar_id/acls
> 获取日历的控制权限列表，即日历成员列表 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[订阅日历访问控制变更事件](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/subscription)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/acls/subscription
> 指定日历下的日历成员变更事件 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `user_access_token` | **✓** | **✓**
[取消订阅日历访问控制变更事件](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/unsubscription)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/acls/unsubscription
> 取消监听指定日历下的日历成员变更事件 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `user_access_token` | **✓** | **✓**
#### 事件列表
**[事件 (Event)](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)** | 触发时机 | 权限要求（满足任一） | 事件类型 | 商店 | 自建
---|---|---|---|---|---
[ACL 新建](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/events/created) | 当被订阅的日历上有 ACL 被创建时 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | calendar.calendar.acl.created_v4 | **✓** | **✓**
[ACL 移除](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/events/deleted) | 当被订阅的日历上有 ACL 被删除时 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | calendar.calendar.acl.deleted_v4 | **✓** | **✓**
### 日程
#### API 列表
**[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建
---|---|---|---|---
[创建日程](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/create)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/events
> 在日历上创建一个日程 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[删除日程](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/delete)
`DELETE` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id
> 删除日历上的一个日程 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[获取日程](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/get)
`GET` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id
> 获取日历上的一个日程信息 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[获取日程列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/list)
`GET` /open-apis/calendar/v4/calendars/:calendar_id/events
> 获取日历下的日程列表 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[更新日程](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/patch)
`PATCH` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id
>更新日历上的一个日程 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[搜索日程](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/search)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/events/search
>以用户身份搜索某日历下的相关日程 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `user_access_token` | **✓** | **✓**
[订阅日程变更事件](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/subscription)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/events/subscription
>以用户身份订阅指定日历下的日程变更事件 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `user_access_token` | **✓** | **✓**
[取消订阅日程变更事件](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/unsubscription)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/events/unsubscription
>以用户身份取消订阅指定日历下的日程变更事件 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `user_access_token` | **✓** | **✓**
#### 事件列表
**[事件 (Event)](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)** | 触发时机 | 权限要求（满足任一） | 事件类型 | 商店 | 自建
---|---|---|---|---|---
[日程变更](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/events/changed) | 当被订阅的用户日历下有日程变更时 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | calendar.calendar.event.changed_v4 | **✓** | **✓**
### 日程参与人
#### API 列表
**[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建
---|---|---|---|---
[创建日程参与人](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event-attendee/create)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees
> 批量给日程添加参与人 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[获取日程参与人列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event-attendee/list)
`GET` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees
> 获取日程的参与人列表 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
[删除日程参与人](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event-attendee/batch_delete)
`POST` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees/batch_delete
> 批量删除日程的参与人 | 更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
### 日程参与人群成员
#### API 列表
**[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建
---|---|---|---|---
[获取日程参与群成员列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event-attendee-chat_member/list)
`GET` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees/:attendee_id/chat_members
> 获取日程的群参与人的群成员列表 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `tenant_access_token`
`user_access_token` | **✓** | **✓**
### 忙闲
#### API 列表
**[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建
---|---|---|---|---
[查询忙闲](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/freebusy/list)
`POST` /open-apis/calendar/v4/freebusy/list
> 查询用户主日历或会议室的忙闲信息 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `tenant_access_token` | **✓** | **✓**
### 请假
#### API 列表
**[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建
---|---|---|---|---
[创建请假日程](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/timeoff_event/create)
`POST` /open-apis/calendar/v4/timeoff_events
> 为指定用户创建一个请假日程 | 创建或删除请假日程(calendar:timeoff) | `tenant_access_token` | **✓** | **✓**
[删除请假日程](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/timeoff_event/delete)
`DELETE` /open-apis/calendar/v4/timeoff_events/:timeoff_event_id
> 删除一个指定的请假日程 | 创建或删除请假日程(calendar:timeoff) | `tenant_access_token` | **✓** | **✓**
### 日历设置
#### API 列表
**[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建
---|---|---|---|---
[生成 CalDAV 配置](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/setting/generate_caldav_conf)
`POST` /open-apis/calendar/v4/settings/generate_caldav_conf
> 为当前用户生成一个 CalDAV 账号密码 | 更新日历及日程信息(calendar:calendar)
生成 CalDAV 配置信息(calendar:setting:generate_caldav_conf) | `user_access_token` | **✓** | **✓**
### Exchange 绑定与解绑
#### API 列表
**[方法 (API)](https://open.feishu.cn/document/ukTMukTMukTM/uITNz4iM1MjLyUzM)** | 权限要求（满足任一） | **[访问凭证](https://open.feishu.cn/document/ukTMukTMukTM/uMTNz4yM1MjLzUzM)（选择其一）** | 商店 | 自建
---|---|---|---|---
[创建 Exchange 绑定关系](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/exchange_binding/create)
`POST` /open-apis/calendar/v4/exchange_bindings
> 将 Exchange 账户绑定到飞书账户 | 获取日历、日程及忙闲信息(calendar:calendar:readonly)
更新日历及日程信息(calendar:calendar) | `user_access_token` | **✓** | **✓**
[获取绑定状态](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/exchange_binding/get)
`GET` /open-apis/calendar/v4/exchange_bindings/:exchange_binding_id
> 获取 Exchange 账户的绑定状态 | 获取日历、日程及忙闲信息(calendar:calendar:readonly) | `user_access_token` | **✓** | **✓**
[解除 Exchange 绑定关系](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/exchange_binding/delete)
`DELETE` /open-apis/calendar/v4/exchange_bindings/:exchange_binding_id
> 解除 Exchange 账户和飞书账户的绑定关系 | 更新日历及日程信息(calendar:calendar) | `user_access_token` | **✓** | **✓**