콘텐츠로 이동

목록 조회



GET /api/v1/account/list

개요

사이트에서 아직 삭제되지 않은 프런트엔드 계정과 직접 연결된 워크스페이스 역할을 페이지 단위로 조회합니다.

호출 전 준비 및 사용 단계

r 또는 w 권한의 External 자격 증명을 사용합니다. 먼저 닉네임 또는 이메일로 범위를 좁힌 다음 content.data를 페이지별로 읽고, 이후 content.data[].uuid로 계정 상세를 호출합니다. 정상 계정과 비활성화된 계정이 모두 포함되며 레코드 id 기준 내림차순으로 정렬됩니다. 필터 조건이 고정되어 있어도 계정이 추가되거나 삭제되면 페이지 조회 결과에 영향을 줄 수 있습니다. 페이지 정보는 content.pageInfo에 있습니다.

요청 헤더

파라미터 이름 유형 필수 설명
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.totalCount와 함께 페이지 조회를 중지합니다.
pageSize integer 페이지당 개수이며 기본값 10, 최댓값 100입니다.
null 허용: False
$maxValue: 100
$minValue: 1
예시: 10
획득 또는 입력 방법: 클라이언트 요구에 따라 1~100 사이에서 선택합니다.
search string name 또는 email 기준 포함 일치로 검색하며 username은 검색하지 않습니다. 생략하거나 빈 문자열이면 필터링하지 않습니다.
null 허용: False
예시: 示例成员
획득 또는 입력 방법: 계정의 name 닉네임 또는 email에서 알려진 키워드를 사용합니다.

파라미터 추가 설명

사이트 수준 External API 자격 증명을 사용하며 인증 방식은 External API 서명 인증을 참고하십시오. 다음 예시는 v20240417 서명 버전을 사용하며, 서명 경로, Query 인코딩 및 원본 요청 본문은 실제 전송 내용과 완전히 일치해야 합니다. 반환되는 계정 정보에는 password 필드가 포함되지 않으며, mfaSecret은 고정 마스크일 뿐 로그인에 사용할 수 있는 키가 아닙니다. 목록의 wsInfo는 직접 연결된 항목이 없으면 null입니다. 목록은 userIconUrl을 보완하지 않으며, 아바타는 상세 조회에서 가져올 수 있습니다.

요청 예시

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/account/list'
query = {'search': '示例成员', 'pageIndex': 1, 'pageSize': 10}
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, Content-Type은 application/json이며 통합 응답 셸을 사용합니다. 비즈니스 데이터는 content에 있으며, External API는 declaration을 자동으로 추가하지 않고 목록 페이지 정보는 content.pageInfo에 유지됩니다.

