飞书开放平台 Server API 文档

主题

搜索日程 ​

调用该接口搜索指定日历下的相关日程，支持关键词搜索、过滤条件搜索。

注意事项 ​

适用于主日历和共享日历，且当前身份必须对日历有 reader、writer 或 owner 权限。你可以调用查询日历信息接口，获取当前身份对日历的访问权限。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/calendar/v4/calendars/:calendar_id/events/search
HTTP MethodPOST
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可calendar:calendar 更新日历及日程信息 calendar:calendar.event:read 读取日程信息 calendar:calendar:readonly 获取日历、日程及忙闲信息
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

路径参数 ​

名称类型描述
calendar_idstring日历 ID。关于日历 ID 可参见日历 ID 说明。
示例值："feishu.cn_xxxxxxxxxx@group.calendar.feishu.cn"

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：xxxxx
page_sizeint否一次调用所返回的最大日程数量。最小值为10，不足10取10。
示例值：10
默认值：20
数据校验规则：
- 最大值：100

请求体 ​

名称类型必填描述
querystring是搜索关键字，用于模糊查询日程名称。
注意：如果日程名称包含下划线（_），则必须精准查询。该场景模糊查询可能无法搜索到日程。
示例值："query words"
数据校验规则：
- 长度范围：0 ～ 200 字符
filterevent_search_filter否搜索过滤器。
  └ start_timetime_info否搜索过滤项，日程搜索区间的开始时间。
注意：start_time 和 end_time 不传值时，默认搜索近一个月内的日程。
    └ datestring否以天为最小单位指定开始时间，RFC 3339 格式，例如，2018-09-01。
注意：该参数不能与 timestamp 同时指定。
示例值："2018-09-01"
    └ timestampstring否秒级时间戳，指具体的开始时间。例如，1602504000 表示 2020/10/12 20:00:00（UTC +8 时区）。
注意：该参数不能与 date 同时指定。
示例值："1602504000"
    └ timezonestring否时区。使用 IANA Time Zone Database 标准，例如 Asia/Shanghai。
- 全天时区固定为UTC +0 - 非全天时区默认为 Asia/Shanghai
示例值："Asia/Shanghai"
  └ end_timetime_info否搜索过滤项，日程搜索区间的结束时间。
注意：start_time 和 end_time 不传值时，默认搜索近一个月内的日程。
    └ datestring否以天为最小单位指定结束时间，RFC 3339 格式，例如，2018-09-01。
注意：该参数不能与 timestamp 同时指定。
示例值："2018-09-01"
    └ timestampstring否秒级时间戳，指具体的结束时间。例如，1602504000 表示 2020/10/12 20:00:00（UTC +8 时区）。
注意：该参数不能与 date 同时指定。
示例值："1602504000"
    └ timezonestring否时区。使用 IANA Time Zone Database 标准，例如 Asia/Shanghai。
- 全天时区固定为UTC +0 - 非全天时区默认为 Asia/Shanghai
示例值："Asia/Shanghai"
  └ user_idsstring\[\]否搜索过滤项，日程参与人的用户 ID 列表。设置该字段后，被搜索到的日程中至少包含其中一个参与人。
注意：用户 ID 类型和 user_id_type 的值保持一致，关于用户 ID 可参见用户相关的 ID 概念。
默认值：空，表示不设置该过滤项
示例值：["ou_e051986ab19f80d16b7b8d74f3f1235"]
  └ room_idsstring\[\]否搜索过滤项，会议室 ID 列表。设置该字段后，被搜索到的日程中至少包含其中一个会议室。
默认值：空，表示不设置该过滤项
示例值：["omm_eada1d61a550955240c28757e7dec3af"]
  └ chat_idsstring\[\]否搜索过滤项，群 ID 列表。设置该字段后，被搜索到的日程中至少包含其中一个群。关于群 ID 可参见群 ID 说明。
默认值：空，表示不设置该过滤项
示例值：["oc_a0553eda9014c201e6969b478895c230"]

请求体示例 ​

