概述

业务介绍

日历 API 基于飞书日历功能开放了对日历、日程、忙闲等实体的操作查询能力，开发者能以「应用」或「用户」身份调用日历 API 操作对应数据。你可以实现多种功能，例如：

创建日程/会议室预定

邀请飞书用户/第三方用户参与日程

查看用户忙闲查询

同步用户休假状态

绑定/解绑exchange账户

更多应用场景可参考客户案例：

货拉拉：飞书智能会务，轻松搞定会议管理

中国移动国际有限公司：休假状态实时同步，沟通协作更高效

接入流程

	步骤	介绍
1	创建一个应用	如需创建企业自建应用，可参考自建应用的开发流程如需创建应用商店应用，可参考开发和上架应用商店应用
2	调用API，对日历进行操作	调用API前，你需要先获取访问凭证并开启对应的权限，详情参见如何调用服务端API你还可以在 API 调试台中快速调试这些 API ，使用方法参见API 调试台使用指南。
3	监听事件，获知日历的变化	监听事件前，你需要先申请相应的权限，详情参见事件订阅概述

开发教程

教程名称	教程步骤拆解
快速实现日历日程的自动获取	准备工作确定需要调用的API 订阅事件日历同步日程同步

资源介绍

日历业务域以“资源”为中心进行开放，资源的关系图如下：

资源的定义如下：

资源	资源定义
日历	日历是包含一系列相关日程的容器，是同一类日程的聚合实体。
访问控制列表	日历的成员列表，可以给不同成员授予不同的日历操作权限。
日程	日程包含一个确定的日期或者时间范围，是会议预定的基本实体，分为普通日程和重复性日程。
日程参与人	参与日程的对象，包括用户、会议室、群组和第三方email。
日程参与人群成员	参与日程的群成员。
忙闲	日历在某一时间段内的忙碌空闲信息。
请假	给用户创建某一日期或者时间段的休假日程。
日历设置	给指定设备生成一个CalDAV账号密码，用于将客户端日历信息同步到本地设备日历。
Exchange绑定	完成exchange账户到客户端账户的绑定/解绑。

以下将详细介绍每个资源的字段、方法、事件。

资源：日历

查看资源字段及示例

方法列表

“商店”代表应用商店应用；“自建”代表企业自建应用

	方法 (API)	权限要求（满足任一）		访问凭证（选择其一）	商店	自建
获取主日历`POST` /open-apis/calendar/v4/calendars/primary获取用户的主日历实体信息	获取日历、日程及忙闲信息	tenant_access_tokenuser_access_token	✓	✓
创建日历`POST` /open-apis/calendar/v4/calendars以当前身份创建一个日历实体	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
删除日历`DELETE` /open-apis/calendar/v4/calendars/:calendar_id以当前身份去删除指定日历实体	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
获取日历`GET` /open-apis/calendar/v4/calendars/:calendar_id以当前身份获取指定日历实体	获取日历、日程及忙闲信息更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
获取日历列表`GET` /open-apis/calendar/v4/calendars获取当前身份下的日历列表	获取日历、日程及忙闲信息更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
更新日历`PATCH` /open-apis/calendar/v4/calendars/:calendar_id以当前身份更新指定日历实体信息	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
搜索日历`POST` /open-apis/calendar/v4/calendars/search以应用身份搜索日历信息	获取日历、日程及忙闲信息更新日历及日程信息	tenant_access_token	✓	✓
订阅日历`POST` /open-apis/calendar/v4/calendars/:calendar_id/subscribe以当前身份订阅指定日历	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
取消订阅日历`POST` /open-apis/calendar/v4/calendars/:calendar_id/unsubscribe以当前身份取订指定日历	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
订阅日历变更事件`POST` /open-apis/calendar/v4/calendars/subscription与当前身份的日历资源建立事件订阅关系	获取日历、日程及忙闲信息更新日历及日程信息	user_access_token	✓	✓
取消订阅日历变更事件`POST` /open-apis/calendar/v4/calendars/unsubscription取消与当前身份的日历资源建立事件订阅关系	更新日历及日程信息获取日历、日程及忙闲信息	user_access_token	✓	✓

事件列表

	事件 (Event)	触发时机	权限要求（满足任一）	事件类型	商店	自建
日历变更	当订阅用户的日历列表有日历变动时	获取日历、日程及忙闲信息更新日历及日程信息	calendar.calendar.changed_v4	✓	✓

资源：用户访问控制

查看资源字段及示例

方法列表

“商店”代表应用商店应用；“自建”代表企业自建应用

	方法 (API)	权限要求（满足任一）		访问凭证（选择其一）	商店	自建
创建访问控制`POST` /open-apis/calendar/v4/calendars/:calendar_id/acls以当前身份添加访问控制权限，即添加日历成员	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
删除访问控制`DELETE` /open-apis/calendar/v4/calendars/:calendar_id/acls/:acl_id以当前身份删除日历的控制权限，即删除日历成员	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
获取访问控制列表`GET` /open-apis/calendar/v4/calendars/:calendar_id/acls获取日历的控制权限列表，即日历成员列表	获取日历、日程及忙闲信息更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
订阅日历访问控制变更事件`POST` /open-apis/calendar/v4/calendars/:calendar_id/acls/subscription指定日历下的日历成员变更事件	获取日历、日程及忙闲信息更新日历及日程信息	user_access_token	✓	✓
取消订阅日历访问控制变更事件`POST` /open-apis/calendar/v4/calendars/:calendar_id/acls/unsubscription取消监听指定日历下的日历成员变更事件	获取日历、日程及忙闲信息更新日历及日程信息	user_access_token	✓	✓

