跳转至

修改



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 请求参数

参数名 类型 必选 说明
email 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并核对账号当前资料和状态;修改/删除可能已保存后才失败。

文档评价

文档内容是否对您有帮助?