飞书开放平台 Server API 文档

主题

查询所有任务 ​

以分页的方式获取任务列表。当使用user_access_token时，获取与该用户身份相关的所有任务。当使用tenant_access_token时，获取以该应用身份通过“创建任务“接口创建的所有任务（并非获取该应用所在租户下所有用户创建的任务）。 本接口支持通过任务创建时间以及任务的完成状态对任务进行过滤。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/task/v1/tasks
HTTP MethodGET
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用task:task:readonly 查看任务详情
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

查询参数 ​

名称类型必填描述
page_sizeint否分页大小
示例值：10
数据校验规则：
- 最大值：100
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：MTYzMTg3ODUxNQ==
start_create_timestring否范围查询任务时，查询的起始时间。不填时默认起始时间为第一个任务的创建时间。
示例值：1652323331
end_create_timestring否范围查询任务时，查询的结束时间。不填时默认结束时间为最后一个任务的创建时间。
示例值：1652323335
task_completedboolean否可用于查询时过滤任务完成状态。true表示只返回已完成的任务，false表示只返回未完成的任务。不填时表示同时返回两种完成状态的任务。
示例值：false
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

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemstask\[\]任务列表
    └ idstring任务的唯一ID，例如"83912691-2e43-47fc-94a4-d512e03984fa"
    └ summarystring任务的标题，类型为文本字符串。 如果要在任务标题中插入 URL 或者 @某个用户，请使用rich_summary字段。 创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。
> Info: 任务标题和任务富文本标题同时存在时只使用富文本标题。
    └ descriptionstring任务的描述，类型为文本字符串。 如果要在任务描述中插入 URL 或者 @某个用户，请使用rich_description字段。
> Info: 任务备注和任务富文本备注同时存在时只使用富文本备注。
    └ complete_timestring任务的完成时间戳（单位为秒），完成时间为0则表示任务尚未完成。 不支持部分完成，只有整个任务完成，该字段才会有非0值。
    └ creator_idstring任务的创建者 ID。 其中查询字段 user_id_type 是用于控制返回体中 creator_id 的类型，不传时默认返回 open_id。 特别的，使用tenant_access_token 调用接口时，如果是user_id_type是openid，则返回代表该应用身份的openid；当user_id_type为user_id时，不返回creator_id。原因是user_id代表一个真实飞书用户的id，应用身份没有user_id。使用user_access_token调用接口正常返回创建者。
    └ extrastring附属信息。 接入方可以传入base64 编码后的自定义的数据。用户如果需要对当前任务备注信息，但对外不显示，可使用该字段进行存储。 该数据会在获取任务详情时，原样返回给用户。
    └ create_timestring任务的创建时间的Unix时间戳（单位为秒）
    └ update_timestring任务的更新时间的Unix时间戳（单位为秒） 创建任务时update_time与create_time相同
    └ duedue任务的截止时间设置
      └ timestring表示截止时间的Unix时间戳（单位为秒）。
      └ timezonestring截止时间对应的时区。 传入值需要符合IANA Time Zone Database标准，规范见Time Zone Database。
      └ is_all_dayboolean标记任务是否为全天任务。 包括如下取值： - true：表示是全天任务，全天任务的截止时间为当天 UTC 时间的 0 点。 - false：表示不是全天任务。
    └ originorigin任务关联的第三方平台来源信息
      └ platform_i18n_namestring任务来源的名称。 用于在任务中心详情页展示。需要提供一个字典，支持多种语言名称映射。应用在使用不同语言时，导入来源也将展示对应的内容。详细参见：任务字段补充说明
      └ hrefhref任务关联的来源平台详情页链接
        └ urlstring具体链接地址。 URL仅支持解析http、https。详细参见：任务字段补充说明
        └ titlestring链接对应的标题
    └ can_editboolean此字段用于控制该任务在飞书任务中心是否可编辑，默认为false
> Info: 已经废弃，向前兼容故仍然保留，但不推荐使用
    └ customstring自定义完成配置。 此字段用于设置完成任务时的页面跳转，或展示提示语。详细参见：任务字段补充说明
    └ sourceint任务创建的来源
