수정¶
POST /api/v1/super-account/{account_uuid}/modify
개요¶
관리 콘솔 계정의 프로필, 역할 또는 비밀번호를 수정합니다.
호출 전 및 사용 단계¶
External 자격 증명에 대한 w 권한이 필요합니다. 먼저 관리 콘솔 계정 상세로 기존 프로필을 백업하세요. 필드를 생략하면 유지되며, 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 | 읽기 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 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| string | 선택적 이메일 문자열이며 생략하면 유지됩니다. 명시적 값은 유효한 이메일이어야 하며 빈 문자열로 비울 수 없습니다. 64자 이내를 권장하며 null/비문자열을 전달하지 마세요. 500이 발생할 수 있습니다. null 허용: False $isEmail: True 예시: xxx@guance.com가져오기 또는 입력 방법: 알림을 받을 수 있는 유효한 이메일 문자열을 입력합니다. |
||
| extend | json | 선택적 객체이며 현재 수정 시 매핑 컬럼에 저장되지 않고 해당 필드도 반환되지 않습니다. null 허용: False 예시: {}가져오기 또는 입력 방법: 이전 선언 호환 필드이며 현재 영속화되지 않으므로 생략을 권장합니다. |
|
| exterId | string | 선택적 문자열이며 이 API를 통해 외부 ID 바인딩을 설정하지 않으며 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를 보관하고 계정의 현재 프로필 및 상태를 확인합니다. 수정/삭제가 저장된 후에 실패할 수 있습니다. |