콘텐츠로 이동

목록



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를 저장하고 관리자에게 실제 관계와 캐시를 확인하도록 요청합니다. 쓰기 작업이 일부 커밋되었을 수 있으므로 무작정 재시도해서는 안 됩니다.

문서 평가

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