可选值有：
- 0: 未知类型 - 1: 来源任务中心创建 - 2: 来源消息转任务 - 3: 来源云文档 - 4: 来源文档单品 - 5: 来源PANO - 6: 来源tenant_access_token创建的任务 - 7: 来源user_access_token创建的任务 - 8: 来源新版云文档
    └ followersfollower\[\]任务的关注者
      └ idstring任务关注人 ID
      └ id_liststring\[\]要删除的关注人ID列表
    └ collaboratorscollaborator\[\]任务的执行者
      └ idstring任务执行者的 ID。 传入的值为 user_id 或 open_id，由user_id_type 决定。user_id和open_id的获取可见文档如何获取不同的用户 ID。
> Info: 已经废弃，为了向前兼容早期只支持单次添加一个人的情况而保留，但不再推荐使用，建议使用id_list字段
      └ id_liststring\[\]执行者的用户ID列表。 传入的值为 user_id 或 open_id，由user_id_type 决定。user_id和open_id的获取可见文档如何获取不同的用户 ID。
    └ collaborator_idsstring\[\]创建任务时添加的执行者用户id列表。 传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：如何获取不同的用户 ID。
    └ follower_idsstring\[\]创建任务时添加的关注者用户id列表。 传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：如何获取不同的用户 ID。
    └ repeat_rulestring重复任务的规则表达式。 语法格式参见RRule语法规范 4.3.10小节
    └ rich_summarystring富文本任务标题。语法格式参见Markdown模块 。创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。
    └ rich_descriptionstring富文本任务备注。语法格式参见Markdown模块
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ has_moreboolean是否还有更多项

响应体示例 ​

json
{
    "code": 0,
    "data": {
        "has_more": true,
        "items": [
            {
                "can_edit": true,
                "collaborators": [
                    {
                        "id": "ou_842f5b9b4b8faa60570e9008acc9af1f"
                    }
                ],
                "complete_time": "1637119864",
                "create_time": "1637045612",
                "creator_id": "ou_5df8b925054285f7166bf8b6ff03341f",
                "custom": "",
                "description": "多吃水果，多运动，健康生活，快乐工作。",
                "due": {
                    "time": "1637137860",
                    "timezone": "Asia/Shanghai"
                },
                "extra": "dGVzdA==",
                "followers": [
                    {
                        "id": "ou_842f5b9b4b8faa60570e9008acc9af1f"
                    }
                ],
                "id": "11d42f77-cfa4-4833-a76e-ad778b081077",
                "origin": {
                    "href": {
                        "title": "反馈一个问题，需要协助排查",
                        "url": "https://support.feishu.com/internal/foo-bar"
                    },
                    "platform_i18n_name": "{\"en_us\":\"IT Workspace\",\"zh_cn\":\"IT 工作台\"}"
                },
                "source": 6,
                "summary": "少喝咖啡",
                "update_time": "1637119866"
            },
            {
                "collaborators": [
                    {
                        "id": "ou_842f5b9b4b8faa60570e9008acc9af1f"
                    }
                ],
                "complete_time": "1636965009",
                "create_time": "1632886899",
                "creator_id": "ou_5df8b925054285f7166bf8b6ff03341f",
                "custom": "",
                "description": "",
                "due": {
                    "time": "0",
                    "timezone": ""
                },
                "extra": "",
                "followers": [
                    {
                        "id": "ou_842f5b9b4b8faa60570e9008acc9af1f"
                    }
                ],
                "id": "692ec13b-613d-4d0b-818d-a34ae2cb1413",
                "origin": {
                    "href": {},
                    "platform_i18n_name": "null"
                },
                "source": 1,
                "summary": "多喝热水",
                "update_time": "1636965011",
                "repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
            }
        ],
        "page_token": "MTYzMTg3ODUxNQ=="
    },
    "msg": ""
}

错误码 ​

HTTP状态码错误码描述排查建议
4031470403The identity token is incorrect. It should be either user_access_token or tenant_access_token.发起请求方的身份token不正确，需要为UserAccessToken或TenantAccessToken其中一种
5001470605failed to get task list一般是系统内部错误造成的，可联系维护同学进行处理
4001470421page_size exceed 100分页大小超过最大值100，需要减小page_size的值
4001470422failed to parse page_token解析分页标识失败，需要检查分页标识是否合法

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

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