飞书开放平台 Server API 文档

主题

创建子任务 ​

给一个任务创建一个子任务。

接口功能除了额外需要输入父任务的GUID之外，和创建任务接口功能完全一致。

Tip: 创建子任务需要拥有父任务的编辑权限。详见任务是如何鉴权的？

如果将新任务加入清单，则需要清单的可编辑权限。详情见任务功能概述中的“任务是如何鉴权的？”章节。

请求 ​

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

请求头 ​

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

路径参数 ​

名称类型描述
task_guidstring父任务GUID
示例值："e297ddff-06ca-4166-b917-4ce57cd3a7a0"
数据校验规则：
- 最大长度：100 字符

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_id
默认值：open_id

请求体 ​

名称类型必填描述
summarystring是任务标题
示例值："针对全年销售进行一次复盘"
数据校验规则：
- 最大长度：10000 字符
descriptionstring否任务摘要
示例值："需要事先阅读复盘总结文档"
duedue否任务截止时间戳(ms)，截止时间戳和截止日期选择一个填写。
示例值：1675742789470
  └ timestampstring否截止时间/日期的时间戳，距1970-01-01 00:00:00的毫秒数。如果截止时间是一个日期，需要把日期转换成时间戳，并设置 is_all_day=true
示例值："1675454764000"
  └ is_all_dayboolean否是否截止到一个日期。如果设为true，timestamp中只有日期的部分会被解析和存储。
示例值：true
originorigin否任务关联的第三方平台来源信息。详见如何使用Origin?
  └ platform_i18n_namei18n_text否任务导入来源的名称，用于在任务中心详情页展示。需提供多语言版本。
    └ en_usstring否英文
示例值："workbench"
数据校验规则：
- 最大长度：1000 字符
    └ zh_cnstring否中文
示例值："工作台"
数据校验规则：
- 最大长度：1000 字符
    └ zh_hkstring否中文（香港地区）
示例值："工作臺"
数据校验规则：
- 最大长度：1000 字符
    └ zh_twstring否中文（台湾地区）
示例值："工作臺"
数据校验规则：
- 最大长度：1000 字符
    └ ja_jpstring否日语
示例值："作業台"
数据校验规则：
- 最大长度：1000 字符
    └ fr_frstring否法语
示例值："Table de travail"
    └ it_itstring否意大利语
示例值："banco di lavoro"
    └ de_destring否德语
示例值："Werkbank"
    └ ru_rustring否俄语
示例值："верстак"
    └ th_thstring否泰语
示例值："โต๊ะทำงาน"
    └ es_esstring否西班牙语
示例值："banco de trabajo"
    └ ko_krstring否韩语
示例值："작업대"
  └ hrefhref否任务关联的来源平台详情页链接
    └ urlstring否链接对应的地址
示例值："https://www.example.com"
数据校验规则：
- 长度范围：0 ～ 1024 字符
    └ titlestring否链接对应的标题
示例值："反馈一个问题，需要协助排查"
数据校验规则：
- 最大长度：512 字符
extrastring否调用者可以传入的任意附带到任务上的数据。在获取任务详情时会原样返回。
示例值："dGVzdA=="
数据校验规则：
- 最大长度：65536 字符
completed_atstring否任务的完成时刻时间戳(ms)
示例值："1675742789470"
默认值：0
数据校验规则：
- 最大长度：20 字符
membersmember\[\]否任务成员列表
示例值：[ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f]
数据校验规则：
- 最大长度：500
  └ idstring否表示member的id
示例值："ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f"
数据校验规则：
- 最大长度：100 字符
  └ typestring否成员的类型
示例值："user"
默认值：user
  └ rolestring否成员角色，支持"assignee"或者"follower"
示例值："assignee"
数据校验规则：
- 最大长度：20 字符
repeat_rulestring否如果设置，则该任务为“重复任务”。该字段表示了重复任务的重复规则。详见功能概述中的“如何使用重复任务？”章节。
示例值："FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
数据校验规则：
- 最大长度：1000 字符
custom_completecustom_complete否任务自定义完成规则。详见功能概述中的“如何使用自定义完成？”章节。
  └ pccustom_complete_item否pc客户端自定义完成配置（含mac和windows）
    └ hrefstring否自定义完成的跳转url
