飞书开放平台 Server API 文档

主题

更新任务 ​

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

请求 ​

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

请求头 ​

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

路径参数 ​

名称类型描述
task_idstring任务 ID
示例值："83912691-2e43-47fc-94a4-d512e03984fa"

查询参数 ​

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

请求体 ​

名称类型必填描述
tasktask是被更新的任务实体基础信息
  └ summarystring否任务的标题，类型为文本字符串。 如果要在任务标题中插入 URL 或者 @某个用户，请使用rich_summary字段。 创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。
> Info: 任务标题和任务富文本标题同时存在时只使用富文本标题。
示例值："完成本季度OKR编写"
数据校验规则：
- 长度范围：0 ～ 1000 字符
  └ descriptionstring否任务的描述，类型为文本字符串。 如果要在任务描述中插入 URL 或者 @某个用户，请使用rich_description字段。
> Info: 任务备注和任务富文本备注同时存在时只使用富文本备注。
示例值："对本次会议内容复盘总结，编写更新本季度OKR"
数据校验规则：
- 长度范围：0 ～ 65536 字符
  └ extrastring否附属信息。 接入方可以传入base64 编码后的自定义的数据。用户如果需要对当前任务备注信息，但对外不显示，可使用该字段进行存储。 该数据会在获取任务详情时，原样返回给用户。
示例值："dGVzdA=="
数据校验规则：
- 长度范围：0 ～ 65536 字符
  └ duedue否任务的截止时间设置
    └ timestring否表示截止时间的Unix时间戳（单位为秒）。
示例值："1623124318"
    └ timezonestring否截止时间对应的时区。 传入值需要符合IANA Time Zone Database标准，规范见Time Zone Database。
示例值："Asia/Shanghai"
默认值：Asia/Shanghai
    └ is_all_dayboolean否标记任务是否为全天任务。 包括如下取值： - true：表示是全天任务，全天任务的截止时间为当天 UTC 时间的 0 点。 - false：表示不是全天任务。
示例值：false
默认值：false
  └ originorigin否任务关联的第三方平台来源信息
    └ platform_i18n_namestring是任务来源的名称。 用于在任务中心详情页展示。需要提供一个字典，支持多种语言名称映射。应用在使用不同语言时，导入来源也将展示对应的内容。详细参见：任务字段补充说明
示例值："{\"zh_cn\": \"IT 工作台\", \"en_us\": \"IT Workspace\"}"
数据校验规则：
- 长度范围：0 ～ 1024 字符
    └ hrefhref否任务关联的来源平台详情页链接
      └ urlstring否具体链接地址。 URL仅支持解析http、https。详细参见：任务字段补充说明
示例值："https://support.feishu.com/internal/foo-bar"
数据校验规则：
- 长度范围：0 ～ 1024 字符
      └ titlestring否链接对应的标题
示例值："反馈一个问题，需要协助排查"
数据校验规则：
- 长度范围：0 ～ 512 字符
  └ can_editboolean否此字段用于控制该任务在飞书任务中心是否可编辑，默认为false
> Info: 已经废弃，向前兼容故仍然保留，但不推荐使用
示例值：true
默认值：false
  └ customstring否自定义完成配置。 此字段用于设置完成任务时的页面跳转，或展示提示语。详细参见：任务字段补充说明
示例值："{"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\"}}}}"
数据校验规则：
- 长度范围：0 ～ 65536 字符
  └ followersfollower\[\]否任务的关注者
示例值：ou_03c21c80caea2c816665f8056dc59027
    └ idstring否任务关注人 ID
示例值："ou_99e1a581b36ecc4862cbfbce473f3123"
    └ id_liststring\[\]否要删除的关注人ID列表
示例值：["ou_99e1a581b36ecc4862cbfbce473f3123"]
  └ collaboratorscollaborator\[\]否任务的执行者
示例值：ou_558d4999baae26e32aa2fd9bb228660b
    └ idstring否任务执行者的 ID。 传入的值为 user_id 或 open_id，由user_id_type 决定。user_id和open_id的获取可见文档如何获取不同的用户 ID。
> Info: 已经废弃，为了向前兼容早期只支持单次添加一个人的情况而保留，但不再推荐使用，建议使用id_list字段
示例值："ou_99e1a581b36ecc4862cbfbce473f1234"
    └ id_liststring\[\]否执行者的用户ID列表。 传入的值为 user_id 或 open_id，由user_id_type 决定。user_id和open_id的获取可见文档如何获取不同的用户 ID。
示例值：["ou_99e1a581b36ecc4862cbfbce473f3123"]
  └ collaborator_idsstring\[\]否创建任务时添加的执行者用户id列表。 传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：如何获取不同的用户 ID。
