목록¶
GET /api/v1/workspace/{workspace_uuid}/member/list
개요¶
워크스페이스의 활성 멤버와 해당 멤버의 직접 역할 및 상속 역할을 페이지 단위로 조회합니다.
호출 전 및 사용 단계¶
r 또는 w 권한의 External 자격 증명이 필요합니다. 목록에는 직접 멤버와 백엔드 그룹에서 상속된 멤버가 포함되며, status=0인 계정만 반환됩니다. 또한 nameSpace는 비어 있거나 해당 워크스페이스에 구성된 SSO 네임스페이스여야 합니다. 계정이 비활성화되었거나 삭제되었거나 SSO 네임스페이스가 일치하지 않으면 표시되지 않으며, 조회되지 않는다는 이유만으로 관계가 더 이상 존재하지 않는다고 판단해서는 안 됩니다. 반환되는 역할에는 roles의 직접 역할, mgroups의 백엔드 그룹 상속 역할, member_group의 팀 상속 역할이 포함됩니다. 상속 역할은 직접 역할을 대체하는 대상이 아닙니다. 계정의 전역 name을 기준으로 오름차순 정렬하며, 가입 시간 기준으로 정렬하지 않습니다. search는 전역 닉네임, 이메일, 워크스페이스 닉네임을 동시에 매칭하지만, 이 응답 구조에는 별도의 acntWsNickname 필드가 없습니다. 페이지 정보는 content.pageInfo에 있습니다. 결과가 없으면 data=[]이며, 잘못된 워크스페이스 UUID도 빈 목록을 반환할 수 있으므로 먼저 대상 워크스페이스를 확인해야 합니다.
라우트 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| workspace_uuid | string | Y | 대상 워크스페이스 UUID이며, 먼저 활성 상태와 사이트를 확인합니다. 예: wksp_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 초 문자열을 생성합니다. |
Query 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| pageIndex | integer | 선택 사항이며 기본값은 1이고 최솟값은 1입니다. null 허용: False $minValue: 1 예: 1획득 또는 입력 방법: 1부터 시작하여 content.pageInfo와 함께 이후 페이지를 순서대로 읽습니다. |
|
| pageSize | integer | 선택 사항이며 기본값은 10이고 최댓값은 100입니다. null 허용: False $maxValue: 100 $minValue: 1 예: 10획득 또는 입력 방법: 클라이언트 표시에 따라 1~100 사이에서 선택합니다. |
|
| search | string | 선택 사항이며, 앞뒤 공백을 제거한 후 포함 매칭을 수행합니다. 생략하거나 공백만 있으면 필터링하지 않습니다. username은 검색하지 않습니다. null 허용: False 예: 示例成员획득 또는 입력 방법: 멤버의 전역 닉네임, 이메일 또는 워크스페이스 닉네임에 포함된 키워드를 입력합니다. |
파라미터 추가 설명¶
인증은 External API 서명 인증을 참조하십시오. 이 페이지의 예시는 v20240417을 사용하며, 원본 전체 경로, Query, 요청 본문 서명 알고리즘과 함께 사용됩니다. 이 모듈은 지정된 워크스페이스의 멤버 관계 또는 역할을 조작하며, 계정 자체를 생성하지 않습니다. 쓰기 요청이 실패하면 먼저 멤버와 역할의 현재 상태를 확인한 후 재시도 여부를 결정해야 합니다. 멤버 목록에는 password, mobile, 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/workspace/wksp_example001/member/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, application/json 통합 래퍼이며 비즈니스 데이터는 content에 있습니다. External은 declaration에 자동으로 추가되지 않으며, 목록 페이지네이션은 content.pageInfo를 유지합니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.data | 객체 배열 | 현재 페이지의 활성 멤버입니다. 결과가 없으면 빈 배열입니다. |
| content.data[].id | integer | 사이트 내 계정 레코드 일련번호이며, 참고 자료로만 반환됩니다. 다른 API를 호출할 때는 uuid를 사용합니다. |
| content.data[].uuid | string | 계정 UUID이며, 이후 조회, 수정, 비활성화, 삭제 시 이 필드를 사용합니다. |
| content.data[].status | integer | 이 목록은 status=0인 활성 계정만 반환합니다. |
| 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[].countryCode | string | 휴대폰 번호의 국가/지역 코드 숫자만으로 된 문자열입니다(예: 86). 설정하지 않으면 빈 문자열입니다. |
| content.data[].exterId | string | 타사 ID 시스템의 고유 ID입니다. 로컬 계정은 일반적으로 비어 있습니다. |
| content.data[].extend | object 또는 null | 계정의 기존 확장 자료이며 user_icon 아바타 주소를 포함할 수 있습니다. 이 API는 읽기만 하며 멤버 관계 파라미터로 업데이트하지 않습니다. |
| content.data[].extend.user_icon | string | 선택적 아바타 URL 또는 정적 리소스 파일 이름입니다. 기존 자료를 읽을 때 나타날 수 있으며, 이 페이지에서 쓸 수 있는 파라미터가 아닙니다. |
| content.data[].source | string | ID 출처 식별자입니다. 예: local, unknown, oidc, ldap. agent 등 과거 내부 출처가 존재할 수도 있습니다. |
| content.data[].nameSpace | string | ID 네임스페이스입니다. External 생성 시 기본값은 비어 있으며, 이 모듈의 공개 파라미터로는 설정할 수 없습니다. |
| content.data[].isUsed | integer 또는 boolean | 계정 사용 여부 표시입니다. |
| content.data[].agreeTerms | integer | 약관 동의 표시입니다. |
| content.data[].canaryPublic | boolean | 카나리 표시입니다. |
| content.data[].enableMFA | boolean | 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[].roles | 객체 배열 | 이 워크스페이스에서 계정의 직접 역할 요약입니다. 상속 역할은 각각 mgroups/member_group에 있습니다. |
| content.data[].roles[].uuid | string | 역할 UUID 또는 내장 역할 식별자입니다. |
| content.data[].roles[].name | string | 역할 표시 이름입니다. |
| content.data[].enablePersonalAPIKey | integer | 개인 API Key 허용 여부입니다. 1은 허용, 0은 비허용입니다. Owner/관리자 역할과 사용자 지정 설정을 기준으로 계산하며 상속 역할을 포함합니다. |
| content.data[].mgroups | 객체 배열 | 관리 백엔드 그룹에서 부여한 워크스페이스 역할입니다. |
| content.data[].mgroups[].uuid | string | 백엔드 그룹 UUID이며, 일반적으로 mgroup_ 접두사를 사용합니다. |
| content.data[].mgroups[].name | string | 백엔드 그룹 이름입니다. |
| content.data[].mgroups[].roles | 객체 배열 | 이 백엔드 그룹을 통해 상속된 역할입니다. |
| content.data[].mgroups[].roles[].uuid | string | 역할 UUID 또는 내장 역할 식별자입니다. |
| content.data[].mgroups[].roles[].name | string | 역할 표시 이름입니다. |
| content.data[].member_group | 객체 배열 | 계정이 속한 이 워크스페이스의 팀 및 팀 관련 역할입니다. |
| content.data[].member_group[].uuid | string | 워크스페이스 팀 UUID이며, 일반적으로 group_ 접두사를 사용합니다. |
| content.data[].member_group[].name | string | 팀 이름입니다. |
| content.data[].member_group[].roles | 객체 배열 | 이 팀을 통해 상속된 역할 요약입니다. |
| content.data[].member_group[].roles[].uuid | string | 역할 UUID 또는 내장 역할 식별자입니다. |
| content.data[].member_group[].roles[].name | string | 역할 표시 이름입니다. |
| content.data[].userType | string | nameSpace가 비어 있지 않으면 saml, 그렇지 않으면 common입니다. 이 필드는 source와 같지 않으며, 모든 타사 계정 유형을 판단하는 데 사용할 수 없습니다. |
| content.data[].userIconUrl | string 또는 null | 아바타 URL이며, 아바타가 없으면 null입니다. |
| 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",
"countryCode": "",
"exterId": "",
"extend": null,
"source": "local",
"nameSpace": "",
"isUsed": 0,
"agreeTerms": 0,
"canaryPublic": false,
"enableMFA": false,
"language": "zh",
"tokenHoldTime": 86400,
"tokenMaxValidDuration": 604800,
"timezone": "",
"attributes": {
"部门": "研发部"
},
"customAttributes": {
"costCenter": "CC-1001"
},
"statusPageSubs": 0,
"defaultWorkspace": "",
"brandKey": "guance",
"scheduleMobile": "",
"scheduleEmail": "",
"ifScheduleMobileEnable": false,
"ifScheduleEmailEnable": false,
"accountStatus": "",
"roles": [
{
"uuid": "general",
"name": "普通成员"
}
],
"enablePersonalAPIKey": 0,
"mgroups": [],
"member_group": [],
"userType": "common",
"userIconUrl": null
}
],
"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"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
아래 표는 확인된 비즈니스 및 요청 오류입니다. 일반 데이터베이스/다운스트림 5xx 또는 처리되지 않은 예외는 전역에서 ft.InternalServerError로 래핑됩니다. 쓰기 요청 실패 시 부분 적용이 없었다고 보장할 수 없으므로 먼저 관계 현황을 확인해야 합니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다. | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형, 값을 확인합니다. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시, 이전 승인 작업 취소 또는 처리되지 않은 배열/필드 예외 | 내부 오류 | traceId를 저장하고 관리자에게 실제 관계와 캐시를 확인하도록 요청합니다. 쓰기 작업이 일부 커밋되었을 수 있으므로 무작정 재시도해서는 안 됩니다. |