示例值："https://www.example.com"
    └ tipi18n_text否自定义完成的弹出提示为
      └ en_usstring否英文
示例值："workbench"
数据校验规则：
- 最大长度：1000 字符
      └ zh_cnstring否中文
示例值："工作台"
数据校验规则：
- 最大长度：1000 字符
      └ zh_hkstring否中文（香港地区）
示例值："工作臺"
数据校验规则：
- 最大长度：1000 字符
      └ zh_twstring否中文（台湾地区）
示例值："工作臺"
数据校验规则：
- 最大长度：1000 字符
      └ ja_jpstring否日语
示例值："作業台"
数据校验规则：
- 最大长度：1000 字符
      └ fr_frstring否法语
示例值："Table de travail"
      └ it_itstring否意大利语
示例值："banco di lavoro"
      └ de_destring否德语
示例值："Werkbank"
      └ ru_rustring否俄语
示例值："верстак"
      └ th_thstring否泰语
示例值："โต๊ะทำงาน"
      └ es_esstring否西班牙语
示例值："banco de trabajo"
      └ ko_krstring否韩语
示例值："작업대"
  └ ioscustom_complete_item否飞书ios端的自定义完成配置
    └ hrefstring否自定义完成的跳转url
示例值："https://www.example.com"
    └ tipi18n_text否自定义完成的弹出提示为
      └ en_usstring否英文
示例值："workbench"
数据校验规则：
- 最大长度：1000 字符
      └ zh_cnstring否中文
示例值："工作台"
数据校验规则：
- 最大长度：1000 字符
      └ zh_hkstring否中文（香港地区）
示例值："工作臺"
数据校验规则：
- 最大长度：1000 字符
      └ zh_twstring否中文（台湾地区）
示例值："工作臺"
数据校验规则：
- 最大长度：1000 字符
      └ ja_jpstring否日语
示例值："作業台"
数据校验规则：
- 最大长度：1000 字符
      └ fr_frstring否法语
示例值："Table de travail"
      └ it_itstring否意大利语
示例值："banco di lavoro"
      └ de_destring否德语
示例值："Werkbank"
      └ ru_rustring否俄语
示例值："верстак"
      └ th_thstring否泰语
示例值："โต๊ะทำงาน"
      └ es_esstring否西班牙语
示例值："banco de trabajo"
      └ ko_krstring否韩语
示例值："작업대"
  └ androidcustom_complete_item否飞书android端的自定义完成配置
    └ hrefstring否自定义完成的跳转url
示例值："https://www.example.com"
    └ tipi18n_text否自定义完成的弹出提示为
      └ en_usstring否英文
示例值："workbench"
数据校验规则：
- 最大长度：1000 字符
      └ zh_cnstring否中文
示例值："工作台"
数据校验规则：
- 最大长度：1000 字符
      └ zh_hkstring否中文（香港地区）
示例值："工作臺"
数据校验规则：
- 最大长度：1000 字符
      └ zh_twstring否中文（台湾地区）
示例值："工作臺"
数据校验规则：
- 最大长度：1000 字符
      └ ja_jpstring否日语
示例值："作業台"
数据校验规则：
- 最大长度：1000 字符
      └ fr_frstring否法语
示例值："Table de travail"
      └ it_itstring否意大利语
示例值："banco di lavoro"
      └ de_destring否德语
示例值："Werkbank"
      └ ru_rustring否俄语
示例值："верстак"
      └ th_thstring否泰语
示例值："โต๊ะทำงาน"
      └ es_esstring否西班牙语
示例值："banco de trabajo"
      └ ko_krstring否韩语
示例值："작업대"
taskliststask_in_tasklist_info\[\]否任务所在清单的信息。如果设置，则表示创建的任务要直接加入到指定清单。
  └ tasklist_guidstring否任务要加入的清单的GUID。
