跳转至

comments

feishu.approval.comments

CommentsNamespace

Bases: Namespace

审批评论接口命名空间。

通过 client.approval.comments 访问，封装飞书审批中审批评论（comment）相关的服务端接口， 包括创建与列举审批评论等能力。评论隶属于某个审批实例（instance_id，即 instance_code）， 以 comment_id 标识。

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

飞书文档

审批 / 评论

源代码位于： feishu/approval/comments.py
Python
 32
 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
class CommentsNamespace(Namespace):
    r"""
    审批评论接口命名空间。

    通过 `client.approval.comments` 访问，封装飞书审批中审批评论（comment）相关的服务端接口，
    包括创建与列举审批评论等能力。评论隶属于某个审批实例（`instance_id`，即 `instance_code`），
    以 `comment_id` 标识。

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

    飞书文档:
        [审批 / 评论](https://open.feishu.cn/document/server-docs/approval-v4/instance-comment/create)
    """

    async def create(self, instance_id: str, comment: dict[str, Any], *, user_id: str | None = None) -> NestedDict:
        r"""
        创建审批评论。

        `comment` 是描述待创建评论的请求体，原样作为 JSON 发送，常见键包括 `content`、
        `at_info_list`、`parent_comment_id` 等。仅当显式传入 `user_id` 时才将其并入查询参数。

        Args:
            instance_id: 审批实例的 `instance_id`（即 `instance_code`）。
            comment: 评论定义对象，例如 `{"content": "请补充材料"}`。
            user_id: 发表评论的用户 ID；为空时省略该参数。

        Returns:
            创建结果数据，含新建评论的 `comment_id` 等字段。

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

        飞书文档:
            [创建评论](https://open.feishu.cn/document/server-docs/approval-v4/instance-comment/create)

        Examples:
            >>> await client.approval.comments.create("INST123", {"content": "请补充材料"})  # doctest:+SKIP
            {'comment_id': 'C1'}  # noqa: E501
        """
        params = {}
        if user_id is not None:
            params["user_id"] = user_id
        return await self._request_data(
            "POST", f"approval/v4/instances/{quote_segment(instance_id)}/comments", params=params, json=comment
        )

    async def list(
        self, instance_id: str, *, user_id: str | None = None, page_size: int = 50, max_items: int | None = None
    ) -> list[NestedDict]:
        r"""
        获取审批评论列表。

        自动翻页并将各页结果拼接为单个列表返回。`page_size` 会被限制在
        [feishu.consts.MAX_PAGE_SIZE][] 以内。仅当显式传入 `user_id` 时才将其并入查询参数。
        响应体中评论条目位于 `comments` 字段下。

        Args:
            instance_id: 审批实例的 `instance_id`（即 `instance_code`）。
            user_id: 用户 ID，用于按指定用户视角返回评论；为空时省略该参数。
            page_size: 每页条数，默认为 50，超过上限时按上限截断。
            max_items: 最多返回的条数；为空表示返回全部。

        Returns:
            评论数据列表，每项包含 `id`、`content`、`create_time`、`commentator`、`replies`
            等字段。

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

        飞书文档:
            [获取评论](https://open.feishu.cn/document/server-docs/approval-v4/instance-comment/list)

        Examples:
            >>> await client.approval.comments.list("INST123", user_id="ou_xxx")  # doctest:+SKIP
            [{'id': 'C1', 'content': '请补充材料', ...}, ...]  # noqa: E501
        """
        params: dict[str, Any] = {}
        if user_id is not None:
            params["user_id"] = user_id
        return await self._client.paginate_get(
            f"approval/v4/instances/{quote_segment(instance_id)}/comments",
            params=params,
            page_size=page_size,
            max_items=max_items,
            items_key="comments",
        )

create async

Python
create(instance_id: str, comment: dict[str, Any], *, user_id: str | None = None) -> NestedDict

创建审批评论。

comment 是描述待创建评论的请求体，原样作为 JSON 发送，常见键包括 content、 at_info_list、parent_comment_id 等。仅当显式传入 user_id 时才将其并入查询参数。

参数：

名称 类型 描述 默认
instance_id
str

审批实例的 instance_id（即 instance_code）。

 必需
comment
dict[str, Any]

评论定义对象，例如 {"content": "请补充材料"}。

 必需
user_id
str | None

发表评论的用户 ID；为空时省略该参数。

 None

返回：

类型 描述
NestedDict

