콘텐츠로 이동

목록



GET /api/v1/super-account/list

개요

사이트 관리 백엔드 계정 및 MFA 바인딩 상태를 페이지네이션으로 조회합니다.

호출 전 및 사용 단계

삭제되지 않은 모든 관리 계정을 조회하며, 비활성화된 계정도 포함하고 id 내림차순으로 정렬합니다. search는 로그인 이름, 닉네임 또는 이메일의 포함 일치로 검색하며 앞뒤 공백을 제거합니다. 기본값은 pageIndex=1/pageSize=20이고 최대 100입니다. 목록에서는 내부 mfaSecret을 제거합니다. creatorAccount는 확인 가능한 생성자 로그인 이름이며, sys 생성인 경우 보통 비어 있습니다. id=1인 레코드만 추가로 isSuperAdministrator=true를 반환하고 다른 레코드에서는 생략됩니다. enableMFA는 현재 MFA 설정과 바인딩 상태에 따라 계산되며, 사용자 지정 MFA 서비스 확인에 실패하면 해당 필드가 생략될 수 있으므로 false로 간주해서는 안 됩니다.

요청 헤더

파라미터 이름 유형 필수 설명
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 초 문자열을 생성합니다.

Query 요청 파라미터

파라미터 이름 유형 필수 설명
pageIndex integer 기본값 1, 최소 1.
null 허용: False
$minValue: 1
예시: 1
가져오기 또는 입력 방법: 처음에는 1부터 시작하고 content.pageInfo에 따라 다음 페이지로 진행합니다.
pageSize integer 기본값 20, 최대 100.
null 허용: False
$maxValue: 100
$minValue: 1
예시: 20
가져오기 또는 입력 방법: 클라이언트 필요에 따라 1~100을 선택합니다. 사용자 지정 MFA 확인이 계정별로 실행될 수 있으므로 매번 작업량을 의도치 않게 늘리지 않도록 합니다.
search string 선택 사항이며 생략하거나 공백이면 필터링하지 않습니다. 휴대폰 번호로는 검색하지 않습니다.
null 허용: False
예시: api-doc
가져오기 또는 입력 방법: 로그인 이름, 닉네임 또는 이메일의 키워드를 사용합니다.

파라미터 추가 설명

인증은 External API 서명 인증을 참조하십시오. 이 모듈은 사이트 관리 백엔드 계정을 관리하며 UUID는 보통 mact_입니다. 워크스페이스 비즈니스 멤버 acnt_가 아니고 워크스페이스 Owner도 아닙니다. 목록/상세는 r 또는 w 권한을 사용할 수 있고, 나머지는 w 권한이 필요합니다. External은 sys 자격으로 실행되며, 일반 백엔드 계정의 초기 슈퍼 관리자에 대한 작업 제한을 적용하지 않습니다. 작업 전에 대상 계정과 여전히 로그인할 수 있는 관리 계정을 확인해야 합니다. 사용자 지정 MFA 확인 예외는 보통 계정별로 캐치되며, 전체 목록을 반드시 실패하게 하지는 않습니다.

요청 예시

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/list'
query = {'search': 'api-doc', 'pageIndex': 1, 'pageSize': 20}
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.data 객체 배열 현재 페이지의 삭제되지 않은 관리 계정.
content.data[].id integer 또는 null 관리 계정 레코드 일련번호; id=1은 초기 슈퍼 관리자입니다. 생성 시 반환 스냅샷은 null일 수 있으며 호출 시 uuid를 사용합니다.
content.data[].uuid string 관리 계정 UUID, 보통 mact_ 접두사.
content.data[].status integer 계정 상태: 0 활성화, 2 비활성화, 3 삭제됨; 목록과 상세에서는 3을 제외하며, 2는 여전히 반환될 수 있습니다.
content.data[].creator string 생성 주체, External은 보통 sys.
content.data[].updator string 최근 업데이트 주체, 업데이트되지 않은 경우 비어 있을 수 있습니다.
content.data[].createAt integer 생성 Unix 초.
content.data[].deleteAt number 삭제 Unix 초, 삭제되지 않은 경우 보통 -1.
content.data[].updateAt number 업데이트 Unix 초; 일부 수정은 updator만 업데이트하므로 이 값만으로 정보 변경 여부를 판단할 수 없습니다.
content.data[].name string 표시 닉네임.
content.data[].username string 관리 백엔드 로그인 이름.
content.data[].email string 이메일, 구성되지 않은 경우 비어 있을 수 있습니다.
content.data[].mobile string 관리 계정 휴대폰 번호를 복호화하여 표시하며, 설정되지 않은 경우 비어 있습니다. 별도 countryCode 필드는 없습니다.
content.data[].role string 관리 백엔드 역할 식별자, 정의된 용도는 admin/dev입니다. dev는 표준 백엔드 계정 비밀번호 로그인 경로에서 거부되므로 일반 읽기 전용 역할로 간주할 수 없습니다.
content.data[].resetPasswordAt integer 또는 null 최근 비밀번호 재설정 Unix 초; 생성 스냅샷은 null일 수 있고 영속 초기값은 보통 -1이며, 표준 백엔드 최초 재설정 안내를 트리거합니다.
content.data[].creatorAccount string 생성자 관리 계정 로그인 이름, 찾을 수 없거나 sys 자격인 경우 보통 비어 있습니다.
content.data[].enableMFA boolean MFA 바인딩 상태, 계산 실패 시 생략될 수 있으며 누락을 false로 이해해서는 안 됩니다.
content.data[].isSuperAdministrator boolean 초기 슈퍼 관리자 id=1인 경우에만 true를 반환하며, 다른 계정에서는 보통 생략됩니다.
content.pageInfo.pageIndex integer 현재 페이지 번호.
content.pageInfo.pageSize integer 페이지당 항목 수.
content.pageInfo.count integer 이 페이지 항목 수.
content.pageInfo.totalCount integer 삭제되지 않았고 검색 조건을 충족하는 총 개수.
{
  "code": 200,
  "content": {
    "data": [
      {
        "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,
        "creatorAccount": "",
        "enableMFA": false
      }
    ],
    "pageInfo": {
      "pageIndex": 1,
      "pageSize": 20,
      "count": 1,
      "totalCount": 1
    }
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.

이 표는 현재 External SYS 분기에서 도달할 수 있는 비즈니스 오류만 명시합니다. 일반 백엔드의 실제 계정에 대한 자체 보호 오류는 그대로 적용하지 않습니다. 데이터베이스/캐시 등 일반 5xx는 전역에서 ft.InternalServerError로 통일되며, 상태 또는 정보가 이미 저장된 후에 실패할 수 있습니다.

HTTP 상태 errorCode 트리거 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 파라미터 파싱 실패 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다.
500 ft.InternalServerError 데이터베이스, 캐시, 감사 또는 처리되지 않은 필드 예외 내부 오류 traceId를 보존하고 계정의 현재 정보와 상태를 확인합니다. 수정/삭제는 이미 저장된 후에 실패할 수 있습니다.

문서 평가

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