飞书开放平台 Server API 文档

主题

列取任务列表 ​

基于调用身份，列出特定类型的所有任务。支持分页。

目前只支持列取任务界面上“我负责的”任务。返回的任务数据按照任务在”我负责的“界面中”自定义拖拽“的顺序排序。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/task/v2/tasks
HTTP MethodGET
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可task:task:read 查看任务信息 task:task:write 查看、创建、更新、删除任务

请求头 ​

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

查询参数 ​

名称类型必填描述
page_sizeint否每页的任务数量
示例值：50
默认值：50
数据校验规则：
- 取值范围：1 ～ 100
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：aWQ9NzEwMjMzMjMxMDE=
completedboolean否是否按任务完成进行过滤。填写true表示只列出已完成任务；填写false表示只列出未完成任务。不填写表示不过滤。
示例值：true
typestring否列取任务的类型，目前只支持"my_tasks"，即“我负责的”。
示例值：my_tasks
默认值：my_tasks
user_id_typestring否用户 ID 类型
示例值：open_id
默认值：open_id

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ itemstask\[\]返回的任务列表
    └ guidstring任务guid，任务的唯一ID
    └ summarystring任务标题
    └ descriptionstring任务备注
    └ duedue任务截止时间
      └ timestampstring截止时间/日期的时间戳，距1970-01-01 00:00:00的毫秒数。
- 如果是截止日期（is_all_day 取值为 true），则该时间戳转换为具体时间后，只需精确到天。例如 1724284800000 转换为具体时间为 2024-08-22。 - 如果是截止时间（is_all_day 取值为 false），则该时间戳转换为具体时间后，精确到秒。例如 1724284800000 转换为具体时间为 2024-08-22 08:00:00 UTC+8。
      └ is_all_dayboolean是否截止到一个日期。可能值有：
- true：截止日期，timestamp 转换为具体时间后精确到天。 - false：截止时间，timestamp 转换为具体时间后精确到秒。
    └ remindersreminder\[\]任务的提醒配置列表。目前每个任务最多有1个。
      └ idstring提醒时间设置的 ID
      └ relative_fire_minuteint相对于截止时间的提醒时间分钟数。例如30表示截止时间前30分钟提醒；0表示截止时提醒。
注意：该参数值可能为负值。例如，在客户端创建的任务未设置具体截止时间，则该任务的截止时间默认为当天 00:00，如果任务提醒时间为当天 18:00，则 relative_fire_minute 返回值为 -1080。
    └ creatormember任务创建者
      └ idstring表示member的id
      └ typestring成员的类型
      └ rolestring成员角色
    └ membersmember\[\]任务成员列表
      └ idstring表示member的id
      └ typestring成员的类型
      └ rolestring成员角色
    └ completed_atstring任务完成的时间戳(ms)
    └ attachmentsattachment\[\]任务的附件列表
      └ guidstring附件guid
      └ file_tokenstring附件在云文档系统中的token
      └ namestring附件名
      └ sizeint附件的字节大小
      └ resourceresource附件归属的资源
        └ typestring资源类型
        └ idstring资源ID
      └ uploadermember附件上传者
        └ idstring表示member的id
        └ typestring成员的类型
        └ rolestring成员角色
      └ is_coverboolean是否是封面图
      └ uploaded_atstring上传时间戳(ms)
    └ originorigin任务关联的第三方平台来源信息。创建是设置后就不可更改。
      └ platform_i18n_namei18n_text任务导入来源的名称，用于在任务中心详情页展示。需提供多语言版本。
        └ en_usstring英文
        └ zh_cnstring中文
        └ zh_hkstring中文（香港地区）
        └ zh_twstring中文（台湾地区）
        └ ja_jpstring日语
        └ fr_frstring法语
        └ it_itstring意大利语
        └ de_destring德语
        └ ru_rustring俄语
        └ th_thstring泰语
        └ es_esstring西班牙语
        └ ko_krstring韩语
      └ hrefhref任务关联的来源平台详情页链接
        └ urlstring链接对应的地址
        └ titlestring链接对应的标题
    └ extrastring任务附带的自定义数据。
    └ taskliststask_in_tasklist_info\[\]任务所属清单的名字。调用者只能看到有权限访问的清单的列表。
      └ tasklist_guidstring任务所在清单的guid
      └ section_guidstring任务所在清单的自定义分组guid
    └ repeat_rulestring如果任务为重复任务，返回重复任务的配置
    └ parent_task_guidstring如果当前任务为某个任务的子任务，返回父任务的guid
    └ modeint任务的模式。1 - 会签任务；2 - 或签任务
    └ sourceint任务创建的来源