필드 유형 설명
content object 목록 및 페이지 정보 객체입니다.
content.data 객체 배열 현재 페이지의 계정이며 일치 항목이 없으면 빈 배열을 반환합니다.
content.data[].id integer 사이트 내 계정 레코드 순번으로 정보 제공용으로만 반환됩니다. 다른 API 호출 시에는 uuid를 사용합니다.
content.data[].uuid string 계정 UUID로 이후 조회, 수정, 비활성화, 삭제 시 이 필드를 사용합니다.
content.data[].status integer 계정 상태: 0 정상, 2 비활성화. 목록에서는 3(삭제됨)을 필터링하며 다른 과거 상태가 나타날 수 있습니다.
content.data[].creator string 생성 주체 식별자이며 External 생성은 일반적으로 SYS입니다.
content.data[].updator string 최근 수정 주체 식별자이며 아직 수정된 적이 없으면 비어 있을 수 있습니다.
content.data[].createAt number 생성 시간, Unix 초입니다.
content.data[].updateAt number 업데이트 시간, Unix 초이며 아직 업데이트 시간이 없으면 -1일 수 있습니다.
content.data[].deleteAt number 상태 작업 시간 필드로 초기값은 일반적으로 -1입니다. 활성화/비활성화 시에도 이 값이 기록되므로 이것만으로 삭제 여부를 판단하지 말고 status를 사용해야 합니다.
content.data[].name string 표시 닉네임입니다.
content.data[].username string 로그인 계정 이름입니다. 서드파티 계정은 비어 있거나 다른 계정과 중복될 수 있습니다.
content.data[].email string 계정 연락 이메일입니다. 생성 시 비어 있고 username이 이메일 형식이면 username으로 보완됩니다.
content.data[].mobile string 휴대폰 번호의 로컬 번호로 복호화되어 표시되며 국가 코드는 포함하지 않습니다. 설정하지 않으면 빈 문자열입니다.
content.data[].countryCode string 휴대폰 번호의 국가/지역 코드 순수 숫자 문자열(예: 86)입니다. 설정하지 않으면 빈 문자열입니다.
content.data[].exterId string 서드파티 신원 시스템의 고유 ID이며 로컬 계정은 일반적으로 비어 있습니다.
content.data[].extend object 또는 null 기존 확장 정보로 user_icon 아바타 주소를 포함할 수 있습니다. 이 API 생성 시 전달한 extend는 현재 저장되지 않으며 수정 API도 이 입력 파라미터를 공개하지 않습니다.
content.data[].extend.user_icon string 선택적 아바타 URL 또는 정적 리소스 파일명입니다. 기존 정보를 읽을 때 나타날 수 있으며 이 페이지에서 쓸 수 있는 파라미터가 아닙니다.
content.data[].source string 신원 출처 식별자로 예: local, unknown, oidc, ldap이며 agent 등 과거 내부 출처도 존재할 수 있습니다.
content.data[].nameSpace string 신원 네임스페이스로 External 생성 시 기본값은 비어 있습니다. 이 모듈의 공개 파라미터로는 설정할 수 없습니다.
content.data[].isUsed integer 또는 boolean 계정 사용 여부 표시입니다.
content.data[].agreeTerms integer 약관 동의 표시입니다.
content.data[].canaryPublic boolean 카나리 표시입니다.
content.data[].enableMFA boolean MFA 사용 여부입니다.
content.data[].mfaSecret string 고정 마스크 *********************이며 사용 가능한 MFA 키를 포함하지 않습니다.
content.data[].language string 언어 식별자: zh, en, zh-hant, id, ja, ko.
content.data[].tokenHoldTime integer 계정 무작업 세션 유지 시간(초)입니다. 새 계정은 사이트 보안 세션 구성에 따라 초기화되며 예시 값으로 고정된다는 보장은 없습니다.
content.data[].tokenMaxValidDuration integer 계정 세션 최대 유효 기간(초)입니다. 새 계정은 사이트 보안 세션 구성에 따라 초기화됩니다.
content.data[].timezone string 시간대 식별자이며 설정하지 않으면 비어 있습니다.
content.data[].attributes object SSO 동기화 속성 KV 객체로 이후 SSO 로그인 시 덮어써질 수 있습니다. 키와 값은 연동 측에서 정의합니다.
content.data[].attributes.{속성 이름} 임의 JSON 값 사용자 정의 속성 값이며 문자열 사용을 권장합니다. 예: 部门=研发部.
content.data[].customAttributes object 비즈니스 측에서 관리하는 속성 KV 객체입니다.
content.data[].customAttributes.{속성 이름} 임의 JSON 값 비즈니스 사용자 정의 값이며 문자열 사용을 권장합니다. 예: costCenter=CC-1001.
content.data[].statusPageSubs integer 상태 페이지 구독 표시입니다.
content.data[].defaultWorkspace string 계정 기본 워크스페이스 UUID이며 구성하지 않으면 비어 있습니다.
content.data[].brandKey string 계정의 현재 브랜드 식별자로 사이트에서 허용된 브랜드 집합에 따라 결정됩니다.
content.data[].scheduleMobile string 스케줄 전용 휴대폰 번호의 로컬 번호이며 설정하지 않으면 비어 있습니다.
content.data[].scheduleEmail string 스케줄 전용 이메일이며 설정하지 않으면 비어 있습니다.
content.data[].ifScheduleMobileEnable boolean 스케줄 휴대폰 번호 사용 여부입니다.
content.data[].ifScheduleEmailEnable boolean 스케줄 이메일 사용 여부입니다.
content.data[].accountStatus string 계정 추가 상태 식별자이며 설정하지 않으면 비어 있습니다.
content.data[].wsInfo 객체 배열 또는 null 계정에 직접 바인딩된 활성 워크스페이스 및 역할입니다. 관리 백엔드 그룹에서 상속된 권한만 있는 경우는 포함하지 않습니다.
content.data[].wsInfo[].uuid string 워크스페이스 UUID입니다.
content.data[].wsInfo[].name string 워크스페이스 이름입니다.
content.data[].wsInfo[].roles 객체 배열 해당 계정에 직접 연결된 유효 역할입니다.
content.data[].wsInfo[].roles[].uuid string 역할 UUID(예: owner)입니다.
content.data[].wsInfo[].roles[].name string 역할 표시 이름입니다.
content.data[].wsInfo[].roles[].workspaceUUID string 역할 정의가 속한 워크스페이스 UUID이며 시스템 공용 역할은 빈 문자열입니다.
content.pageInfo.pageIndex integer 현재 페이지 번호입니다.
content.pageInfo.pageSize integer 페이지당 개수입니다.
content.pageInfo.count integer 이 페이지의 항목 수입니다.
content.pageInfo.totalCount integer 현재 필터 기준 전체 항목 수입니다.
{
  "code": 200,
  "content": {
    "data": [
      {
        "id": 1001,
        "uuid": "acnt_example001",
        "status": 0,
        "creator": "SYS",
        "updator": "",
        "createAt": 1785427200,
        "deleteAt": -1,
        "updateAt": -1,
        "name": "示例成员",
        "username": "xxx@guance.com",
        "email": "xxx@guance.com",
        "mobile": "",
        "countryCode": "",
        "exterId": "",
        "extend": null,
        "source": "local",
        "nameSpace": "",
        "isUsed": 0,
        "agreeTerms": 0,
        "canaryPublic": false,
        "enableMFA": false,
        "mfaSecret": "*********************",
        "language": "zh",
        "tokenHoldTime": 86400,
        "tokenMaxValidDuration": 604800,
        "timezone": "",
        "attributes": {
          "部门": "研发部"
        },
        "customAttributes": {
          "costCenter": "CC-1001"
        },
        "statusPageSubs": 0,
        "defaultWorkspace": "",
        "brandKey": "guance",
        "scheduleMobile": "",
        "scheduleEmail": "",
        "ifScheduleMobileEnable": false,
        "ifScheduleEmailEnable": false,
        "accountStatus": "",
        "wsInfo": [
          {
            "uuid": "wksp_example001",
            "name": "示例空间",
            "roles": [
              {
                "uuid": "general",
                "name": "普通成员",
                "workspaceUUID": ""
              }
            ]
          }
        ]
      }
    ],
    "pageInfo": {
      "pageIndex": 1,
      "pageSize": 10,
      "count": 1,
      "totalCount": 1
    }
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

일치하는 계정이 없을 때:

{
  "code": 200,
  "content": {
    "data": [],
    "pageInfo": {
      "pageIndex": 1,
      "pageSize": 10,
      "count": 0,
      "totalCount": 0
    }
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

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

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 파라미터 파싱 실패 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다.
500 ft.InternalServerError 데이터베이스, 캐시, 비동기 작업 전달 또는 명시적으로 처리되지 않은 필드 예외 내부 오류 traceId를 저장하고 관리자에게 문의하십시오. 쓰기 요청은 먼저 계정 현재 상태를 다시 조회하여 확인한 후 재시도 여부를 결정해야 하며, 500을 곧바로 미적용으로 간주해서는 안 됩니다.

문서 평가

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