跳转至

创建



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

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

文档评价

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