事件列表

	事件 (Event)	触发时机	权限要求（满足任一）	事件类型	商店	自建
ACL新建	当被订阅的日历上有ACL被创建时	获取日历、日程及忙闲信息更新日历及日程信息	calendar.calendar.acl.created_v4	✓	✓
ACL移除	当被订阅的日历上有ACL被删除时	获取日历、日程及忙闲信息更新日历及日程信息	calendar.calendar.acl.deleted_v4	✓	✓

资源：日程

查看资源字段及示例

方法列表

“商店”代表应用商店应用；“自建”代表企业自建应用

	方法 (API)	权限要求（满足任一）		访问凭证（选择其一）	商店	自建
创建日程`POST` /open-apis/calendar/v4/calendars/:calendar_id/events在日历上创建一个日程	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
删除日程`DELETE` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id删除日历上的一个日程	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
获取日程`GET` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id获取日历上的一个日程信息	获取日历、日程及忙闲信息更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
获取日程列表`GET` /open-apis/calendar/v4/calendars/:calendar_id/events获取日历下的日程列表	获取日历、日程及忙闲信息更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
更新日程`PATCH` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id更新日历上的一个日程	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
搜索日程`POST` /open-apis/calendar/v4/calendars/:calendar_id/events/search以用户身份搜索某日历下的相关日程	获取日历、日程及忙闲信息更新日历及日程信息	user_access_token	✓	✓
订阅日程变更事件`POST` /open-apis/calendar/v4/calendars/:calendar_id/events/subscription以用户身份订阅指定日历下的日程变更事件	获取日历、日程及忙闲信息更新日历及日程信息	user_access_token	✓	✓
取消订阅日程变更事件`POST` /open-apis/calendar/v4/calendars/:calendar_id/events/unsubscription以用户身份取消订阅指定日历下的日程变更事件	获取日历、日程及忙闲信息更新日历及日程信息	user_access_token	✓	✓

事件列表

	事件 (Event)	触发时机	权限要求（满足任一）	事件类型	商店	自建
日程变更	当被订阅的用户日历下有日程变更时	获取日历、日程及忙闲信息更新日历及日程信息	calendar.calendar.event.changed_v4	✓	✓

资源：日程参与人

查看资源字段及示例

方法列表

“商店”代表应用商店应用；“自建”代表企业自建应用

	方法 (API)	权限要求（满足任一）		访问凭证（选择其一）	商店	自建
创建日程参与人`POST` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees批量给日程添加参与人	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
获取日程参与人列表`GET` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees获取日程的参与人列表	获取日历、日程及忙闲信息更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓
删除日程参与人`POST` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees/batch_delete批量删除日程的参与人	更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓

资源：日程参与人群成员

查看资源字段及示例

方法列表

“商店”代表应用商店应用；“自建”代表企业自建应用

	方法 (API)	权限要求（满足任一）		访问凭证（选择其一）	商店	自建
获取日程参与群成员列表`GET` /open-apis/calendar/v4/calendars/:calendar_id/events/:event_id/attendees/:attendee_id/chat_members获取日程的群参与人的群成员列表	获取日历、日程及忙闲信息更新日历及日程信息	tenant_access_tokenuser_access_token	✓	✓

资源：忙闲

查看资源字段及示例

方法列表

“商店”代表应用商店应用；“自建”代表企业自建应用

	方法 (API)	权限要求（满足任一）		访问凭证（选择其一）	商店	自建
查询忙闲`POST` /open-apis/calendar/v4/freebusy/list查询用户主日历或会议室的忙闲信息	获取日历、日程及忙闲信息更新日历及日程信息	tenant_access_token	✓	✓

资源：请假

查看资源字段及示例

方法列表

“商店”代表应用商店应用；“自建”代表企业自建应用

	方法 (API)	权限要求（满足任一）		访问凭证（选择其一）	商店	自建
创建请假日程`POST` /open-apis/calendar/v4/timeoff_events为指定用户创建一个请假日程	创建或删除请假日程	tenant_access_token	✓	✓
删除请假日程`DELETE` /open-apis/calendar/v4/timeoff_events/:timeoff_event_id删除一个指定的请假日程	创建或删除请假日程	tenant_access_token	✓	✓

资源：日历设置

查看资源字段及示例

方法列表

“商店”代表应用商店应用；“自建”代表企业自建应用

	方法 (API)	权限要求（满足任一）		访问凭证（选择其一）	商店	自建
生成CalDAV配置`POST` /open-apis/calendar/v4/settings/generate_caldav_conf为当前用户生成一个CalDAV账号密码	更新日历及日程信息生成 CalDAV 配置信息	user_access_token	✓	✓

资源：Exchange绑定

查看资源字段及示例

方法列表

“商店”代表应用商店应用；“自建”代表企业自建应用

	方法 (API)	权限要求（满足任一）		访问凭证（选择其一）	商店	自建
创建Exchange绑定关系`POST` /open-apis/calendar/v4/exchange_bindings将Exchange账户绑定到飞书账户	获取日历、日程及忙闲信息更新日历及日程信息	user_access_token	✓	✓
获取绑定状态`GET` /open-apis/calendar/v4/exchange_bindings/:exchange_binding_id获取Exchange账户的绑定状态	获取日历、日程及忙闲信息	user_access_token	✓	✓
解除Exchange绑定关系`DELETE` /open-apis/calendar/v4/exchange_bindings/:exchange_binding_id解除Exchange账户和飞书账户的绑定关系	更新日历及日程信息	user_access_token	✓	✓

修改于 2023-01-28 02:56:02

更新订阅状态