# 搜索日程

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

## 注意事项

适用于主日历和共享日历，且当前身份必须对日历有 reader、writer 或 owner 权限。你可以调用[查询日历信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/get)接口，获取当前身份对日历的访问权限。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/calendar/v4/calendars/:calendar_id/events/search
HTTP Method | POST
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用**<br>开启任一权限即可 | 更新日历及日程信息(calendar:calendar)<br>读取日程信息(calendar:calendar.event:read)<br>获取日历、日程及忙闲信息(calendar:calendar:readonly)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请<br>获取用户 user ID(contact:user.employee_id:readonly)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`<br>或<br>`user_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"

### 路径参数

名称 | 类型 | 描述
---|---|---
calendar_id | string | 日历 ID。关于日历 ID 可参见[日历 ID 说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/introduction)。<br>**示例值**："feishu.cn_xxxxxxxxxx@group.calendar.feishu.cn"

### 查询参数

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

### 请求体

名称 | 类型 | 必填 | 描述
---|---|---|---
query | string | 是 | 搜索关键字，用于模糊查询日程名称。<br>**注意**：如果日程名称包含下划线（_），则必须精准查询。该场景模糊查询可能无法搜索到日程。<br>**示例值**："query words"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `200` 字符
filter | event_search_filter | 否 | 搜索过滤器。
start_time | time_info | 否 | 搜索过滤项，日程搜索区间的开始时间。<br>**注意**：start_time 和 end_time 不传值时，默认搜索近一个月内的日程。
date | string | 否 | 以天为最小单位指定开始时间，[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) 格式，例如，2018-09-01。<br>**注意**：该参数不能与 `timestamp` 同时指定。<br>**示例值**："2018-09-01"
timestamp | string | 否 | 秒级时间戳，指具体的开始时间。例如，1602504000 表示 2020/10/12 20:00:00（UTC +8 时区）。<br>**注意**：该参数不能与 `date` 同时指定。<br>**示例值**："1602504000"
timezone | string | 否 | 时区。使用 IANA Time Zone Database 标准，例如 Asia/Shanghai。<br>- 全天时区固定为UTC +0<br>- 非全天时区默认为 Asia/Shanghai<br>**示例值**："Asia/Shanghai"
end_time | time_info | 否 | 搜索过滤项，日程搜索区间的结束时间。<br>**注意**：start_time 和 end_time 不传值时，默认搜索近一个月内的日程。
date | string | 否 | 以天为最小单位指定结束时间，[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) 格式，例如，2018-09-01。<br>**注意**：该参数不能与 `timestamp` 同时指定。<br>**示例值**："2018-09-01"
timestamp | string | 否 | 秒级时间戳，指具体的结束时间。例如，1602504000 表示 2020/10/12 20:00:00（UTC +8 时区）。<br>**注意**：该参数不能与 `date` 同时指定。<br>**示例值**："1602504000"
timezone | string | 否 | 时区。使用 IANA Time Zone Database 标准，例如 Asia/Shanghai。<br>- 全天时区固定为UTC +0<br>- 非全天时区默认为 Asia/Shanghai<br>**示例值**："Asia/Shanghai"
user_ids | string\[\] | 否 | 搜索过滤项，日程参与人的用户 ID 列表。设置该字段后，被搜索到的日程中至少包含其中一个参与人。<br>**注意**：用户 ID 类型和 user_id_type 的值保持一致，关于用户 ID 可参见[用户相关的 ID 概念](https://open.feishu.cn/document/home/user-identity-introduction/introduction)。<br>**默认值**：空，表示不设置该过滤项<br>**示例值**：["ou_e051986ab19f80d16b7b8d74f3f1235"]
room_ids | string\[\] | 否 | 搜索过滤项，会议室 ID 列表。设置该字段后，被搜索到的日程中至少包含其中一个会议室。<br>**默认值**：空，表示不设置该过滤项<br>**示例值**：["omm_eada1d61a550955240c28757e7dec3af"]
chat_ids | string\[\] | 否 | 搜索过滤项，群 ID 列表。设置该字段后，被搜索到的日程中至少包含其中一个群。关于群 ID 可参见[群 ID 说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-id-description)。<br>**默认值**：空，表示不设置该过滤项<br>**示例值**：["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"
        ]
    }
}
```

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
items | calendar.event\[\] | 搜索命中的日程列表。
event_id | string | 日程 ID。后续可通过该 ID 查询、更新或删除日程信息。更多信息可参见[日程 ID 说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/introduction)。
organizer_calendar_id | string | 日程组织者的日历 ID。关于日历 ID 可参见[日历 ID 说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/introduction)。
summary | string | 日程标题。
description | string | 日程描述。
start_time | time_info | 日程开始时间。
date | string | 开始时间，仅全天日程使用该字段，[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) 格式，例如，2018-09-01。
timestamp | string | 秒级时间戳，指日程具体的开始时间。例如，1602504000 表示 2020/10/12 20:00:00（UTC +8 时区）。
timezone | string | 时区。使用 IANA Time Zone Database 标准。
end_time | time_info | 日程结束时间。
date | string | 结束时间，仅全天日程使用该字段，[RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) 格式，例如，2018-09-01。
timestamp | string | 秒级时间戳，指日程具体的结束时间。例如，1602504000 表示 2020/10/12 20:00:00（UTC +8 时区）。
timezone | string | 时区。使用 IANA Time Zone Database 标准。
visibility | string | 日程公开范围。仅新建日程时对所有参与人生效，之后修改该属性仅对当前身份生效。<br>**可选值有**：<br>- default：默认权限，跟随日历权限，默认仅向他人显示是否“忙碌”<br>- public：公开，显示日程详情<br>- private：私密，仅自己可见详情
attendee_ability | string | 参与人权限。<br>**可选值有**：<br>- none：无法编辑日程、无法邀请其它参与人、无法查看参与人列表<br>- can_see_others：无法编辑日程、无法邀请其它参与人、可以查看参与人列表<br>- can_invite_others：无法编辑日程、可以邀请其它参与人、可以查看参与人列表<br>- can_modify_event：可以编辑日程、可以邀请其它参与人、可以查看参与人列表
free_busy_status | string | 日程占用的忙闲状态。仅新建日程时对所有参与人生效，之后修改该属性仅对当前身份生效。<br>**可选值有**：<br>- busy：忙碌<br>- free：空闲
location | event_location | 日程地点。
name | string | 地点名称。
address | string | 地点地址。
latitude | number(float) | 地点坐标纬度信息。<br>- 对于国内的地点，采用 GCJ-02 标准<br>- 对于海外的地点，采用 WGS84 标准
longitude | number(float) | 地点坐标经度信息。<br>- 对于国内的地点，采用 GCJ-02 标准<br>- 对于海外的地点，采用 WGS84 标准
color | int | 日程颜色，由颜色 RGB 值的 int32 表示。<br>**说明**：<br>- 仅对当前身份生效。<br>- 取值为 0 或 -1 时，表示默认跟随日历颜色。<br>- 客户端展示时会映射到色板上最接近的一种颜色。
reminders | reminder\[\] | 日程提醒列表。
minutes | int | 日程提醒时间的偏移量。该参数仅对当前身份生效。<br>- 正数时表示在日程开始前 X 分钟提醒。<br>- 负数时表示在日程开始后 X 分钟提醒。
recurrence | string | 重复日程的重复性规则，规则格式可参见 [rfc5545](https://datatracker.ietf.org/doc/html/rfc5545#section-3.3.10)。
status | string | 日程状态。<br>**可选值有**：<br>- tentative：未回应<br>- confirmed：已确认<br>- cancelled：日程已取消
is_exception | boolean | 日程是否是一个重复日程的例外日程。了解例外日程，可参见[例外日程](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar-event/introduction#71c5ec78)。
recurring_event_id | string | 例外日程对应的原重复日程的 event_id。
event_organizer | event_organizer | 日程组织者信息。
user_id | string | 日程组织者 user ID。
display_name | string | 日程组织者姓名。
app_link | string | 日程的 app_link，跳转到具体的某个日程。
attachments | attachment\[\] | 日程附件
file_token | string | 附件token
file_size | string | 附件大小
is_deleted | boolean | 是否删除附件
name | string | 附件名称
page_token | string | 分页标记，当 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状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 190002 | invalid parameters in request | 无效的请求参数。排查建议如下：<br>- 确认请求参数的字段名称、传参类型正确。<br>- 确认已经申请了相应资源的权限。<br>- 确认相应资源未被删除。
500 | 190003 | internal service error | 内部服务错误，请咨询[技术支持](https://applink.feishu.cn/TLJpeNdW)。
429 | 190004 | method rate limited | 方法频率限制。建议稍后再试，并适当减小请求 QPS。
429 | 190005 | app rate limited | 应用频率限制。建议稍后再试，并适当减小请求 QPS。
403 | 190006 | wrong unit for app tenant | 请求错误，检查应用 App ID 和 App Secret 是否正确。如仍无法解决请咨询[技术支持](https://applink.feishu.cn/TLJpeNdW)。
404 | 190007 | app bot_id not found | 应用的 bot_id 没有找到。你需要确保应用开启了[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)。如仍未解决请咨询[技术支持](https://applink.feishu.cn/TLJpeNdW)。
400 | 190008 | page_token or sync_token expired | page_token 或 sync_token 已过期。你需要置空 token 参数值，然后重试。
429 | 190010 | current operation rate limited | 当前操作被限流，原因一般为公用资源并发抢占失败。你可以适当降低当前操作频率，然后重试。
404 | 191000 | calendar not found | 日历没有找到。你需要检查并改为正确的日历 ID。
400 | 191001 | invalid calendar_id | calendar_id 无效。你需要检查并改为正确的日历 ID。
403 | 191002 | no calendar access_role | 当前身份没有日历的访问权限。如需查询某一日历信息，则需要确保当前身份拥有该日历的访问权限。
403 | 191003 | calendar is deleted | 日历已经被删除。你需要检查并改为正确的日历 ID。
403 | 191004 | invalid calendar type | 日历类型错误。你可以调用[查询日历信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/calendar-v4/calendar/get)接口获取日历类型信息，然后确保日历类型适用于当前接口。
400 | 193000 | invalid event_id | event_id 无效。你需要检查并改为正确的日程 ID。
404 | 193001 | event not found | 日程未找到。你需要确保传入了正确的日程 ID。
403 | 193002 | no permission to operate event | 无权限操作。你需要确保有日历以及日程的编辑权限。
403 | 193003 | event is deleted | 日程已经被删除。你需要检查并改为正确的日程 ID。
404 | 195100 | user is dismiss or not exist in the tenant | 当前身份或指定用户已经离职，或者不在该租户内。请检查并改为正确的身份来调用接口。

更多错误码信息，参见[通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)。