创建结果数据，含新建评论的 comment_id 等字段。

引发：

类型 描述
FeishuError

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

创建评论

示例：

Python Console Session
1
2
>>> await client.approval.comments.create("INST123", {"content": "请补充材料"})
{'comment_id': 'C1'}  # noqa: E501
源代码位于： feishu/approval/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
async def create(self, instance_id: str, comment: dict[str, Any], *, user_id: str | None = None) -> NestedDict:
    r"""
    创建审批评论。

    `comment` 是描述待创建评论的请求体，原样作为 JSON 发送，常见键包括 `content`、
    `at_info_list`、`parent_comment_id` 等。仅当显式传入 `user_id` 时才将其并入查询参数。

    Args:
        instance_id: 审批实例的 `instance_id`（即 `instance_code`）。
        comment: 评论定义对象，例如 `{"content": "请补充材料"}`。
        user_id: 发表评论的用户 ID；为空时省略该参数。

    Returns:
        创建结果数据，含新建评论的 `comment_id` 等字段。

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

    飞书文档:
        [创建评论](https://open.feishu.cn/document/server-docs/approval-v4/instance-comment/create)

    Examples:
        >>> await client.approval.comments.create("INST123", {"content": "请补充材料"})  # doctest:+SKIP
        {'comment_id': 'C1'}  # noqa: E501
    """
    params = {}
    if user_id is not None:
        params["user_id"] = user_id
    return await self._request_data(
        "POST", f"approval/v4/instances/{quote_segment(instance_id)}/comments", params=params, json=comment
    )

list async

Python
list(instance_id: str, *, user_id: str | None = None, page_size: int = 50, max_items: int | None = None) -> list[NestedDict]

获取审批评论列表。

自动翻页并将各页结果拼接为单个列表返回。page_size 会被限制在 [feishu.consts.MAX_PAGE_SIZE][] 以内。仅当显式传入 user_id 时才将其并入查询参数。 响应体中评论条目位于 comments 字段下。

参数：

名称 类型 描述 默认
instance_id
str

审批实例的 instance_id（即 instance_code）。

 必需
user_id
str | None

用户 ID，用于按指定用户视角返回评论；为空时省略该参数。

 None
page_size
int

每页条数，默认为 50，超过上限时按上限截断。

 50
max_items
int | None

最多返回的条数；为空表示返回全部。

 None

返回：

类型 描述
list[NestedDict]

评论数据列表，每项包含 id、content、create_time、commentator、replies
list[NestedDict]

等字段。

引发：

类型 描述
FeishuError

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

获取评论

示例：

Python Console Session
1
2
>>> await client.approval.comments.list("INST123", user_id="ou_xxx")
[{'id': 'C1', 'content': '请补充材料', ...}, ...]  # noqa: E501
源代码位于： feishu/approval/comments.py
Python
 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
async def list(
    self, instance_id: str, *, user_id: str | None = None, page_size: int = 50, max_items: int | None = None
) -> list[NestedDict]:
    r"""
    获取审批评论列表。

    自动翻页并将各页结果拼接为单个列表返回。`page_size` 会被限制在
    [feishu.consts.MAX_PAGE_SIZE][] 以内。仅当显式传入 `user_id` 时才将其并入查询参数。
    响应体中评论条目位于 `comments` 字段下。

    Args:
        instance_id: 审批实例的 `instance_id`（即 `instance_code`）。
        user_id: 用户 ID，用于按指定用户视角返回评论；为空时省略该参数。
        page_size: 每页条数，默认为 50，超过上限时按上限截断。
        max_items: 最多返回的条数；为空表示返回全部。

    Returns:
        评论数据列表，每项包含 `id`、`content`、`create_time`、`commentator`、`replies`
        等字段。

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

    飞书文档:
        [获取评论](https://open.feishu.cn/document/server-docs/approval-v4/instance-comment/list)

    Examples:
        >>> await client.approval.comments.list("INST123", user_id="ou_xxx")  # doctest:+SKIP
        [{'id': 'C1', 'content': '请补充材料', ...}, ...]  # noqa: E501
    """
    params: dict[str, Any] = {}
    if user_id is not None:
        params["user_id"] = user_id
    return await self._client.paginate_get(
        f"approval/v4/instances/{quote_segment(instance_id)}/comments",
        params=params,
        page_size=page_size,
        max_items=max_items,
        items_key="comments",
    )