服务端 API/日历/日历常见问题 # 日历常见问题 本文汇总了使用日历 API 期间可能遇到的常见问题与解决方案。 ## 日历相关 ### Q：如何获取日历订阅列表？ 你可以调用[获取日历列表](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/list)，该接口获取到的日历为用户当前已经订阅的日历。 ### Q：Lark日历是否支持查询法定工作日、节假日安排？ Lark日历不提供法定工作日、节假日的查询功能。如果已知有对应内容的日历，则可以调用[搜索日历](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/search) 接口找到对应的日历，然后调用[获取日程列表](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/list)接口获取日程数据，并根据日程数据判断当日的安排。 ### Q：Lark客户端上绑定了三方日历 (Google、Exchange)，是否支持通过 API 操作解绑？ 目前仅支持 Exchange 账号的绑定、解绑操作，且需要租户超级管理员权限。Google 暂不支持。 ## 日程相关 ### Q：获取指定时间段内的所有日程时，单次调用未获取到完整数据，再次调用传入的 sync_token 不起作用是什么原因？ 在[获取日程列表](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/list)接口中，开始/结束时间参数（start_time/end_time）和增量同步标记参数（sync_token）不能同时使用。这两类参数代表了两种不同的同步方式： - 开始/结束时间参数（start_time/end_time） 用于获取指定时间段内的日程列表。例如，获取 2021-11-01 00:00:00 到 2021-11-02 00:00:00 期间所有的日程。 - 增量同步标记参数（sync_token） 通过日程版本号获取日程列表。每一次日程信息更新时都会同步更新版本号，使用 sync_token 可以获取指定版本号内后续发生变动的日程信息。 ### Q：能看见日程返回，但无法看见日程标题是什么原因？ 能否看到日程标题和以下权限参数相关。 - [创建日程](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/create)接口中的 `visibility` 参数，该参数用于指定日程的公开范围。取值范围： - `public`：公开，默认显示日程详情。 - `default`：默认权限，用户有 `reader` 权限可以查看详情。 - `private`：私密，即便用户有 `reader` 权限也不能查看详情。 - [创建访问控制](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-acl/create)中的 `role` 参数，该参数用于设置用户对日历的访问权限（可通过[查询日历信息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/get)中的 `role` 参数获取用户对日历的访问权限）。`role` 参数取值范围： - `unknown`：未知权限（即不考虑当前 `role`）。 - `free_busy_reader`：游客，只能看到忙碌/空闲信息。 - `reader`：订阅者，查看所有日程详情。 - `writer`：编辑者，创建及修改日程。 - `owner`：管理员，管理日历及共享设置。 - 当日程公开范围为 `public`，用户对当前日历无论为何种权限均可见标题。 - 当日程公开范围为 `private`，用户对当前日历为 `writer` 和 `owner` 时可见标题。 - 当日程公开范围为 `default`, 用户对当前日历为`reader`、`writer`和`owner`时可见标题。 ### Q：我为什么不能编辑日程标题或删除日程？ 当用户为日程参与人时，可以在自己的主日历上获取到日程，但并不代表有日程的编辑权限。相关文档： - 在[更新日程](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/patch)或[删除日程](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/delete)接口文档内阅读注意事项，了解什么情况下可以更新或删除日程。 - 如何判断当前用户对日历的权限，可调用[查询日历信息](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/get)接口。 - 如何判断当前用户是否为日程组织者，可参考本文的 **如何判断当前用户是否为日程组织者**。 ### Q：如何判断当前用户是否为日程组织者？ 目前可通过[获取日程参与人列表](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event-attendee/list)接口，查看参与人是否为日程的组织者。 1. 路径参数中的 `calendar_id` 需传入当前用户的主日历 ID。 2. 获取到参与人列表后，如果 `is_organizer: true` 的用户与当前用户身份匹配时，则表示当前用户为日程的组织者。 ### Q：重复性日程为什么只能获取到一个日程？ 重复性日程是通过日程 Rrule 字段表示重复规则的，详细定义可以参考 [RFC5545 协议](https://datatracker.ietf.org/doc/html/rfc5545)。例如，每天重复一次的日程对应 `RRULE: FREQ=DAILY;UNTIL=20220531T155959Z;INTERVAL=1`。 ### Q: 调用接口设置了日程颜色, 为什么不生效？ 调用接口设置的日程颜色（`color` 字段）, 仅对当前身份生效。如果需要改变其他人看到的日程颜色, 需要用对方的身份来修改。类似逻辑的字段还有 `reminder` （日程提醒）。 ## 参与人（含会议室）相关 ### Q：如何通过开放平台 OpenAPI 预定会议室？ 你需要在创建日程后，调用[添加日程参与人](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event-attendee/create)接口预定会议室，而不是创建日程时传入 `location` 字段。 调用[添加日程参与人](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event-attendee/create)接口预定会议室时，需要注意： - 如果调用接口时以应用身份进行预定，则需要上传 `operate_id` 字段，该字段用于指定会议室的联系人。 - 最终是否预定成功，取决于管理员是否在管理后台配置了会议室预定限制（包括审批、时间限制和范围限制），以及是否有其他用户在同一时间抢占会议室。 ### Q：预定会议室时没有日程冲突仍然预定失败是什么原因？ 可能有多种原因，包括但不限于： 1. 管理员在管理后台配置了 **会议室预定限制**。 - 会议室为审批会议室。因为 OpenAPI 未支持审批功能，所以当管理员在管理后台打开会议室审批开关后，用户发起会议室预定请求会失败。 - 会议室设置了时间范围限制。当管理员在管理后台开启了预定时间限制后，不满足时间限制会预定失败。例如：会议室每日预定时间范围为 08:00 ~ 23:00, 则当预定 03:00 ~ 04:00 时间段时会失败。 - 会议室设置了用户可预定范围限制。当管理员在管理后台设置了可预定范围后，如果当前用户并未在可预定范围内，则会预定失败。 ![image.png](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/6f5df3f6ebd168ac50c3a580e9521dab_wgqsHQZmm6.png?height=1262&lazyload=true&maxWidth=600&width=2072) 2. 并发预定会议室。其他用户先预定了当前会议室，因为两个请求间隔时间较短，会导致用户获取会议室忙闲时，出现会议室未被预定，但实际已被预定的情况。 ### Q: 预定会议室后, 为什么不能立刻知道是否预定成功？ 调用接口预定会议室是一个异步过程，并且可能涉及和其他用户的竞争抢占。因此，当提交预定会议室的操作后，需要等待几秒才会返回最终的预定状态。 ### Q：是否支持订阅参与人回复接受、拒绝等操作的日程变更事件？ 你可以订阅[日程变更事件](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/events/changed)，参与人点击接受、拒绝等操作带来的数据变更，包含在日程变更事件的范围内。 ## 错误码相关 ### Q：如何使用调用接口后返回的错误码？ 你可以在 OpenAPI 对应的帮助文档内，或者参见[通用错误码](https://open.larksuite.com/document/ukTMukTMukTM/ugjM14COyUjL4ITN)，查找相匹配的错误码，然后根据错误码说明与排查建议修复问题。