json
{
    "query": "query words",
    "filter": {
        "start_time": {
            "date": "2018-09-01",
            "timestamp": "1602504000",
            "timezone": "Asia/Shanghai"
        },
        "end_time": {
            "date": "2018-09-01",
            "timestamp": "1602504000",
            "timezone": "Asia/Shanghai"
        },
        "user_ids": [
            "ou_e051986ab19f80d16b7b8d74f3f1235"
        ],
        "room_ids": [
            "omm_eada1d61a550955240c28757e7dec3af"
        ],
        "chat_ids": [
            "oc_a0553eda9014c201e6969b478895c230"
        ]
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemscalendar.event\[\]搜索命中的日程列表。
    └ event_idstring日程 ID。后续可通过该 ID 查询、更新或删除日程信息。更多信息可参见日程 ID 说明。
    └ organizer_calendar_idstring日程组织者的日历 ID。关于日历 ID 可参见日历 ID 说明。
    └ summarystring日程标题。
    └ descriptionstring日程描述。
    └ start_timetime_info日程开始时间。
      └ datestring开始时间，仅全天日程使用该字段，RFC 3339 格式，例如，2018-09-01。
      └ timestampstring秒级时间戳，指日程具体的开始时间。例如，1602504000 表示 2020/10/12 20:00:00（UTC +8 时区）。
      └ timezonestring时区。使用 IANA Time Zone Database 标准。
    └ end_timetime_info日程结束时间。
      └ datestring结束时间，仅全天日程使用该字段，RFC 3339 格式，例如，2018-09-01。
      └ timestampstring秒级时间戳，指日程具体的结束时间。例如，1602504000 表示 2020/10/12 20:00:00（UTC +8 时区）。
      └ timezonestring时区。使用 IANA Time Zone Database 标准。
    └ visibilitystring日程公开范围。仅新建日程时对所有参与人生效，之后修改该属性仅对当前身份生效。
可选值有：
- default: 默认权限，跟随日历权限，默认仅向他人显示是否“忙碌” - public: 公开，显示日程详情 - private: 私密，仅自己可见详情
    └ attendee_abilitystring参与人权限。
可选值有：
- none: 无法编辑日程、无法邀请其它参与人、无法查看参与人列表 - can_see_others: 无法编辑日程、无法邀请其它参与人、可以查看参与人列表 - can_invite_others: 无法编辑日程、可以邀请其它参与人、可以查看参与人列表 - can_modify_event: 可以编辑日程、可以邀请其它参与人、可以查看参与人列表
    └ free_busy_statusstring日程占用的忙闲状态。仅新建日程时对所有参与人生效，之后修改该属性仅对当前身份生效。
可选值有：
- busy: 忙碌 - free: 空闲
    └ locationevent_location日程地点。
      └ namestring地点名称。
      └ addressstring地点地址。
      └ latitudenumber(float)地点坐标纬度信息。 - 对于国内的地点，采用 GCJ-02 标准 - 对于海外的地点，采用 WGS84 标准
      └ longitudenumber(float)地点坐标经度信息。 - 对于国内的地点，采用 GCJ-02 标准 - 对于海外的地点，采用 WGS84 标准
    └ colorint日程颜色，由颜色 RGB 值的 int32 表示。
说明： - 仅对当前身份生效。 - 取值为 0 或 -1 时，表示默认跟随日历颜色。 - 客户端展示时会映射到色板上最接近的一种颜色。
    └ remindersreminder\[\]日程提醒列表。
      └ minutesint日程提醒时间的偏移量。该参数仅对当前身份生效。
- 正数时表示在日程开始前 X 分钟提醒。 - 负数时表示在日程开始后 X 分钟提醒。
    └ recurrencestring重复日程的重复性规则，规则格式可参见 rfc5545。
    └ statusstring日程状态。
可选值有：
- tentative: 未回应 - confirmed: 已确认 - cancelled: 日程已取消
    └ is_exceptionboolean日程是否是一个重复日程的例外日程。了解例外日程，可参见例外日程。
    └ recurring_event_idstring例外日程对应的原重复日程的 event_id。
    └ event_organizerevent_organizer日程组织者信息。
      └ user_idstring日程组织者 user ID。
      └ display_namestring日程组织者姓名。
    └ app_linkstring日程的 app_link，跳转到具体的某个日程。
    └ attachmentsattachment\[\]日程附件
      └ file_tokenstring附件token
      └ file_sizestring附件大小
      └ is_deletedboolean是否删除附件
      └ namestring附件名称
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "event_id": "00592a0e-7edf-4678-bc9d-1b77383ef08e_0",
                "organizer_calendar_id": "feishu.cn_xxxxxxxxxx@group.calendar.feishu.cn",
                "summary": "日程标题",
                "description": "日程描述",
                "start_time": {
                    "date": "2018-09-01",
                    "timestamp": "1602504000",
                    "timezone": "Asia/Shanghai"
                },
                "end_time": {
                    "date": "2018-09-01",
                    "timestamp": "1602504000",
                    "timezone": "Asia/Shanghai"
                },
                "visibility": "default",
                "attendee_ability": "can_see_others",
                "free_busy_status": "busy",
                "location": {
                    "name": "地点名称",
                    "address": "地点地址",
                    "latitude": 1.100000023841858,
                    "longitude": 2.200000047683716
                },
                "color": -1,
                "reminders": [
                    {
                        "minutes": 5
                    }
                ],
                "recurrence": "FREQ=DAILY;INTERVAL=1",
                "status": "confirmed",
                "is_exception": false,
                "recurring_event_id": "1cd45aaa-fa70-4195-80b7-c93b2e208f45",
                "event_organizer": {
                    "user_id": "ou_xxxxxx",
                    "display_name": "孙二二"
                },
                "app_link": "https://applink.larkoffice.com/client/calendar/event/detail?calendarId=7039673579105026066&key=aeac9c56-aeb1-4179-a21b-02f278f59048&originalTime=0&startTime=1700496000",
                "attachments": [
                    {
                        "file_token": "xAAAAA",
                        "file_size": "2345",
                        "is_deleted": true,
                        "name": "附件.jpeg"
                    }
                ]
            }
        ],
        "page_token": "xxxxx"
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
400190002invalid parameters in request无效的请求参数。排查建议如下： - 确认请求参数的字段名称、传参类型正确。 - 确认已经申请了相应资源的权限。 - 确认相应资源未被删除。
500190003internal service error内部服务错误，请咨询技术支持。
429190004method rate limited方法频率限制。建议稍后再试，并适当减小请求 QPS。
429190005app rate limited应用频率限制。建议稍后再试，并适当减小请求 QPS。
403190006wrong unit for app tenant请求错误，检查应用 App ID 和 App Secret 是否正确。如仍无法解决请咨询技术支持。
404190007app bot_id not found应用的 bot_id 没有找到。你需要确保应用开启了机器人能力。如仍未解决请咨询技术支持。
400190008page_token or sync_token expiredpage_token 或 sync_token 已过期。你需要置空 token 参数值，然后重试。
429190010current operation rate limited当前操作被限流，原因一般为公用资源并发抢占失败。你可以适当降低当前操作频率，然后重试。
404191000calendar not found日历没有找到。你需要检查并改为正确的日历 ID。
400191001invalid calendar_idcalendar_id 无效。你需要检查并改为正确的日历 ID。
403191002no calendar access_role当前身份没有日历的访问权限。如需查询某一日历信息，则需要确保当前身份拥有该日历的访问权限。
403191003calendar is deleted日历已经被删除。你需要检查并改为正确的日历 ID。
403191004invalid calendar type日历类型错误。你可以调用查询日历信息接口获取日历类型信息，然后确保日历类型适用于当前接口。
400193000invalid event_idevent_id 无效。你需要检查并改为正确的日程 ID。
404193001event not found日程未找到。你需要确保传入了正确的日程 ID。
403193002no permission to operate event无权限操作。你需要确保有日历以及日程的编辑权限。
403193003event is deleted日程已经被删除。你需要检查并改为正确的日程 ID。
404195100user is dismiss or not exist in the tenant当前身份或指定用户已经离职，或者不在该租户内。请检查并改为正确的身份来调用接口。

更多错误码信息，参见通用错误码。

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

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