可选值有：
- 0: 未知来源 - 1: 任务中心 - 2: 群组任务/消息转任务 - 6: 通过开放平台以tenant_access_token授权创建的任务 - 7: 通过开放平台以user_access_token授权创建的任务 - 8: 文档任务
    └ custom_completecustom_complete任务的自定义完成配置
      └ pccustom_complete_itempc客户端自定义完成配置（含mac和windows）
        └ hrefstring自定义完成的跳转url
        └ tipi18n_text自定义完成的弹出提示为
          └ en_usstring英文
          └ zh_cnstring中文
          └ zh_hkstring中文（香港地区）
          └ zh_twstring中文（台湾地区）
          └ ja_jpstring日语
          └ fr_frstring法语
          └ it_itstring意大利语
          └ de_destring德语
          └ ru_rustring俄语
          └ th_thstring泰语
          └ es_esstring西班牙语
          └ ko_krstring韩语
      └ ioscustom_complete_itemios端的自定义完成配置
        └ hrefstring自定义完成的跳转url
        └ tipi18n_text自定义完成的弹出提示为
          └ en_usstring英文
          └ zh_cnstring中文
          └ zh_hkstring中文（香港地区）
          └ zh_twstring中文（台湾地区）
          └ ja_jpstring日语
          └ fr_frstring法语
          └ it_itstring意大利语
          └ de_destring德语
          └ ru_rustring俄语
          └ th_thstring泰语
          └ es_esstring西班牙语
          └ ko_krstring韩语
      └ androidcustom_complete_itemandroid端的自定义完成配置
        └ hrefstring自定义完成的跳转url
        └ tipi18n_text自定义完成的弹出提示为
          └ en_usstring英文
          └ zh_cnstring中文
          └ zh_hkstring中文（香港地区）
          └ zh_twstring中文（台湾地区）
          └ ja_jpstring日语
          └ fr_frstring法语
          └ it_itstring意大利语
          └ de_destring德语
          └ ru_rustring俄语
          └ th_thstring泰语
          └ es_esstring西班牙语
          └ ko_krstring韩语
    └ task_idstring任务界面上的代码
    └ created_atstring任务创建时间戳(ms)
    └ updated_atstring任务最后一次更新的时间戳(ms)
    └ statusstring任务的状态，支持"todo"和"done"两种状态
    └ urlstring任务的分享链接
    └ startstart任务的开始时间
      └ timestampstring开始时间/日期的时间戳，距1970-01-01 00:00:00的毫秒数。如果开始时间是一个日期，需要把日期转换成时间戳，并设置 is_all_day=true
      └ is_all_dayboolean是否开始于一个日期。如果设为true，timestamp中只有日期的部分会被解析和存储。
    └ subtask_countint该任务的子任务的个数。
    └ is_milestoneboolean是否是里程碑任务
    └ custom_fieldscustom_field_value\[\]任务的自定义字段值
      └ guidstring字段GUID
      └ typestring自定义字段类型，支持"member", "datetime", "number", "single_select", "multi_select"五种类型
      └ number_valuestring数字类型的自定义字段值，填写一个合法数字的字符串表示，空字符串表示设为空。
      └ datetime_valuestring日期类型自定义字段值。可以输入一个表示日期的以毫秒为单位的字符串。设为空字符串表示设为空。
      └ member_valuemember\[\]人员类型的自定义字段值，可以设置1个或多个用户的id（遵循member格式，只支持user类型）。当该字段的设置为“不能多选”时只能输入一个值。设为空数组表示设为空。
        └ idstring表示member的id
        └ typestring成员的类型
        └ rolestring成员角色
      └ single_select_valuestring单选类型字段值，填写一个字段选项的option_guid。设置为空字符串表示设为空。
      └ multi_select_valuestring\[\]多选类型字段值，可以填写一个或多个本字段的option_guid。设为空数组表示设为空。
      └ namestring自定义字段名
    └ dependenciestask_dependency\[\]任务依赖
      └ typestring依赖类型
