接口介绍
MetadataClient 提供以下用户管理接口，用于创建、查询、删除和列出 Memory 实例下的用户账号。
create_user：创建用户，指定用户名和所属团队。
get_user：按用户 ID 或过滤条件查询单个用户的详细信息。
delete_users：批量删除指定用户（不可恢复）。
list_users：按团队或条件分页查询用户列表。
导入
from tencentdb_agent_memory.v3 import MetadataClient
方法签名
def create_user(self, p: Dict[str, Any]) -> Dict[str, Any]
def get_user(self, query: Union[str, Dict[str, Any]]) -> Dict[str, Any]
def delete_users(self, user_ids: List[str]) -> Dict[str, Any]
def list_users(self,team_id_or_request: Union[str, Dict[str, Any], None] = None,*,pagination: Optional[Dict[str, Any]] = None,) -> Dict[str, Any]
使用示例
create_user
from tencentdb_agent_memory.v3 import MetadataClientmetadata = MetadataClient(endpoint="https://memory.tdai.tencentyun.com",api_key="sk-xxxxxxxxxxxxxxxx",service_id="tdai-mem-xxxxxxxx",)resp = metadata.create_user({"username": "alice","team_id": "team-abc",})print(resp)
get_user
# 按 ID 查询user = metadata.get_user("user-123")# 按条件查询user = metadata.get_user({"username": "alice", "team_id": "team-abc"})print(user)
delete_users
resp = metadata.delete_users(["user-123", "user-456"])print(resp)
list_users
# 按团队 ID 查询resp = metadata.list_users("team-abc")# 按条件查询（带分页）resp = metadata.list_users({"team_id": "team-abc","limit": 20,"offset": 0,})for user in resp["items"]:print(user["username"])
请求参数
create_user
参数名 | 类型 | 必填 | 描述说明 |
username | str | 是 | 用户名 |
team_id | str | 是 | 用户所属团队 ID |
get_user
参数名 | 类型 | 必填 | 描述说明 |
user_id_or_filter | str 或 Dict | 是 | 用户 ID（str）或过滤条件（Dict，含 username、team_id 等字段） |
delete_users
参数名 | 类型 | 必填 | 描述说明 |
user_ids | List[str] | 是 | 待删除的用户 ID 列表 |
list_users
参数名 | 类型 | 必填 | 描述说明 |
team_id_or_request | str 或 Dict | 是 | 团队 ID（str）或请求条件（Dict，含 team_id、limit、offset 等字段） |
pagination | Dict | 否 | 分页参数，含 limit 和 offset |
响应示例
create_user
{"user_id": "user-550e8400-e29b-41d4-a716-446655440000","username": "alice","team_id": "team-abc","created_at_ms": 1723968000000}
get_user
{"user_id": "user-123","username": "alice","team_id": "team-abc","created_at_ms": 1723900000000,"updated_at_ms": 1723968000000}
list_users
{"items": [{"user_id": "user-123","username": "alice","team_id": "team-abc","created_at_ms": 1723900000000}],"total": 1}
响应参数说明
参数名 | 类型 | 参数含义 |
user_id | str | 用户唯一标识 ID |
username | str | 用户名 |
team_id | str | 所属团队 ID |
created_at_ms | int | 创建时间，Unix 时间戳，单位为毫秒 |
updated_at_ms | int | 最后更新时间，Unix 时间戳，单位为毫秒 |
items | List[Dict] | 用户列表 |
total | int | 符合条件的用户总数 |
错误码
错误码 | 触发场景 | 处理建议 |
400 | 请求参数不合法（如 username 为空） | 检查参数是否符合约束条件 |
401 | API Key 无效或缺失 | 检查 Bearer Token 配置 |
404 | 指定用户不存在 | 确认用户 ID 是否正确 |
409 | 用户名在同一团队下已存在 | 使用不同的用户名 |
500 | 服务内部错误 | 稍后重试 |