示例值：["ou_49dadcd6fd55da971d887087c4f3a37a"]
数据校验规则：
- 最大长度：100
  └ follower_idsstring\[\]否创建任务时添加的关注者用户id列表。 传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：如何获取不同的用户 ID。
示例值：["ou_49dadcd6fd55da971d887087c4f3a37a"]
数据校验规则：
- 最大长度：100
  └ repeat_rulestring否重复任务的规则表达式。 语法格式参见RRule语法规范 4.3.10小节
示例值："FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
  └ rich_summarystring否富文本任务标题。语法格式参见Markdown模块 。创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。
示例值："完成本季度OKR编写[飞书开放平台](https://open.feishu.cn/)"
数据校验规则：
- 长度范围：0 ～ 1000 字符
  └ rich_descriptionstring否富文本任务备注。语法格式参见Markdown模块
示例值："对本次会议内容复盘总结，编写更新本季度OKR[飞书开放平台](https://open.feishu.cn/)"
数据校验规则：
- 长度范围：0 ～ 65536 字符
update_fieldsstring\[\]是指定需要更新的任务字段。可以更新的字段包括：
- summary: 任务标题（普通文本） - rich_summary: 任务标题（富文本） - description: 任务描述（普通文本） - rich_description: 任务描述（富文本） - due: 任务截止时间 - extra: 任务附属信息 - custom: 任务自定义完成规则 - follower_ids: 任务关注人ID列表 - collaborator_ids: 任务执行者ID列表 - repeat_rule: 任务重复规则
示例值：["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"]
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ tasktask返回修改后的任务详情
    └ 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链接对应的标题
    └ 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模块

响应体示例 ​

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状态码错误码描述排查建议
4001470400The request failed due to incorrect request parameters.一般可能是请求参数存在问题，导致请求失败，建议根据返回的具体错误进行排查
4031470403The identity token is incorrect. It should be either user_access_token or tenant_access_token.发起请求方的身份token不正确，需要为UserAccessToken或TenantAccessToken其中一种
4001470410failed to parse rich_summary富文本标题解析错误，建议检查一下rich_summary是否存在格式错误，语法格式参见Markdown模块
4001470411failed to parse rich_description富文本描述解析错误，建议检查一下rich_description是否存在格式错误，语法格式参见Markdown模块
4001470412invalid follower id关注者id无效，建议确认一下是否向follower_ids字段传入了非法的关注者id，如空值“”
4001470413invalid collaborator id协作者id无效，建议确认一下是否向collaborator_ids字段传入了非法的协作者id，如空值“”
4001470414invalid time zone填入的时区信息不合规，建议检查timezone字段是否格式正确，传入值需要符合IANA Time Zone Database标准，规范见Time Zone Database
4001470415invalid platform_i18n_name任务导入来源的名称不合规，建议检查platform_i18n_name字段是否格式正确，可能传入了不支持的地区名
4001470423task id is missing传入的任务id丢失
4001470424update_fields include unknown fieldupdate_field中包含了未知的字段
4001470425update_fields include forbidden fieldupdate_field中包含了禁止更新的字段
4001470426expected one or more update fieldupdate_field为空，应该填充需要更新的字段
4001470450request too fast当前同时发起的请求过多，峰值较高导致了限流，请稍后重新尝试
4001470602Invalid task id.请检查任务的 id 是否合法
5001470603update task failed一般是业务逻辑校验未通过
4001470740Text content fails to pass the audit.一般是任务的标题或描述或富文本内容存在非法内容，没有通过安全内容检查
5001470741failed to audit task任务内容审核失败，建议结合失败原因排查。如果无法解决，请提供 request id 并联系飞书技术人员协助排查
4001470404be refused to create or update task, perhaps you have no permission一般是因为操作者没有操作权限，导致更新任务或其他更新任务的操作失败。如，任务的关注者没有权限修改任务。
4001470434invalid repeat rule, please check the format重复规则无法解析，可能是传入了不正确的格式，请检查是否符合语法规范
4001470435decode extra by base64 failedextra字段无法按base64格式解析，请检查传入的内容是否由base64编码后传入
4001470436failed to parse url of origin, should start with http, https or applink解析Origin中的URL失败，请检查是否以http、https或applink开头
4001470437summary or description length exceed limit, the maximum length of summary is 256, the maximum length of description is 65536任务标题或者描述的文本长度超出限制，标题文本最大长度为256个字符，描述文本最大长度是65536个字符
4001470438invalid custom, please check the formatCustom字段格式错误，请根据字段说明检查
4001470439failed to get time by timestamp无法解析时间戳，请根据字段说明检查时间戳是否符合规范

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

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