콘텐츠로 이동

생성



POST /api/v1/super-account/create

개요

사이트 관리 콘솔 계정을 생성합니다.

호출 전 준비 및 사용 단계

External 자격 증명에 w 권한이 필요합니다. 먼저 관리 콘솔 계정 목록에서 로그인 이름을 확인한 다음, admin 또는 dev를 명확히 선택하고 강력한 비밀번호를 설정합니다. name/email/mobile은 필요에 따라 제공할 수 있으며, 워크스페이스나 일반 비즈니스 계정은 자동으로 생성되지 않습니다. 새 계정의 영구 resetPasswordAt 값은 일반적으로 -1이며, 표준 로그인 시 최초 비밀번호 재설정이 요구될 수 있습니다. 생성은 멱등 요청이 아니므로 로그인 이름이 중복되면 오류가 발생합니다. 시간 초과 후에는 먼저 계정이 생성되었는지 조회합니다. isDisable과 extend는 현재 적용되지 않으며, 비활성화가 필요하면 생성 후 별도로 활성화/비활성화를 호출합니다.

요청 헤더

파라미터 이름 유형 필수 설명
X-Df-SVersion string 원본 경로 및 요청 본문 서명 버전입니다. 생략한 뒤 이 페이지의 알고리즘을 계속 사용할 수 없습니다.
예시: v20240417
획득 또는 입력 방법: 이 페이지의 예시는 이 고정 버전을 사용하며 예시 서명 알고리즘과 함께 사용됩니다.
X-Df-Access-Key string Y 읽기 API는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 API에는 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을 이미 사용 중임 {}이(가) 이미 존재함 먼저 기존 관리 계정을 조회합니다. 업데이트가 필요하면 수정 API를 사용합니다.
500 ft.InternalServerError 데이터베이스, 캐시, 감사 또는 처리되지 않은 필드 예외; 이메일에 null/문자열이 아닌 값을 전달하거나 필드가 실제 저장 길이를 초과함 내부 오류 traceId를 보관하고 계정의 현재 정보와 상태를 확인합니다. 수정/삭제는 이미 저장된 후에 실패할 수 있습니다.

문서 평가

이 페이지가 도움이 되었나요?