更新清单
更新清单，可以更新清单的名字和所有者。
更新清单时，将update_fields字段中填写所有要修改的清单字段名，同时在tasklist字段中填写要修改的字段的新值即可。更新调用规范详见功能概述中的“ 关于资源的更新”章节。
支持更新的字段包括:
name- 清单名字owner- 清单所有者
更新清单所有者（owner）时，如果该成员已经是清单的“可编辑”或者“可阅读”角色，则该成员将直接升级为所有者角色，自动从清单的成员列表中消失。这是因为同一个用户在同一个清单中只能有一个角色。同时，支持使用origin_owner_to_role字段将原有所有者变为可编辑/可阅读角色或者直接退出清单。
该接口不能用于更新清单的成员和增删清单中的任务。
Tip: 更新清单名字需要清单的编辑权限。
更新清单所有人必须由清单的管理权限。
详情见清单功能概述中的“清单是如何鉴权的？“章节。
请求
| 项目 | 值 |
|---|---|
| HTTP URL | https://open.feishu.cn/open-apis/task/v2/tasklists/:tasklist_guid |
| HTTP Method | PATCH |
| 接口频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | custom,isv |
| 权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 | task:tasklist:write 查看、创建、更新、删除任务清单 |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | string | 是 | tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token |
| Content-Type | string | 是 | 固定值："application/json; charset=utf-8" |
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
tasklist_guid | string | 要更新的清单的全局唯一GUID 示例值："d300a75f-c56a-4be9-80d1-e47653028ceb" |
查询参数
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
user_id_type | string | 否 | 用户 ID 类型 示例值：open_id 默认值： open_id |
请求体
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
tasklist | input_tasklist | 是 | 要更新清单的数据 |
└ name | string | 否 | 清单名称。如要更新，不能设为空。最大100个字符。 示例值："年会工作任务清单" |
└ owner | member | 否 | 更新的清单所有者。 |
└ id | string | 否 | 表示member的id 示例值："ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f" 数据校验规则： - 最大长度： 100 字符 |
└ type | string | 否 | 成员的类型，可以是"user"或者"app"。所有者的类型不可以是"chat"。 示例值："user" 默认值： user |
└ role | string | 否 | 成员角色，此时必须是"owner" 示例值："owner" 数据校验规则： - 最大长度： 20 字符 |
update_fields | string\[\] | 是 | 要更新的字段名，支持 - name: 更新清单名 - owner: 更新清单所有者示例值：["owner"] 数据校验规则： - 最小长度： 1 |
origin_owner_to_role | string | 否 | 该字段表示如果更新了新的所有者，则将原所有者设为指定的新的角色。仅在更新清单所有者时生效。支持"editor", "viewer"和"none"。默认为"none"。 如果不设置或设为"none"，原清单所有者将不具有任何清单的角色。如果没有通过其他渠道（比如通过协作群组间接授权），原清单所有者将失去对清单的所有权限。 示例值："editor" 可选值有： - editor: 原所有者变为可编辑角色 - viewer: 原所有者变为可阅读角色 - none: 原所有者直接退出清单默认值： none |
请求体示例
json
{
"tasklist": {
"name": "年会工作任务清单",
"owner": {
"id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
"type": "user",
"role": "owner"
}
},
"update_fields": [
"owner"
],
"origin_owner_to_role": "editor"
}响应
响应体
| 名称 | 类型 | 描述 |
|---|---|---|
code | int | 错误码，非 0 表示失败 |
msg | string | 错误描述 |
data | \- | - |
└ tasklist | tasklist | 修改后的任务清单 |
└ guid | string | 清单的全局唯一ID |
└ name | string | 清单名 |
└ creator | member | 清单创建者 |
└ id | string | 表示member的id |
└ type | string | 成员的类型 |
└ role | string | 成员角色 |
└ owner | member | 清单所有者 |
└ id | string | 表示所有者的id |
└ type | string | 成员的类型 |
└ role | string | 成员角色 |
└ members | member\[\] | 清单协作人 |
└ id | string | 表示member的id |
└ type | string | 成员的类型 |
└ role | string | 成员类型 |
└ url | string | 该清单分享的applink |
└ created_at | string | 清单创建时间戳(ms) |
└ updated_at | string | 清单最后一次更新时间戳（ms) |
响应体示例
json
{
"code": 0,
"msg": "success",
"data": {
"tasklist": {
"guid": "cc371766-6584-cf50-a222-c22cd9055004",
"name": "年会总结工作任务清单",
"creator": {
"id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
"type": "user",
"role": "creator"
},
"owner": {
"id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
"type": "owner",
"role": "editor"
},
"members": [
{
"id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
"type": "user",
"role": "editor"
}
],
"url": "https://applink.feishu.cn/client/todo/task_list?guid=b45b360f-1961-4058-b338-7f50c96e1b52",
"created_at": "1675742789470",
"updated_at": "1675742789470"
}
}
}错误码
| HTTP状态码 | 错误码 | 描述 | 排查建议 |
|---|---|---|---|
| 400 | 1470400 | 请求参数错误，如提供的清单GUID不合法。 | 错误原因见返回的msg提示的信息。 |
| 404 | 1470404 | 清单不存在或已删除。 | 确认要更新的清单是否存在或已删除。 |
| 500 | 1470500 | 服务器错误。 | 尝试重试调用。如持续失败，请联系支持人员进行反馈。 |
| 403 | 1470403 | 缺少清单编辑权限。如果是更新了清单所有者，则缺少清单所有者权限。详情见清单功能概述中的“清单是如何鉴权的？“章节。 | 检查调用身份是否有清单的权限执行更新。 |