跳转至

comments

feishu.task.comments

CommentsNamespace

Bases: Namespace

任务评论（Comment）接口命名空间。

通过 client.task.comments 访问，封装飞书任务 v2 中评论的增删改查（创建、列举、更新、删除）。 评论挂载在某个资源上，由 resource_type（默认 task）与 resource_id（任务的 guid）共同定位。

通常无需直接实例化，应通过 client.task.comments 访问。

飞书文档

创建评论

源代码位于： feishu/task/comments.py
Python
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
class CommentsNamespace(Namespace):
    r"""
    任务评论（Comment）接口命名空间。

    通过 `client.task.comments` 访问，封装飞书任务 v2 中评论的增删改查（创建、列举、更新、删除）。
    评论挂载在某个资源上，由 `resource_type`（默认 `task`）与 `resource_id`（任务的 `guid`）共同定位。

    通常无需直接实例化，应通过 `client.task.comments` 访问。

    飞书文档:
        [创建评论](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/comment/create)
    """

    async def create(
        self,
        resource_id: str,
        content: str,
        *,
        resource_type: str = "task",
        user_id_type: str | None = None,
    ) -> NestedDict:
        r"""
        在任务上创建评论。

        Args:
            resource_id: 被评论资源的 ID；当 `resource_type` 为 `task` 时即任务的 `guid`。
            content: 评论内容文本。
            resource_type: 被评论资源的类型，默认 `task`。
            user_id_type: 用户 ID 的类型，如 `open_id`、`union_id`、`user_id`；为空时使用接口默认值。

        Returns:
            创建结果数据，含 `comment` 字段，内含 `id`、`content`、`creator`、`resource_id`、`resource_type`、
            `created_at` 等信息。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [创建评论](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/comment/create)

        Examples:
            >>> await client.task.comments.create("d116...", "已完成初稿")  # doctest:+SKIP
            {'comment': {'id': '7654...', 'content': '已完成初稿', 'resource_id': 'd116...'}}
        """
        params: dict[str, Any] = {}
        if user_id_type is not None:
            params["user_id_type"] = user_id_type
        body = {"content": content, "resource_type": resource_type, "resource_id": resource_id}
        return await self._request_data("POST", "task/v2/comments", params=params, json=body)

    async def list(
        self,
        resource_id: str,
        *,
        resource_type: str = "task",
        user_id_type: str | None = None,
        page_size: int = 50,
        max_items: int | None = None,
    ) -> builtins.list[NestedDict]:
        r"""
        列举某个任务下的评论。

        自动翻页并汇总目标资源上的评论。

        Args:
            resource_id: 资源 ID；当 `resource_type` 为 `task` 时即任务的 `guid`。
            resource_type: 资源类型，默认 `task`。
            user_id_type: 用户 ID 的类型，如 `open_id`、`union_id`、`user_id`；为空时使用接口默认值。
            page_size: 每页数量。默认为 50；超过 [feishu.consts.MAX_PAGE_SIZE][] 时由客户端收敛。
            max_items: 最多返回的评论数量，`None` 表示不限制。默认为 `None`。

        Returns:
            评论对象列表（`data.items`）；无评论时返回空列表。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [获取评论列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/comment/list)

        Examples:
            >>> await client.task.comments.list("d116...")  # doctest:+SKIP
            [{'id': '7654...', 'content': '已完成初稿'}]
        """
        params: dict[str, Any] = {"resource_type": resource_type, "resource_id": resource_id}
        if user_id_type is not None:
            params["user_id_type"] = user_id_type
        return await self._client.paginate_get(
            "task/v2/comments", params=params, page_size=page_size, max_items=max_items
        )

    async def update(self, comment_id: str, content: str) -> NestedDict:
        r"""
        更新评论内容。

        仅评论的创建者可编辑评论内容。需要 `task:comment:write` 权限。

        Args:
            comment_id: 评论的唯一标识 `id`。
            content: 更新后的评论内容文本。

        Returns:
            更新后的评论数据，含 `comment` 字段，内含 `id`、`content`、`creator`、`resource_id`、
            `resource_type` 等信息。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [更新评论](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/comment/patch)

        Examples:
            >>> await client.task.comments.update("7654...", "已完成终稿")  # doctest:+SKIP
            {'comment': {'id': '7654...', 'content': '已完成终稿'}}
        """
        body = {"comment": {"content": content}, "update_fields": ["content"]}
        return await self._request_data("PATCH", f"task/v2/comments/{quote_segment(comment_id)}", json=body)

    async def delete(self, comment_id: str) -> NestedDict:
        r"""
        删除评论。

        需要 `task:comment:write` 权限。

        Args:
            comment_id: 评论的唯一标识 `id`。

        Returns:
            空数据体（接口成功时不返回额外字段）。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [删除评论](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/comment/delete)

        Examples:
            >>> await client.task.comments.delete("7654...")  # doctest:+SKIP
            {}
        """
        return await self._request_data("DELETE", f"task/v2/comments/{quote_segment(comment_id)}")

