创建¶
POST /api/v1/super-account/create
概述¶
创建站点管理后台账号。
调用前和使用步骤¶
需要w权限External凭据。先从管理后台账号列表检查登录名,再明确选择admin或dev并设置强密码。name/email/mobile可按需提供;不自动创建工作空间或普通业务账号。新账号持久resetPasswordAt通常为-1,标准登录可能要求首次重置密码。创建不是幂等请求,重复登录名报错;超时后先查询是否已创建。isDisable和extend目前不生效,需要禁用时在创建后单独调用启用/禁用。
请求头¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| 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字符建议不超过64。不要传null/非字符串,旧声明缺少类型检查,可能导致500。 允许 null: False $isEmail: True 例子: xxx@guance.com获取或填写方式: 填写可接收通知的有效邮箱字符串。 |
||
| extend | json | 可选JSON对象;当前ManageAccount没有对应持久字段,创建不会保存,也不返回,建议省略。 允许 null: False 例子: {}获取或填写方式: 仅为旧声明兼容,不通过此字段保存业务数据。 |
|
| isDisable | boolean | 可选布尔值;当前创建实现忽略该字段,新增仍status=0,不能依赖true创建禁用账号。 允许 null: False 可选值: [True, False] 例子: false获取或填写方式: 如需禁用,创建成功取得uuid后调用启用/禁用。 |
|
| mobile | string | 可选,省略为空;本模块仅加密保存,不执行普通业务账号的countryCode拆分/完整号码校验,null非法。 允许 null: False 例子: 13800138000获取或填写方式: 填写账号手机号字符串;未配置时省略或空字符串。 |
|
| name | string | 可选,省略为空字符串;模型列64字符,建议不超过64,null非法。 允许 null: False 例子: 示例管理员获取或填写方式: 填写账号显示昵称。 |
|
| password | string | Y | 必填原文字符串,经HTTPS传输;至少8字符且数字/大写/小写/特殊字符四类中至少三类。不是管理后台页面的RSA包装字段,null非法。 允许 null: False 例子: Example!2026a获取或填写方式: 由调用方生成安全初始密码并通过合适渠道交付账号本人。 |
| role | string | Y | 必填角色标识,推荐仅使用已定义的admin/dev。当前声明未限制枚举,其他值不具有稳定的权限语义;dev不能通过标准后台账号密码登录。 允许 null: False 例子: admin获取或填写方式: 按管理后台账号用途选择admin或dev,不使用工作空间角色UUID。 |
| username | string | Y | 必填字符串,调用方应使用非空登录名;当前声明未强制非空。存储列为128字符,建议不超过128。 允许 null: False 例子: api-doc-admin获取或填写方式: 从管理后台账号列表检查已有登录名,再指定未被占用的新值。 |
参数补充说明¶
认证见External API 签名认证。本模块管理站点管理后台账号,UUID通常为mact_;不是工作空间业务成员acnt_,也不是空间Owner。列表/详情可用r或w权限,其余需要w权限。External以sys身份执行,不套用普通后台账号对初始超级管理员的操作限制,操作前须核对目标账号与仍可登录的管理账号。创建返回在flush前取快照,id和resetPasswordAt可能null;用详情读取持久化资料。响应不包含password或passworHistory。
请求例子¶
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/create'
query = {}
data = {'username': 'api-doc-admin', 'password': 'Example!2026a', 'name': '示例管理员', 'email': 'xxx@guance.com', 'role': 'admin'}
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": null,
"uuid": "mact_example001",
"status": 0,
"creator": "sys",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例管理员",
"username": "api-doc-admin",
"email": "xxx@guance.com",
"mobile": "",
"role": "admin",
"resetPasswordAt": null,
"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.ObjectParmeterExists | 未删除账号已使用相同username | {} 已存在 |
先查现有管理账号;需要更新时使用修改接口。 |
| 500 | ft.InternalServerError | 数据库、缓存、审计或未处理字段异常;邮箱传null/非字符串或字段超过实际存储长度 | 内部错误 | 保留traceId并核对账号当前资料和状态;修改/删除可能已保存后才失败。 |