wechatpy.work.client.api.tag 源代码

# -*- coding: utf-8 -*-

from typing import Optional, List, Dict, Any

from wechatpy.client.api.base import BaseWeChatAPI


[文档]class WeChatTag(BaseWeChatAPI): @staticmethod def _validate_tag_id(tag_id): if tag_id < 0: raise ValueError("tag id cannot be a negative integer") @staticmethod def _validate_tag_name(tag_name): if len(tag_name) > 32: raise ValueError("the length of the tag name cannot be more than 32 characters")
[文档] def create(self, name: str, tag_id: Optional[int] = None) -> dict: """创建标签 参考:https://developer.work.weixin.qq.com/document/path/90210 **权限说明**: 创建的标签属于该应用,只有该应用才可以增删成员。 **注意**: 标签总数不能超过3000个。 返回结果示例: :: { "errcode": 0, "errmsg": "created" "tagid": 12 } 返回结果参数说明: +---------+------------------------+ | 参数 | 说明 | +=========+========================+ | errcode | 返回码 | +---------+------------------------+ | errmsg | 对返回码的文本描述内容 | +---------+------------------------+ | tagid | 标签id | +---------+------------------------+ :param name: 标签名称,长度限制为32个字以内(汉字或英文字母),标签名不可与 其他标签重名。 :param tag_id: 标签id,非负整型,指定此参数时新增的标签会生成对应的标签id,不指 定时则以目前最大的id自增。 :return: 创建结果 """ if tag_id is not None: self._validate_tag_id(tag_id) self._validate_tag_name(name) data: Dict[str, Any] = {"tagname": name} if tag_id: data["tagid"] = tag_id return self._post("tag/create", data=data)
[文档] def update(self, tag_id: int, name: str) -> dict: """更新标签名字 参考:https://developer.work.weixin.qq.com/document/path/90211 **权限说明**:调用的应用必须是指定标签的创建者。 返回结果示例: :: { "errcode": 0, "errmsg": "updated" } 结果参数说明: +---------+------------------------+ | 参数 | 说明 | +=========+========================+ | errcode | 返回码 | +---------+------------------------+ | errmsg | 对返回码的文本描述内容 | +---------+------------------------+ :param tag_id: 标签ID :param name: 标签名称,长度限制为32个字(汉字或英文字母),标签不可与其他标签重名。 :return: 更新结果 """ self._validate_tag_id(tag_id) self._validate_tag_name(name) return self._post("tag/update", data={"tagid": tag_id, "tagname": name})
[文档] def delete(self, tag_id: int) -> dict: """删除标签 参考:https://developer.work.weixin.qq.com/document/path/90212 **权限说明**:调用的应用必须是指定标签的创建者。 返回结果示例: :: { "errcode": 0, "errmsg": "deleted" } 结果参数说明: +---------+------------------------+ | 参数 | 说明 | +=========+========================+ | errcode | 返回码 | +---------+------------------------+ | errmsg | 对返回码的文本描述内容 | +---------+------------------------+ :param tag_id: 标签ID,非负整型 :return: 删除结果 """ self._validate_tag_id(tag_id) return self._get("tag/delete", params={"tagid": tag_id})
[文档] def get_users(self, tag_id: int) -> dict: """获取标签成员 参考:https://developer.work.weixin.qq.com/document/path/90213 **权限说明**: 无限制,但返回列表仅包含应用可见范围的成员;第三方可获取自己创建的标签及应用可见 范围内的标签详情。 返回结果示例: :: { "errcode": 0, "errmsg": "ok", "tagname": "乒乓球协会", "userlist": [ { "userid": "zhangsan", "name": "李四" } ], "partylist": [2] } 结果参数说明: +-----------+-------------------------------------------------------------------------------+ | 参数 | 说明 | +===========+===============================================================================+ | errcode | 返回码 | +-----------+-------------------------------------------------------------------------------+ | errmsg | 对返回码的文本描述内容 | +-----------+-------------------------------------------------------------------------------+ | tagname | 标签名 | +-----------+-------------------------------------------------------------------------------+ | userlist | 标签中包含的成员列表 | +-----------+-------------------------------------------------------------------------------+ | userid | 成员帐号 | +-----------+-------------------------------------------------------------------------------+ | name | 成员名称,此字段从2019年12月30日起,对新创建第三方应用不再返回, | | | 2020年6月30日起,对所有历史第三方应用不再返回,后续第三方仅通讯录应用可获取, | | | 第三方页面需要通过通讯录展示组件来展示名字 | +-----------+-------------------------------------------------------------------------------+ | partylist | 标签中包含的部门id列表 | +-----------+-------------------------------------------------------------------------------+ :param tag_id: 标签ID,非负整型 :return: 成员用户信息 """ self._validate_tag_id(tag_id) return self._get("tag/get", params={"tagid": tag_id})
[文档] def add_users( self, tag_id: int, user_ids: Optional[List[str]] = None, department_ids: Optional[List[int]] = None ) -> dict: """增加标签成员 参考:https://developer.work.weixin.qq.com/document/path/90214 **权限说明**: 调用的应用必须是指定标签的创建者;成员属于应用的可见范围。 **注意**:每个标签下部门、人员总数不能超过3万个。 返回结果示例: a. 正确时返回 :: { "errcode": 0, "errmsg": "ok" } b. 若部分userid、partylist非法,则返回 :: { "errcode": 0, "errmsg": "ok", "invalidlist":"usr1|usr2|usr", "invalidparty":[2,4] } c. 当包含userid、partylist全部非法时返回 :: { "errcode": 40070, "errmsg": "all list invalid " } 结果参数说明: +--------------+------------------------+ | 参数 | 说明 | +==============+========================+ | errcode | 返回码 | +--------------+------------------------+ | errmsg | 对返回码的文本描述内容 | +--------------+------------------------+ | invalidlist | 非法的成员帐号列表 | +--------------+------------------------+ | invalidparty | 非法的部门id列表 | +--------------+------------------------+ :param tag_id: 标签ID,非负整型 :param user_ids: 企业成员ID列表,注意:user_ids和department_ids不能同时为空, 单次请求个数不超过1000 :param department_ids: 企业部门ID列表,注意:user_ids和department_ids不能 同时为空,单次请求个数不超过100 :return: 请求结果 """ self._validate_tag_id(tag_id) if not user_ids and not department_ids: raise ValueError("user_ids and department_ids cannot be empty at the same time") if user_ids is not None and len(user_ids) > 1000: raise ValueError("the length of the user_ids cannot be greater than 1000") if department_ids is not None and len(department_ids) > 100: raise ValueError("the length of the department_ids cannot be greater than 100") data: Dict[str, Any] = {"tagid": tag_id} if user_ids: data["userlist"] = user_ids if department_ids: data["partylist"] = department_ids return self._post("tag/addtagusers", data=data)
[文档] def delete_users( self, tag_id: int, user_ids: Optional[List[str]] = None, department_ids: Optional[List[int]] = None ) -> dict: """删除标签成员 参考:https://developer.work.weixin.qq.com/document/path/90215 **权限说明**: 调用的应用必须是指定标签的创建者;成员属于应用的可见范围。 返回结果示例: a. 正确时返回 :: { "errcode": 0, "errmsg": "deleted" } b. 若部分userid、partylist非法,则返回 :: { "errcode": 0, "errmsg": "deleted", "invalidlist":"usr1|usr2|usr", "invalidparty": [2,4] } c. 当包含的userid、partylist全部非法时返回 :: { "errcode": 40031, "errmsg": "all list invalid" } 结果参数说明: +--------------+------------------------+ | 参数 | 说明 | +==============+========================+ | errcode | 返回码 | +--------------+------------------------+ | errmsg | 对返回码的文本描述内容 | +--------------+------------------------+ | invalidlist | 非法的成员帐号列表 | +--------------+------------------------+ | invalidparty | 非法的部门id列表 | +--------------+------------------------+ :param tag_id: 标签ID,非负整型 :param user_ids: 企业成员ID列表,注意:user_ids和department_ids不能同时为空, 单次请求长度不超过1000 :param department_ids: 企业部门ID列表,注意:user_ids和department_ids不能 同时为空,单次请求长度不超过100 :return: 处理结果 """ self._validate_tag_id(tag_id) if not user_ids and not department_ids: raise ValueError("user_ids and department_ids cannot be empty at the same time") if user_ids is not None and len(user_ids) > 1000: raise ValueError("the length of the user_ids cannot be greater than 1000") if department_ids is not None and len(department_ids) > 100: raise ValueError("the length of the department_ids cannot be greater than 100") data: Dict[str, Any] = {"tagid": tag_id} if user_ids: data["userlist"] = user_ids if department_ids: data["partylist"] = department_ids return self._post("tag/deltagusers", data=data)
[文档] def list(self) -> List[dict]: """获取标签列表 参考:https://developer.work.weixin.qq.com/document/path/90216 **权限说明**: 自建应用或通讯同步助手可以获取所有标签列表;第三方应用仅可获取自己创建的标签。 返回结果示例: :: { "errcode": 0, "errmsg": "ok", "taglist":[ {"tagid":1,"tagname":"a"}, {"tagid":2,"tagname":"b"} ] } 结果参数说明: +---------+------------------------+ | 参数 | 说明 | +=========+========================+ | errcode | 返回码 | +---------+------------------------+ | errmsg | 对返回码的文本描述内容 | +---------+------------------------+ | taglist | 标签列表 | +---------+------------------------+ | tagid | 标签id | +---------+------------------------+ | tagname | 标签名 | +---------+------------------------+ :return: 标签信息列表,不包含errcode等信息 """ res = self._get("tag/list") return res["taglist"]