create async

Python
create(resource_id: str, content: str, *, resource_type: str = 'task', user_id_type: str | None = None) -> NestedDict

在任务上创建评论。

参数：

名称 类型 描述 默认
resource_id
str

被评论资源的 ID；当 resource_type 为 task 时即任务的 guid。

 必需
content
str

评论内容文本。

 必需
resource_type
str

被评论资源的类型，默认 task。

 'task'
user_id_type
str | None

用户 ID 的类型，如 open_id、union_id、user_id；为空时使用接口默认值。

 None

返回：

类型 描述
NestedDict

创建结果数据，含 comment 字段，内含 id、content、creator、resource_id、resource_type、
NestedDict

created_at 等信息。

引发：

类型 描述
FeishuError

请求失败或返回错误码时抛出。
飞书文档

创建评论

示例：

Python Console Session
1
2
>>> await client.task.comments.create("d116...", "已完成初稿")
{'comment': {'id': '7654...', 'content': '已完成初稿', 'resource_id': 'd116...'}}
源代码位于： feishu/task/comments.py
Python
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
async def create(
    self,
    resource_id: str,
    content: str,
    *,
    resource_type: str = "task",
    user_id_type: str | None = None,
) -> NestedDict:
    r"""
    在任务上创建评论。

    Args:
        resource_id: 被评论资源的 ID；当 `resource_type` 为 `task` 时即任务的 `guid`。
        content: 评论内容文本。
        resource_type: 被评论资源的类型，默认 `task`。
        user_id_type: 用户 ID 的类型，如 `open_id`、`union_id`、`user_id`；为空时使用接口默认值。

    Returns:
        创建结果数据，含 `comment` 字段，内含 `id`、`content`、`creator`、`resource_id`、`resource_type`、
        `created_at` 等信息。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [创建评论](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/comment/create)

    Examples:
        >>> await client.task.comments.create("d116...", "已完成初稿")  # doctest:+SKIP
        {'comment': {'id': '7654...', 'content': '已完成初稿', 'resource_id': 'd116...'}}
    """
    params: dict[str, Any] = {}
    if user_id_type is not None:
        params["user_id_type"] = user_id_type
    body = {"content": content, "resource_type": resource_type, "resource_id": resource_id}
    return await self._request_data("POST", "task/v2/comments", params=params, json=body)

list async

Python
list(resource_id: str, *, resource_type: str = 'task', user_id_type: str | None = None, page_size: int = 50, max_items: int | None = None) -> list[NestedDict]

列举某个任务下的评论。

自动翻页并汇总目标资源上的评论。

参数：

名称 类型 描述 默认
resource_id
str

资源 ID；当 resource_type 为 task 时即任务的 guid。

 必需
resource_type
str

资源类型，默认 task。

 'task'
user_id_type
str | None

用户 ID 的类型，如 open_id、union_id、user_id；为空时使用接口默认值。

 None
page_size
int

每页数量。默认为 50；超过 feishu.consts.MAX_PAGE_SIZE 时由客户端收敛。

 50
max_items
int | None

最多返回的评论数量，None 表示不限制。默认为 None。

 None

返回：

类型 描述
list[NestedDict]

评论对象列表（data.items）；无评论时返回空列表。

引发：

类型 描述
FeishuError

请求失败或返回错误码时抛出。
飞书文档

获取评论列表

示例：