可选值有：
- prev: 前置依赖 - next: 后置依赖
      └ task_guidstring依赖任务的GUID
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ has_moreboolean是否还有更多项

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "guid": "83912691-2e43-47fc-94a4-d512e03984fa",
                "summary": "进行销售年中总结",
                "description": "进行销售年中总结",
                "due": {
                    "timestamp": "1675454764000",
                    "is_all_day": true
                },
                "reminders": [
                    {
                        "id": "10",
                        "relative_fire_minute": 30
                    }
                ],
                "creator": {
                    "id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
                    "type": "user",
                    "role": "assignee"
                },
                "members": [
                    {
                        "id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
                        "type": "user",
                        "role": "editor"
                    }
                ],
                "completed_at": "1675742789470",
                "attachments": [
                    {
                        "guid": "f860de3e-6881-4ddd-9321-070f36d1af0b",
                        "file_token": "boxcnTDqPaRA6JbYnzQsZ2doB2b",
                        "name": "foo.jpg",
                        "size": 62232,
                        "resource": {
                            "type": "task",
                            "id": "e6e37dcc-f75a-5936-f589-12fb4b5c80c2"
                        },
                        "uploader": {
                            "id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
                            "type": "user",
                            "role": "assignee"
                        },
                        "is_cover": false,
                        "uploaded_at": "1675742789470"
                    }
                ],
                "origin": {
                    "platform_i18n_name": {
                        "en_us": "workbench",
                        "zh_cn": "工作台",
                        "zh_hk": "工作臺",
                        "zh_tw": "工作臺",
                        "ja_jp": "作業台",
                        "fr_fr": "Table de travail",
                        "it_it": "banco di lavoro",
                        "de_de": "Werkbank",
                        "ru_ru": "верстак",
                        "th_th": "โต๊ะทำงาน",
                        "es_es": "banco de trabajo",
                        "ko_kr": "작업대"
                    },
                    "href": {
                        "url": "https://www.example.com",
                        "title": "反馈一个问题，需要协助排查"
                    }
                },
                "extra": "dGVzdA==",
                "tasklists": [
                    {
                        "tasklist_guid": "cc371766-6584-cf50-a222-c22cd9055004",
                        "section_guid": "e6e37dcc-f75a-5936-f589-12fb4b5c80c2"
                    }
                ],
                "repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR",
                "parent_task_guid": "e297ddff-06ca-4166-b917-4ce57cd3a7a0",
                "mode": 2,
                "source": 6,
                "custom_complete": {
                    "pc": {
                        "href": "https://www.example.com",
                        "tip": {
                            "en_us": "workbench",
                            "zh_cn": "工作台",
                            "zh_hk": "工作臺",
                            "zh_tw": "工作臺",
                            "ja_jp": "作業台",
                            "fr_fr": "Table de travail",
                            "it_it": "banco di lavoro",
                            "de_de": "Werkbank",
                            "ru_ru": "верстак",
                            "th_th": "โต๊ะทำงาน",
                            "es_es": "banco de trabajo",
                            "ko_kr": "작업대"
                        }
                    },
                    "ios": {
                        "href": "https://www.example.com",
                        "tip": {
                            "en_us": "workbench",
                            "zh_cn": "工作台",
                            "zh_hk": "工作臺",
                            "zh_tw": "工作臺",
                            "ja_jp": "作業台",
                            "fr_fr": "Table de travail",
                            "it_it": "banco di lavoro",
                            "de_de": "Werkbank",
                            "ru_ru": "верстак",
                            "th_th": "โต๊ะทำงาน",
                            "es_es": "banco de trabajo",
                            "ko_kr": "작업대"
                        }
                    },
                    "android": {
                        "href": "https://www.example.com",
                        "tip": {
                            "en_us": "workbench",
                            "zh_cn": "工作台",
                            "zh_hk": "工作臺",
                            "zh_tw": "工作臺",
                            "ja_jp": "作業台",
                            "fr_fr": "Table de travail",
                            "it_it": "banco di lavoro",
                            "de_de": "Werkbank",
                            "ru_ru": "верстак",
                            "th_th": "โต๊ะทำงาน",
                            "es_es": "banco de trabajo",
                            "ko_kr": "작업대"
                        }
                    }
                },
                "task_id": "t6272302",
                "created_at": "1675742789470",
                "updated_at": "1675742789470",
                "status": "todo",
                "url": "https://applink.feishu.cn/client/todo/detail?guid=70577c8f-91ab-4c91-b359-a21a751054e8&suite_entity_num=t192012",
                "start": {
                    "timestamp": "1675454764000",
                    "is_all_day": true
                },
                "subtask_count": 1,
                "is_milestone": false,
                "custom_fields": [
                    {
                        "guid": "a4f648d7-76ef-477f-bc8e-0601b5a60093",
                        "type": "number",
                        "number_value": "10.23",
                        "datetime_value": "1687708260000",
                        "member_value": [
                            {
                                "id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
                                "type": "user",
                                "role": "editor"
                            }
                        ],
                        "single_select_value": "4216f79b-3fda-4dc6-a0c4-a16022e47152",
                        "multi_select_value": [
                            "4216f79b-3fda-4dc6-a0c4-a16022e47152"
                        ],
                        "name": "优先级"
                    }
                ],
                "dependencies": [
                    {
                        "type": "next",
                        "task_guid": "93b7bd05-35e6-4371-b3c9-6b7cbd7100c0"
                    }
                ]
            }
        ],
        "page_token": "aWQ9NzEwMjMzMjMxMDE=",
        "has_more": true
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001470400请求参数有误，比如page_size填写负数。错误原因见返回的msg提示的信息。
5001470500服务器错误。尝试重试调用。如持续失败，请联系支持人员进行反馈。

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

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