飞书开放平台 Server API 文档

主题

日历概述 ​

日历 API 基于飞书日历功能开放了对日历、日程、忙闲等资源的操作与查询能力。你能以应用或用户的身份调用日历 API 来实现多种功能。例如：

  • 创建日程并预定会议室
  • 邀请飞书用户或第三方用户参与日程
  • 查看用户忙闲
  • 同步用户的休假状态
  • 绑定或解绑 Exchange 账户

客户案例 ​

开放平台包含日历业务的集成方案：

接入流程 ​

日历 API 的基本接入流程如下图所示，如需了解详细的 API 接入流程，参见流程概述。

image.png

开发教程 ​

体验场景化示例教程，了解如何搭配使用日历 API 来实现日历日程管理。

使用限制 ​

  • 单个用户或者单个应用可订阅的日历数量上限为 1000。
  • 每个日程可添加的参与人数量上限为 3000。

资源介绍 ​

日历业务域以资源为中心进行开放。日历是一个用于聚合日程的实体，用户在订阅日历后，可以在日历内创建日程并邀请参与人。资源关系图如下：

image.png

日历业务域包含的资源以及资源定义如下表：

资源定义
日历日历是包含一系列相关日程的容器，是同一类日程的聚合实体。
日历访问控制日历的成员列表，可以给不同成员授予不同的日历操作权限。
日程日程包含一个确定的日期或者时间范围，是会议预定的基本实体，分为普通日程和重复性日程。 此外，还存在以下类型的日程： - 例外日程：重复性日程中的某一个日程被修改后，与其他重复日程产生了区别，则称该日程为例外日程。 - 请假日程：一种特殊日程，在用户请假时，会在日历上显示请假日程。
日程参与人参与日程的对象，包括用户、群组、邮箱和会议室。 > Tip: 说明：日程添加会议室的方式，也是通过添加参与人进行的。
日程参与人群成员参与日程的群成员。
忙闲日历在某一时间段内的忙碌、空闲信息。
请假给用户创建某一日期或者时间段的休假日程。
日历设置给指定设备生成一个 CalDAV 账号密码，用于将客户端日历信息同步到本地设备日历。
Exchange 绑定与解绑完成 Exchange 账户到客户端账户的绑定或解绑。

在飞书客户端中日历资源如下：

  • 图中①区域展示了用户日历，包括用户管理的日历和订阅的日历。
  • 图中②区域展示了当前日历时间段内的日程忙闲信息。选中某一日程后，可以查看日程的内容、参与人、会议室等详细信息。

image.png

方法列表 ​

以下提供了日历业务域内所有资源的 API 和事件列表。

Note 文中表格涉及的 商店 是指商店应用，自建 是指企业自建应用。应用类型说明参见应用类型简介。

日历 ​

API 列表 ​

方法 (API)权限要求（满足任一）访问凭证（选择其一）商店自建
[获取主日历](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/primary) POST/open-apis/calendar/v4/calendars/primary > 获取用户的主日历实体信息 tenant_access_token user_access_token✓✓
[创建日历](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/create) POST /open-apis/calendar/v4/calendars > 以当前身份创建一个日历实体tenant_access_token user_access_token✓✓
[删除日历](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/delete) DELETE /open-apis/calendar/v4/calendars/:calendar_id > 以当前身份去删除指定日历实体tenant_access_token user_access_token✓✓
[获取日历](https://open.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/events/changed)当订阅用户的日历列表有日历变动时calendar:calendar:readonly 获取日历、日程及忙闲信息 calendar:calendar 更新日历及日程信息calendar.calendar.changed_v4✓✓

日历访问控制 ​

API 列表 ​

方法 (API)权限要求（满足任一）访问凭证（选择其一）商店自建
[创建访问控制](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/create) POST/open-apis/calendar/v4/calendars/:calendar_id/acls > 以当前身份添加访问控制权限，即添加日历成员 tenant_access_token user_access_token✓✓
[删除访问控制](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/delete) DELETE/open-apis/calendar/v4/calendars/:calendar_id/acls/:acl_id > 以当前身份删除日历的控制权限，即删除日历成员 tenant_access_token user_access_token✓✓
[获取访问控制列表](https://open.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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)触发时机权限要求（满足任一）事件类型商店自建
[ACL 新建](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/events/created)当被订阅的日历上有 ACL 被创建时calendar:calendar:readonly 获取日历、日程及忙闲信息 calendar:calendar 更新日历及日程信息calendar.calendar.acl.created_v4✓✓
[ACL 移除](https://open.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/events/changed)当被订阅的用户日历下有日程变更时calendar:calendar:readonly 获取日历、日程及忙闲信息 calendar:calendar 更新日历及日程信息calendar.calendar.event.changed_v4✓✓

日程参与人 ​

API 列表 ​

方法 (API)权限要求（满足任一）访问凭证（选择其一）商店自建
[创建日程参与人](https://open.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/timeoff_event/create) POST/open-apis/calendar/v4/timeoff_events > 为指定用户创建一个请假日程 calendar:timeoff 创建或删除请假日程tenant_access_token✓✓
[删除请假日程](https://open.larkoffice.com/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)权限要求（满足任一）访问凭证（选择其一）商店自建
[生成 CalDAV 配置](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/setting/generate_caldav_conf) POST/open-apis/calendar/v4/settings/generate_caldav_conf > 为当前用户生成一个 CalDAV 账号密码 calendar:calendar 更新日历及日程信息 calendar:setting:generate_caldav_conf 生成 CalDAV 配置信息user_access_token✓✓

Exchange 绑定与解绑 ​

API 列表 ​

方法 (API)权限要求（满足任一）访问凭证（选择其一）商店自建
[创建 Exchange 绑定关系](https://open.larkoffice.com/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.larkoffice.com/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.larkoffice.com/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✓✓

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有