Python Console Session
1
2
>>> await client.task.comments.list("d116...")
[{'id': '7654...', 'content': '已完成初稿'}]
源代码位于： feishu/task/comments.py
Python
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
async def list(
    self,
    resource_id: str,
    *,
    resource_type: str = "task",
    user_id_type: str | None = None,
    page_size: int = 50,
    max_items: int | None = None,
) -> builtins.list[NestedDict]:
    r"""
    列举某个任务下的评论。

    自动翻页并汇总目标资源上的评论。

    Args:
        resource_id: 资源 ID；当 `resource_type` 为 `task` 时即任务的 `guid`。
        resource_type: 资源类型，默认 `task`。
        user_id_type: 用户 ID 的类型，如 `open_id`、`union_id`、`user_id`；为空时使用接口默认值。
        page_size: 每页数量。默认为 50；超过 [feishu.consts.MAX_PAGE_SIZE][] 时由客户端收敛。
        max_items: 最多返回的评论数量，`None` 表示不限制。默认为 `None`。

    Returns:
        评论对象列表（`data.items`）；无评论时返回空列表。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [获取评论列表](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/comment/list)

    Examples:
        >>> await client.task.comments.list("d116...")  # doctest:+SKIP
        [{'id': '7654...', 'content': '已完成初稿'}]
    """
    params: dict[str, Any] = {"resource_type": resource_type, "resource_id": resource_id}
    if user_id_type is not None:
        params["user_id_type"] = user_id_type
    return await self._client.paginate_get(
        "task/v2/comments", params=params, page_size=page_size, max_items=max_items
    )

update async

Python
update(comment_id: str, content: str) -> NestedDict

更新评论内容。

仅评论的创建者可编辑评论内容。需要 task:comment:write 权限。

参数：

名称 类型 描述 默认
comment_id
str

评论的唯一标识 id。

 必需
content
str

更新后的评论内容文本。

 必需

返回：

类型 描述
NestedDict

更新后的评论数据，含 comment 字段，内含 id、content、creator、resource_id、
NestedDict

resource_type 等信息。

引发：

类型 描述
FeishuError

请求失败或返回错误码时抛出。
飞书文档

更新评论

示例：

Python Console Session
1
2
>>> await client.task.comments.update("7654...", "已完成终稿")
{'comment': {'id': '7654...', 'content': '已完成终稿'}}
源代码位于： feishu/task/comments.py
Python
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
async def update(self, comment_id: str, content: str) -> NestedDict:
    r"""
    更新评论内容。

    仅评论的创建者可编辑评论内容。需要 `task:comment:write` 权限。

    Args:
        comment_id: 评论的唯一标识 `id`。
        content: 更新后的评论内容文本。

    Returns:
        更新后的评论数据，含 `comment` 字段，内含 `id`、`content`、`creator`、`resource_id`、
        `resource_type` 等信息。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [更新评论](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/comment/patch)

    Examples:
        >>> await client.task.comments.update("7654...", "已完成终稿")  # doctest:+SKIP
        {'comment': {'id': '7654...', 'content': '已完成终稿'}}
    """
    body = {"comment": {"content": content}, "update_fields": ["content"]}
    return await self._request_data("PATCH", f"task/v2/comments/{quote_segment(comment_id)}", json=body)

delete async

Python
delete(comment_id: str) -> NestedDict

删除评论。

需要 task:comment:write 权限。

参数：

名称 类型 描述 默认
comment_id
str

评论的唯一标识 id。

 必需

返回：

类型 描述
NestedDict

空数据体（接口成功时不返回额外字段）。

引发：

类型 描述
FeishuError

请求失败或返回错误码时抛出。
飞书文档

删除评论

示例：

Python Console Session
1
2
>>> await client.task.comments.delete("7654...")
{}
源代码位于： feishu/task/comments.py
Python
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
async def delete(self, comment_id: str) -> NestedDict:
    r"""
    删除评论。

    需要 `task:comment:write` 权限。

    Args:
        comment_id: 评论的唯一标识 `id`。

    Returns:
        空数据体（接口成功时不返回额外字段）。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [删除评论](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/task-v2/comment/delete)

    Examples:
        >>> await client.task.comments.delete("7654...")  # doctest:+SKIP
        {}
    """
    return await self._request_data("DELETE", f"task/v2/comments/{quote_segment(comment_id)}")