# 更新任务

该接口用于修改任务的标题、描述、时间、来源等相关信息。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/task/v1/tasks/:task_id
HTTP Method | PATCH
接口频率限制 | [1000 次/分钟、50 次/秒](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"

### 路径参数

名称 | 类型 | 描述
---|---|---
task_id | string | 任务 ID<br>**示例值**："83912691-2e43-47fc-94a4-d512e03984fa"

### 查询参数

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

### 请求体

名称 | 类型 | 必填 | 描述
---|---|---|---
task | task | 是 | 被更新的任务实体基础信息
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` 字符
followers | follower\[\] | 否 | 任务的关注者<br>**示例值**：ou_03c21c80caea2c816665f8056dc59027
id | string | 否 | 任务关注人 ID<br>**示例值**："ou_99e1a581b36ecc4862cbfbce473f3123"
id_list | string\[\] | 否 | 要删除的关注人ID列表<br>**示例值**：["ou_99e1a581b36ecc4862cbfbce473f3123"]
collaborators | collaborator\[\] | 否 | 任务的执行者<br>**示例值**：ou_558d4999baae26e32aa2fd9bb228660b
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字段<br>**示例值**："ou_99e1a581b36ecc4862cbfbce473f1234"
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)。<br>**示例值**：["ou_99e1a581b36ecc4862cbfbce473f3123"]
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` 字符
update_fields | string\[\] | 是 | 指定需要更新的任务字段。可以更新的字段包括：<br>- summary：任务标题（普通文本）<br>- rich_summary：任务标题（富文本）<br>- description：任务描述（普通文本）<br>- rich_description：任务描述（富文本）<br>- due：任务截止时间<br>- extra：任务附属信息<br>- custom：任务自定义完成规则<br>- follower_ids：任务关注人ID列表<br>- collaborator_ids：任务执行者ID列表<br>- repeat_rule：任务重复规则<br>**示例值**：["summary"]

### 请求体示例
```json
{
	"task": {
		"summary": "每天喝八杯水，保持身心愉悦",
		"description": "多吃水果，多运动，健康生活，快乐工作。",
		"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\"}}}}",
		"repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
	},
	"update_fields": ["summary"]
}
```

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
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>**注意事项**：
description | string | 任务的描述，类型为文本字符串。<br>如果要在任务描述中插入 URL 或者 @某个用户，请使用rich_description字段。<br><md-alert><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": "多吃水果，多运动，健康生活，快乐工作。",
            "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": "每天喝八杯水，保持身心愉悦",
            "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,
            "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. | 一般可能是请求参数存在问题，导致请求失败，建议根据返回的具体错误进行排查
403 | 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 | 1470412 | invalid follower id | 关注者id无效，建议确认一下是否向follower_ids字段传入了非法的关注者id，如空值“”
400 | 1470413 | invalid collaborator id | 协作者id无效，建议确认一下是否向collaborator_ids字段传入了非法的协作者id，如空值“”
400 | 1470414 | invalid time zone | 填入的时区信息不合规，建议检查timezone字段是否格式正确，传入值需要符合IANA Time Zone Database标准，规范见[Time Zone Database](https://www.iana.org/time-zones)
400 | 1470415 | invalid platform_i18n_name | 任务导入来源的名称不合规，建议检查platform_i18n_name字段是否格式正确，可能传入了不支持的地区名
400 | 1470423 | task id is missing | 传入的任务id丢失
400 | 1470424 | update_fields include unknown field | update_field中包含了未知的字段
400 | 1470425 | update_fields include forbidden field | update_field中包含了禁止更新的字段
400 | 1470426 | expected one or more update field | update_field为空，应该填充需要更新的字段
400 | 1470450 | request too fast | 当前同时发起的请求过多，峰值较高导致了限流，请稍后重新尝试
400 | 1470602 | Invalid task id. | 请检查任务的 id 是否合法
500 | 1470603 | update task failed | 一般是业务逻辑校验未通过
400 | 1470740 | Text content fails to pass the audit. | 一般是任务的标题或描述或富文本内容存在非法内容，没有通过安全内容检查
500 | 1470741 | failed to audit task | 任务内容审核失败，建议结合失败原因排查。如果无法解决，请提供 request id 并联系飞书技术人员协助排查
400 | 1470404 | be refused to create or update task, perhaps you have no permission | 一般是因为操作者没有操作权限，导致更新任务或其他更新任务的操作失败。如，任务的关注者没有权限修改任务。
400 | 1470434 | invalid repeat rule, please check the format | 重复规则无法解析，可能是传入了不正确的格式，请检查是否符合语法规范
400 | 1470435 | decode extra by base64 failed | 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 | 无法解析时间戳，请根据字段说明检查时间戳是否符合规范