조회¶
GET /api/v1/super-account/{account_uuid}/get
개요¶
지정된 삭제되지 않은 관리 콘솔 계정의 정보를 조회합니다.
호출 전 준비 및 사용 단계¶
External 자격 증명에 r 또는 w 권한이 필요합니다. 경로 UUID는 관리 콘솔 계정 목록에서 가져오며, 활성화 또는 비활성화된 계정을 조회할 수 있습니다. 삭제되었거나 존재하지 않는 경우 찾을 수 없음이 반환됩니다. 상세 정보는 엔터티 정보이며, 목록에서 계산되는 enableMFA, creatorAccount 또는 isSuperAdministrator를 포함하지 않습니다. MFA 바인딩 상태가 필요하면 목록과 함께 확인해야 하며, 내부 mfaSecret 필드를 사용하여 자체 인증해서는 안 됩니다.
경로 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| 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 초 문자열을 생성합니다. |
파라미터 추가 설명¶
인증은 External API 서명 인증을 참고하세요. 이 모듈은 사이트 관리 콘솔 계정을 관리하며, UUID는 일반적으로 mact_입니다. 워크스페이스 비즈니스 멤버 acnt_가 아니며, 공간 Owner도 아닙니다. 목록/상세는 r 또는 w 권한을 사용할 수 있으며, 나머지는 w 권한이 필요합니다. External은 sys 신원으로 실행되며, 일반 콘솔 계정의 초기 슈퍼 관리자에 대한 작업 제한이 적용되지 않습니다. 작업 전에 대상 계정과 여전히 로그인 가능한 관리 계정을 확인해야 합니다. password와 passworHistory는 반환되지 않습니다. 내부 호환 필드 mfaSecret은 클라이언트 통합 필드로 사용되지 않습니다.
요청 예시¶
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 = 'GET'
path = '/api/v1/super-account/mact_example001/get'
query = {}
data = None
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": "",
"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 | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인합니다. |
| 404 | ft.NotFoundAccount | 상세 조회에서 대상 계정이 존재하지 않거나 삭제됨 | 지정된 계정을 찾을 수 없음 | 관리 콘솔 계정 목록에서 유효한 mact_uuid를 가져와야 하며, 비즈니스 계정 UUID는 사용할 수 없습니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시, 감사 또는 처리되지 않은 필드 예외 | 내부 오류 | traceId를 보관하고 계정의 현재 정보와 상태를 확인합니다. 수정/삭제는 이미 저장된 후에 실패할 수 있습니다. |