# 创建任务

该接口可以创建一个任务，支持填写任务的基本信息，包括任务的标题，描述及协作者等。
在此基础上，创建任务时可以设置截止时间和重复规则，将任务设置为定期执行的重复任务。通过添加协作者，则可以让其他用户协同完成该任务。
此外，接口也提供了一些支持自定义内容的字段，调用方可以实现定制化效果，如完成任务后跳转到指定结束界面。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/task/v1/tasks
HTTP Method | POST
接口频率限制 | [100 次/分钟](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 查看、创建、编辑和删除任务（旧版）(task:task)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请<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"

### 查询参数

名称 | 类型 | 必填 | 描述
---|---|---|---
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)

### 请求体

名称 | 类型 | 必填 | 描述
---|---|---|---
summary | string | 否 | 任务的标题，类型为文本字符串。<br>如果要在任务标题中插入 URL 或者 @某个用户，请使用rich_summary字段。<br>创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。<br>**注意事项**：**示例值**："完成本季度OKR编写"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `1000` 字符
description | string | 否 | 任务的描述，类型为文本字符串。<br>如果要在任务描述中插入 URL 或者 @某个用户，请使用rich_description字段。<br><md-alert><br>任务备注和任务富文本备注同时存在时只使用富文本备注。<br>**示例值**："对本次会议内容复盘总结，编写更新本季度OKR"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `65536` 字符
extra | string | 否 | 附属信息。<br>接入方可以传入base64 编码后的自定义的数据。用户如果需要对当前任务备注信息，但对外不显示，可使用该字段进行存储。<br>该数据会在获取任务详情时，原样返回给用户。<br>**示例值**："dGVzdA=="<br>**数据校验规则**：<br>- 长度范围：`0` ～ `65536` 字符
due | due | 否 | 任务的截止时间设置
time | string | 否 | 表示截止时间的Unix时间戳（单位为秒）。<br>**示例值**："1623124318"
timezone | string | 否 | 截止时间对应的时区。<br>传入值需要符合IANA Time Zone Database标准，规范见[Time Zone Database](https://www.iana.org/time-zones)。<br>**示例值**："Asia/Shanghai"<br>**默认值**：`Asia/Shanghai`
is_all_day | boolean | 否 | 标记任务是否为全天任务。<br>包括如下取值：<br>- true：表示是全天任务，全天任务的截止时间为当天 UTC 时间的 0 点。<br>- false：表示不是全天任务。<br>**示例值**：false<br>**默认值**：`false`
origin | origin | 是 | 任务关联的第三方平台来源信息
platform_i18n_name | string | 是 | 任务来源的名称。<br>用于在任务中心详情页展示。需要提供一个字典，支持多种语言名称映射。应用在使用不同语言时，导入来源也将展示对应的内容。详细参见：[任务字段补充说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)<br>**示例值**："{\"zh_cn\": \"IT 工作台\", \"en_us\": \"IT Workspace\"}"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `1024` 字符
href | href | 否 | 任务关联的来源平台详情页链接
url | string | 否 | 具体链接地址。<br>URL仅支持解析http、https。详细参见：[任务字段补充说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)<br>**示例值**："https://support.feishu.com/internal/foo-bar"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `1024` 字符
title | string | 否 | 链接对应的标题<br>**示例值**："反馈一个问题，需要协助排查"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `512` 字符
can_edit | boolean | 否 | 此字段用于控制该任务在飞书任务中心是否可编辑，默认为false<br>**注意事项**：**示例值**：true<br>**默认值**：`false`
custom | string | 否 | 自定义完成配置。<br>此字段用于设置完成任务时的页面跳转，或展示提示语。详细参见：[任务字段补充说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)<br>**示例值**："{\"custom_complete\":{\"android\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"ios\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"pc\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}}}}"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `65536` 字符
collaborator_ids | string\[\] | 否 | 创建任务时添加的执行者用户id列表。<br>传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：[如何获取不同的用户 ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)。<br>**示例值**：["ou_49dadcd6fd55da971d887087c4f3a37a"]<br>**数据校验规则**：<br>- 最大长度：`100`
follower_ids | string\[\] | 否 | 创建任务时添加的关注者用户id列表。<br>传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：[如何获取不同的用户 ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)。<br>**示例值**：["ou_49dadcd6fd55da971d887087c4f3a37a"]<br>**数据校验规则**：<br>- 最大长度：`100`
repeat_rule | string | 否 | 重复任务的规则表达式。<br>语法格式参见[RRule语法规范](https://www.ietf.org/rfc/rfc2445.txt) 4.3.10小节<br>**示例值**："FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
rich_summary | string | 否 | 富文本任务标题。语法格式参见[Markdown模块](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)<br>。创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。<br>**示例值**："完成本季度OKR编写\[飞书开放平台](https://open.feishu.cn/)"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `1000` 字符
rich_description | string | 否 | 富文本任务备注。语法格式参见[Markdown模块](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)<br>**示例值**："对本次会议内容复盘总结，编写更新本季度OKR\[飞书开放平台](https://open.feishu.cn/)"<br>**数据校验规则**：<br>- 长度范围：`0` ～ `65536` 字符

### 请求体示例
```json
{
    "summary": "每天喝八杯水，保持身心愉悦",
    "description": "多吃水果，多运动，健康生活，快乐工作。",
    "rich_summary": "富文本标题[飞书开放平台](https://open.feishu.cn)",
    "rich_description": "富文本备注[飞书开放平台](https://open.feishu.cn)",
    "extra": "dGVzdA==",
    "due": {
        "time": "1623124318",
        "timezone": "Asia/Shanghai",
        "is_all_day": false
    },
    "origin": {
        "platform_i18n_name": "{\"zh_cn\": \"IT 工作台\", \"en_us\": \"IT Workspace\"}",
        "href": {
            "url": "https://support.feishu.com/internal/foo-bar",
            "title": "反馈一个问题，需要协助排查"
        }
    },
    "can_edit":true,
    "custom": "{\"custom_complete\":{\"android\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"ios\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"pc\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}}}}",
    "follower_ids": ["ou_13585843f02bc94923ed17a007cbc9b1", "ou_219a0611de2a639aa939ee97013f37a5"],
    "collaborator_ids": ["ou_13585843f02bc94923ed17a007cbc9b1", "ou_219a0611de2a639aa939ee97013f37a5"],
    "repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
}
```

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
task | task | 返回创建好的任务
id | string | 任务的唯一ID，例如"83912691-2e43-47fc-94a4-d512e03984fa"
summary | string | 任务的标题，类型为文本字符串。<br>如果要在任务标题中插入 URL 或者 @某个用户，请使用rich_summary字段。<br>创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。<br><md-alert><br>任务标题和任务富文本标题同时存在时只使用富文本标题。
description | string | 任务的描述，类型为文本字符串。<br>如果要在任务描述中插入 URL 或者 @某个用户，请使用rich_description字段。<br>**注意事项**：
complete_time | string | 任务的完成时间戳（单位为秒），完成时间为0则表示任务尚未完成。<br>不支持部分完成，只有整个任务完成，该字段才会有非0值。
creator_id | string | 任务的创建者 ID。<br>其中查询字段 user_id_type 是用于控制返回体中 creator_id 的类型，不传时默认返回 open_id。<br>特别的，使用tenant_access_token 调用接口时，如果是user_id_type是openid，则返回代表该应用身份的openid；当user_id_type为user_id时，不返回creator_id。原因是user_id代表一个真实飞书用户的id，应用身份没有user_id。使用user_access_token调用接口正常返回创建者。
extra | string | 附属信息。<br>接入方可以传入base64 编码后的自定义的数据。用户如果需要对当前任务备注信息，但对外不显示，可使用该字段进行存储。<br>该数据会在获取任务详情时，原样返回给用户。
create_time | string | 任务的创建时间的Unix时间戳（单位为秒）
update_time | string | 任务的更新时间的Unix时间戳（单位为秒）<br>创建任务时update_time与create_time相同
due | due | 任务的截止时间设置
time | string | 表示截止时间的Unix时间戳（单位为秒）。
timezone | string | 截止时间对应的时区。<br>传入值需要符合IANA Time Zone Database标准，规范见[Time Zone Database](https://www.iana.org/time-zones)。
is_all_day | boolean | 标记任务是否为全天任务。<br>包括如下取值：<br>- true：表示是全天任务，全天任务的截止时间为当天 UTC 时间的 0 点。<br>- false：表示不是全天任务。
origin | origin | 任务关联的第三方平台来源信息
platform_i18n_name | string | 任务来源的名称。<br>用于在任务中心详情页展示。需要提供一个字典，支持多种语言名称映射。应用在使用不同语言时，导入来源也将展示对应的内容。详细参见：[任务字段补充说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)
href | href | 任务关联的来源平台详情页链接
url | string | 具体链接地址。<br>URL仅支持解析http、https。详细参见：[任务字段补充说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)
title | string | 链接对应的标题
custom | string | 自定义完成配置。<br>此字段用于设置完成任务时的页面跳转，或展示提示语。详细参见：[任务字段补充说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/Supplementary-directions-of-task-fields)
source | int | 任务创建的来源<br>**可选值有**：<br>- 0：未知类型<br>- 1：来源任务中心创建<br>- 2：来源消息转任务<br>- 3：来源云文档<br>- 4：来源文档单品<br>- 5：来源PANO<br>- 6：来源tenant_access_token创建的任务<br>- 7：来源user_access_token创建的任务<br>- 8：来源新版云文档
followers | follower\[\] | 任务的关注者
id | string | 任务关注人 ID
id_list | string\[\] | 要删除的关注人ID列表
collaborators | collaborator\[\] | 任务的执行者
id | string | 任务执行者的 ID。<br>传入的值为 user_id 或 open_id，由user_id_type 决定。user_id和open_id的获取可见文档[如何获取不同的用户 ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)。<br><md-alert><br>已经废弃，为了向前兼容早期只支持单次添加一个人的情况而保留，但不再推荐使用，建议使用id_list字段
id_list | string\[\] | 执行者的用户ID列表。<br>传入的值为 user_id 或 open_id，由user_id_type 决定。user_id和open_id的获取可见文档[如何获取不同的用户 ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)。
collaborator_ids | string\[\] | 创建任务时添加的执行者用户id列表。<br>传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：[如何获取不同的用户 ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)。
follower_ids | string\[\] | 创建任务时添加的关注者用户id列表。<br>传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：[如何获取不同的用户 ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id)。
repeat_rule | string | 重复任务的规则表达式。<br>语法格式参见[RRule语法规范](https://www.ietf.org/rfc/rfc2445.txt) 4.3.10小节
rich_summary | string | 富文本任务标题。语法格式参见[Markdown模块](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)<br>。创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。
rich_description | string | 富文本任务备注。语法格式参见[Markdown模块](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)

### 响应体示例
```json
{
    "code": 0,
    "data": {
        "task": {
            "can_edit": true,
            "complete_time": "0",
            "create_time": "1630304148",
            "creator_id": "ou_05b67908bc5d12a086e909a076f7f1b6",
            "description": "多吃水果，多运动，健康生活，快乐工作。",
            "rich_description": "富文本备注飞书开放平台\n",
            "due": {
                "time": "1623124318",
                "timezone": "Asia/Shanghai"
            },
            "extra": "dGVzdA==",
            "id": "68c9b9ff-d5b5-41bf-b407-6d956f23143f",
            "origin": {
                "href": {
                    "title": "反馈一个问题，需要协助排查",
                    "url": "https://support.feishu.com/internal/foo-bar"
                },
                "platform_i18n_name": "{\"en_us\":\"IT Workspace\",\"zh_cn\":\"IT 工作台\"}"
            },
            "summary": "每天喝八杯水，保持身心愉悦",
            "rich_summary": "富文本标题飞书开放平台\n",
            "custom": "{\"custom_complete\":{\"android\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"ios\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"pc\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}}}}",
            "update_time": "1630304149",
            "source": 6,
            "collaborators": [
                {
                    "id": "ou_13585843f02bc94923ed17a007cbc9b1"
                },
                {
                    "id": "ou_219a0611de2a639aa939ee97013f37a5"
                }
            ],
            "followers": [
                {
                    "id": "ou_13585843f02bc94923ed17a007cbc9b1"
                },
                {
                    "id": "ou_219a0611de2a639aa939ee97013f37a5"
                }
            ],
            "repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
        }
    },
    "msg": "success"
}
```

### 错误码

HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 1470400 | The request failed due to incorrect request parameters. | 一般可能是请求参数存在问题，导致请求失败，建议根据返回的具体错误进行排查
401 | 1470403 | The identity token is incorrect. It should be either user_access_token or tenant_access_token. | 发起请求方的身份token不正确，需要为UserAccessToken或TenantAccessToken其中一种
400 | 1470410 | Failed to parse rich_summary. | 富文本标题解析错误，建议检查一下rich_summary是否存在格式错误，语法格式参见[Markdown模块](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)
400 | 1470411 | Failed to parse rich_description. | 富文本描述解析错误，建议检查一下rich_description是否存在格式错误，语法格式参见[Markdown模块](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/task-v1/markdown-module)
400 | 1470414 | Invalid timezone. | 填入的时区信息不合规，建议检查timezone字段是否格式正确，传入值需要符合IANA Time Zone Database标准，规范见[Time Zone Database](https://www.iana.org/time-zones)
400 | 1470415 | Invalid platform_i18n_name. | 任务导入来源的名称不合规，建议检查platform_i18n_name字段是否格式正确，可能传入了不支持的地区名
400 | 1470416 | Both summary and rich_summary are empty. | 标题和富文本标题都没有设置内容，创建任务时要求必须填入其中一个字段
400 | 1470434 | Invalid repeat rule, please check the format. | 重复规则无法解析，可能是传入了不正确的格式，请检查是否符合语法规范
400 | 1470435 | Failed to decode extra by base64. | extra字段无法按base64格式解析，请检查传入的内容是否由base64编码后传入
400 | 1470436 | Failed to parse url of origin, should start with http, https or applink. | 解析Origin中的URL失败，请检查是否以http、https或applink开头
400 | 1470437 | Summary or description length exceed limit, the maximum length of summary is 256, the maximum length of description is 65536. | 任务标题或者描述的文本长度超出限制，标题文本最大长度为256个字符，描述文本最大长度是65536个字符
400 | 1470438 | Invalid custom, please check the format. | Custom字段格式错误，请根据字段说明检查
400 | 1470439 | Failed to get time by timestamp. | 无法解析时间戳，请根据字段说明检查时间戳是否符合规范
429 | 1470450 | There are too many requests currently, please try again later. | 当前同时发起的请求过多，峰值较高导致了限流，请稍后重新尝试
500 | 1470600 | Failed to create task. | 任务创建失败，若重试无法解决，请联系飞书技术人员协助排查
400 | 1470740 | Text content fails to pass the audit. | 一般是任务的标题或描述或富文本内容存在非法内容，没有通过安全内容检查