修改¶
POST /api/v1/super-account/{account_uuid}/modify
概述¶
修改后台账号资料、角色或密码。
调用前和使用步骤¶
需要w权限External凭据。先用管理后台账号详情备份现有资料;省略字段保留,password空字符串也保留密码,mobile空字符串清空。extend/exterId为未生效的兼容声明字段,不要用于业务绑定。可操作未删除账号,包括禁用账号。修改禁用账号时,资料可能先保存,再由缓存刷新抛出401 AccountDisabled;收到401也应先查现态。目标不存在时此SYS分支可能返回500,不能承诺与详情一样404。当前External不做普通后台账号对初始超级管理员的保护,请先核对目标。
路由参数¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| account_uuid | string | Y | 管理后台账号UUID,不是普通业务账号UUID。 例子: mact_example001获取或填写方式: 从管理后台账号列表的content.data[].uuid取得。 |
请求头¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| X-Df-SVersion | string | 原始路径与请求体签名版本;不能省略后继续沿用本页算法。 例子: v20240417获取或填写方式: 本页示例使用此固定版本,与示例签名算法配套。 |
|
| X-Df-Access-Key | string | Y | 读接口可用r或w凭据,写接口需要w凭据。 例子: <external-access-key>获取或填写方式: 由站点管理员分配 External API AK,不能使用工作空间 OpenAPI Key。 |
| X-Df-Nonce | string | Y | 临时流水号;失败重发也生成新值并重算签名。 例子: 97d275ee9f774315a7885ba7347acbd9获取或填写方式: 每次请求重新生成uuid.uuid4().hex。 |
| X-Df-Signature | string | Y | 对大写方法、nonce、原始完整路径、timestamp和原始UTF-8请求体按空格拼接后做HMAC-SHA256,取hex摘要。 例子: <hmac-sha256-hex>获取或填写方式: 按External API 签名认证使用配套SK计算,完整可运行模板见下方。 |
| X-Df-Timestamp | string | Y | 必须在站点配置的签名有效时间窗内,不能复用示例时间。 例子: 1785427200获取或填写方式: 发送时用 str(int(time.time())) 生成当前Unix秒字符串。 |
Body 请求参数¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| string | 可选邮箱字符串,省略保留;显式值须有效邮箱,不能用空字符串清空。建议64字符以内,不要传null/非字符串,可能触发500。 允许 null: False $isEmail: True 例子: xxx@guance.com获取或填写方式: 填写可接收通知的有效邮箱字符串。 |
||
| extend | json | 可选对象,当前修改不保存到映射列,也不返回对应字段。 允许 null: False 例子: {}获取或填写方式: 旧声明兼容字段,当前不持久化,建议省略。 |
|
| exterId | string | 可选字符串;不会通过此接口建立外部身份绑定,null非法。 允许 null: False 例子: legacy-id获取或填写方式: 旧声明兼容参数,当前不读取、不持久化,建议省略。 |
|
| mobile | string | 可选,省略保留;不执行countryCode拆分/号码校验,null非法。 允许 null: False 例子: 13800138000获取或填写方式: 填写新手机号字符串,或空字符串清空。 |
|
| name | string | 可选,省略保留;建议64字符以内,null非法。 允许 null: False 例子: 示例管理员新昵称获取或填写方式: 按需更新显示昵称。 |
|
| password | string | 可选,省略或空字符串均不改密码;非空时按强度校验并更新resetPasswordAt。启用密码轮换策略时不能与最近配置次数内的密码重复,null非法。 允许 null: False 例子: Changed!2026a获取或填写方式: 填写新强密码;不需改密码时省略。 |
|
| role | string | 可选,省略保留。设为dev会尝试清理默认管理Token缓存,并使标准后台登录被拒;不能把dev视为普通只读账号,null非法。 允许 null: False 例子: admin获取或填写方式: 仅使用该后台定义的admin/dev;不是工作空间角色。 |
|
| username | string | 可选,省略保留;与其他未删除账号登录名不能重复,建议128字符以内且不要传空串,以免清空登录名影响后续登录;当前声明未强制非空,null非法。 允许 null: False 例子: api-doc-admin-renamed获取或填写方式: 从管理后台账号详情读取当前登录名,按需换成不重复的新值。 |
参数补充说明¶
认证见External API 签名认证。本模块管理站点管理后台账号,UUID通常为mact_;不是工作空间业务成员acnt_,也不是空间Owner。列表/详情可用r或w权限,其余需要w权限。External以sys身份执行,不套用普通后台账号对初始超级管理员的操作限制,操作前须核对目标账号与仍可登录的管理账号。修改会刷新账号资料缓存。非空新密码更新重置时间;role=dev清理当前默认管理Token缓存模式。站点若自定义了Token key模板,需管理员核对实际清理效果。
请求例子¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 替换为目标站点地址及管理员分配的 External API AK/SK。
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/super-account/mact_example001/modify'
query = {}
data = {'name': '示例管理员新昵称'}
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
响应¶
HTTP 200,application/json统一外壳;External不自动加入declaration,列表分页位于content.pageInfo。
| 字段 | 类型 | 说明 |
|---|---|---|
| content.id | integer 或 null | 管理账号记录序号;id=1为初始超级管理员。创建返回快照可为null,调用使用uuid。 |
| content.uuid | string | 管理账号UUID,通常mact_前缀。 |
| content.status | integer | 账号状态:0启用、2禁用、3已删除;列表和详情排除3,仍可返回2。 |
| content.creator | string | 创建身份,External通常sys。 |
| content.updator | string | 最近更新身份,未更新时可能为空。 |
| content.createAt | integer | 创建Unix秒。 |
| content.deleteAt | number | 删除Unix秒,未删除通常-1。 |
| content.updateAt | number | 更新Unix秒;部分修改只更新updator,不能仅靠该值判断资料是否改变。 |
| content.name | string | 显示昵称。 |
| content.username | string | 管理后台登录名。 |
| content.email | string | 邮箱,未配置可为空。 |
| content.mobile | string | 管理账号手机号解密后展示,未设置为空;没有单独countryCode字段。 |
| content.role | string | 管理后台角色标识,已定义用法为admin/dev;dev在标准后台账号密码登录链路被拒,不能视为普通只读角色。 |
| content.resetPasswordAt | integer 或 null | 最近重置密码Unix秒;创建快照可null,持久初值通常-1,会触发标准后台首次重置提示。 |
| content.mfaSecret | string | 现有实现可能返回的内部MFA绑定字段,不供业务集成使用;勿据此构造认证,实际值不应记录或外传。示例为空不代表既有账号均为空。 |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "mact_example001",
"status": 0,
"creator": "sys",
"updator": "sys",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例管理员新昵称",
"username": "api-doc-admin",
"email": "xxx@guance.com",
"mobile": "",
"role": "admin",
"resetPasswordAt": -1,
"mfaSecret": ""
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
错误响应¶
鉴权、限流和公共请求错误参见公共错误定义。
本表只承诺当前External SYS分支可达的业务错误;普通后台真实账号的自保护错误不直接照搬。数据库/缓存等普通5xx经全局统一为ft.InternalServerError,状态或资料可能已保存后才失败。
| HTTP 状态 | errorCode | 触发条件 | 消息或响应说明 | 处理方式 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 请求字段缺失,或字段值违反声明的校验条件 | 参数解析失败 | 核对参数位置、字段名、类型和取值。 |
| 400 | ft.RequestJsonFormatError | 请求 JSON 语法无效 | 请求 JSON 格式错误 | 按 content.reason、line、column 修正 JSON。 |
| 400 | ft.JsonFormatError | JSON顶层不是对象 | 部分 json 文件格式错误 | 按表格提交JSON对象。 |
| 400 | ft.InvalidPasswordRule | 创建密码为空或弱口令,或修改提供的非空密码不符合规则 | 无效的密码规则 | 至少8字符,数字/大写/小写/特殊字符四类中至少三类。 |
| 400 | ft.NameEamilExist | username被其他未删除管理账号占用 | name/email 已存在 | 选择不重复的登录名;此分支实际检查username,不是检查邮箱唯一性。 |
| 406 | ft.PasswordRepeated | 密码轮换策略开启且新密码与最近配置次数内密码重复 | 新密码不能与之前的{}次密码相同 | 选择未使用过的新强密码,比较次数由站点安全策略决定。 |
| 401 | ft.AccountDisabled | 目标账号禁用,资料提交后刷新缓存被拒 | 当前用户已被禁用 | 先查询确认修改结果,按授权流程启用账号后再处理,勿直接重复改密。 |
| 401 | ft.AbnormalUserOrDelete | 资料提交后刷新缓存时账号已不存在/删除 | 当前用户不存在/或已删除 | 重新核对账号生命周期状态。 |
| 500 | ft.InternalServerError | 数据库、缓存、审计或未处理字段异常;目标不存在/已删除,邮箱传null/非字符串,或存储字段长度异常 | 内部错误 | 保留traceId并核对账号当前资料和状态;修改/删除可能已保存后才失败。 |