示例值："cc371766-6584-cf50-a222-c22cd9055004"
数据校验规则：
- 最大长度：100 字符
  └ section_guidstring否任务所在清单的自定义分组GUID。如果设置了清单GUID但没有设置自定义分组GUID，则自动加入该清单的默认分组。
示例值："e6e37dcc-f75a-5936-f589-12fb4b5c80c2"
client_tokenstring否幂等token。如果提供则触发后端实现幂等行为。详见功能概述中的“ 幂等调用 ”章节。
示例值："daa2237f-8310-4707-a83b-52c8a81e0fb7"
数据校验规则：
- 长度范围：10 ～ 100 字符
startstart否任务的开始时间(ms)
  └ timestampstring否开始时间/日期的时间戳，距1970-01-01 00:00:00的毫秒数。如果开始时间是一个日期，需要把日期转换成时间戳，并设置 is_all_day=true
示例值："1675454764000"
  └ is_all_dayboolean否是否开始于一个日期。如果设为true，timestamp中只有日期的部分会被解析和存储。
示例值：true
remindersreminder\[\]否任务提醒
  └ relative_fire_minuteint是相对于截止时间的提醒时间分钟数。例如30表示截止时间前30分钟提醒；0表示截止时提醒。
示例值：30

请求体示例 ​

json
{
    "summary": "针对全年销售进行一次复盘",
    "description": "需要事先阅读复盘总结文档",
    "due": {
        "timestamp": "1675454764000",
        "is_all_day": true
    },
    "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==",
    "completed_at": "1675742789470",
    "members": [
        {
            "id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
            "type": "user",
            "role": "assignee"
        }
    ],
    "repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR",
    "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": "작업대"
            }
        }
    },
    "tasklists": [
        {
            "tasklist_guid": "cc371766-6584-cf50-a222-c22cd9055004",
            "section_guid": "e6e37dcc-f75a-5936-f589-12fb4b5c80c2"
        }
    ],
    "client_token": "daa2237f-8310-4707-a83b-52c8a81e0fb7",
    "start": {
        "timestamp": "1675454764000",
        "is_all_day": true
    },
    "reminders": [
        {
            "relative_fire_minute": 30
        }
    ]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ subtasktask创建的任务
    └ guidstring任务guid，任务的唯一ID
    └ summarystring任务标题
    └ descriptionstring任务描述
    └ duedue任务截止时间
      └ timestampstring截止时间/日期的时间戳，距1970-01-01 00:00:00的毫秒数。如果截止时间是一个日期，需要把日期转换成时间戳，并设置 is_all_day=true
      └ is_all_dayboolean是否截止到一个日期。如果设为true，timestamp中只有日期的部分会被解析和存储。
    └ remindersreminder\[\]任务的提醒配置列表。目前每个任务最多有1个。
      └ idstring提醒时间设置的 ID
      └ relative_fire_minuteint相对于截止时间的提醒时间分钟数。例如30表示截止时间前30分钟提醒；0表示截止时提醒。
    └ 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任务的开始时间。
如果同时设置任务的开始时间和截止时间，开始时间必须<=截止时间，并且开始/截止时间的is_all_day设置必须相同。
      └ timestampstring开始时间/日期的时间戳，距1970-01-01 00:00:00 UTC的毫秒数。如果开始时间是一个日期，需要把日期转换成时间戳，并设置 is_all_day=true。
      └ is_all_dayboolean是否开始于一个日期。如果设为true，timestamp中只有日期的部分会被解析和存储。
    └ subtask_countint该任务的子任务的个数。

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "subtask": {
            "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": "类型"
                }
            ],
            "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
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001470400请求参数错误。例如没有输入任务标题。错误原因见返回的msg提示的信息。
4041470404父任务数据不存在或者已删除。确认父任务数据是否存在或已删除。
5001470500服务器错误。尝试重试调用。如持续失败，请联系支持人员进行反馈。
4031470403缺少父任务的编辑权限。检查调用身份是否有父任务的可编辑权限。详情见任务功能概述中的“任务是如何鉴权的？”章节。
5001470422使用相同的client_token并发调用接口。不要使用相同的client_token并发调用接口。

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

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