멤버 목록¶
GET /api/v1/workspace/members/list
개요¶
현재 워크스페이스의 활성 멤버와 직접 역할, 상속 역할 및 개인 API Key 스위치를 페이지 단위로 가져옵니다.
호출 전 및 사용 단계¶
기본값은 pageIndex=1, pageSize=10이며 계정 이름 기준으로 정렬합니다. 결과에는 직접 멤버와 관리 콘솔 계정 그룹을 통해 추가된 멤버가 포함됩니다. 역할은 각각 roles, mgroups[].roles, member_group[].roles에 있습니다. 계정 배열은 content.data에서 읽고, 페이지 정보는 최상위 pageInfo에서 읽습니다. 담당자, @멤버, 역할 수정 등의 API에 파라미터를 준비할 때 uuid를 사용하십시오. 이메일은 이러한 API에서 공통 계정 ID가 아닙니다. 모든 작업은 현재 DF-API-KEY가 속한 워크스페이스를 대상으로 합니다. 다른 워크스페이스에 대해 작업하려면 해당 Key와 사이트 Endpoint를 변경하십시오.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| pageIndex | integer | 페이지 번호, 기본값 1, 최소 1. null 허용: False $minValue: 1 예시: 1가져오기 또는 입력 방법: 첫 페이지는 1이며 이후 페이지마다 증가합니다. |
|
| pageSize | integer | 페이지당 항목 수, 기본값 10. null 허용: False $maxValue: 100 $minValue: 1 예시: 10가져오기 또는 입력 방법: 필요에 따라 1~100 사이의 정수를 선택합니다. |
|
| search | string | 이름/이메일/워크스페이스 닉네임 기준 부분 일치 검색. null 허용: False 예시: oncall가져오기 또는 입력 방법: 계정 이름, 이메일 또는 이 워크스페이스 닉네임의 텍스트를 입력합니다. 생략하거나 공백이면 필터링하지 않습니다. 닉네임은 검색할 수 있지만 이 공개 목록에서는 해당 필드를 항상 반환하지는 않습니다. |
파라미터 추가 설명¶
이 공개 API는 계정 및 역할 정보를 반환하며 비밀번호, MFA 키, 기본 휴대폰 번호는 제거합니다. 프런트엔드 멤버 페이지의 추가 필드를 그대로 적용하지 마십시오. 예를 들어 프런트엔드의 승인 대기, 최근 Key 호출 등의 정보는 이 API의 고정 출력이 아닙니다.
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/workspace/members/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode pageIndex=1 \
--data-urlencode pageSize=10
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.data | array<object> |
현재 페이지 멤버이며 결과가 없으면 []입니다. |
| content.data[].id | integer | 사이트 계정 레코드 번호이며 다른 API 호출 시 uuid를 사용합니다. |
| content.data[].uuid | string | 계정 UUID, acnt_ 등 계정 식별자입니다. |
| content.data[].status | integer | 사이트 계정 상태이며 이 목록은 활성 계정만 조회합니다. |
| content.data[].creator | string | 계정 생성 주체. |
| content.data[].updator | string | 계정 최근 업데이트 주체. |
| content.data[].createAt | integer | 계정 생성 시간, Unix 초. |
| content.data[].updateAt | integer | 계정 업데이트 시간, Unix 초, 업데이트되지 않은 경우 -1일 수 있습니다. |
| content.data[].deleteAt | integer | 계정 삭제 시간, Unix 초, 삭제되지 않은 경우 -1. |
| content.data[].name | string | 계정 이름. |
| content.data[].username | string | 로그인 사용자 이름. |
| content.data[].email | string | 계정 이메일. |
| content.data[].countryCode | string | 계정 전화 국가/지역 코드. |
| content.data[].exterId | string | 계정 외부 식별자. |
| content.data[].source | string | 계정 소스입니다. 예를 들어 agent는 에이전트 계정이며, 기타 값은 등록/동기화 소스에 따라 제공됩니다. |
| content.data[].nameSpace | string | ID 네임스페이스입니다. 일반 계정은 비어 있고, SSO 계정은 해당 ID 소스 식별자입니다. |
| content.data[].userType | string | nameSpace가 비어 있으면 common, 그렇지 않으면 saml입니다. |
| content.data[].extend | object | 계정 확장 정보이며 구조는 계정 소스에서 제공합니다. |
| content.data[].extend.user_icon | string | 값이 있을 때의 아바타 리소스 또는 URL이며 userIconUrl 생성에 사용됩니다. |
| content.data[].extend.기타 필드 | JSON | 계정 소스에서 정의한 기타 확장 속성입니다. |
| content.data[].userIconUrl | string 또는 null | 생성된 아바타 URL이며 아바타가 없으면 null입니다. |
| content.data[].isUsed | boolean 또는 integer | 계정이 이전에 사용된 적이 있는지에 대한 기록 플래그입니다. |
| content.data[].agreeTerms | integer | 계정 약관 확인 플래그. |
| content.data[].canaryPublic | boolean | 계정 공용 카나리 플래그. |
| content.data[].enableMFA | boolean | 계정의 MFA 활성화 여부. |
| content.data[].language | string | 계정 언어 기본 설정. |
| content.data[].tokenHoldTime | integer | 계정 로그인 세션 유지 시간(초)입니다. 특수 값은 계정 설정에 따라 제공됩니다. |
| content.data[].tokenMaxValidDuration | integer | 로그인 세션 최대 유효 기간(초)입니다. 특수 값은 계정 설정에 따라 제공됩니다. |
| content.data[].timezone | string | 계정 시간대. |
| content.data[].attributes | object 또는 array | ID 소스 속성. |
| content.data[].attributes.사용자 정의 필드 | JSON | ID 소스에서 정의한 속성입니다. |
| content.data[].customAttributes | object 또는 array | 사용자 정의 계정 속성. |
| content.data[].customAttributes.사용자 정의 필드 | JSON | 사용자 정의 속성 값. |
| content.data[].statusPageSubs | integer | Status Page 구독 플래그. |
| content.data[].defaultWorkspace | string | 계정 기본 워크스페이스 식별자. |
| 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 | array<object> |
직접 연결된 워크스페이스 역할 요약입니다. 상속된 역할은 mgroups 및 member_group을 별도로 확인하십시오. |
| content.data[].roles[].uuid | string | 역할 UUID. |
| content.data[].roles[].name | string | 역할 표시 이름. |
| content.data[].mgroups | array<object> |
관리 콘솔 계정 그룹을 통해 추가/권한이 부여된 그룹입니다. |
| content.data[].mgroups[].uuid | string | 관리 계정 그룹 UUID. |
| content.data[].mgroups[].name | string | 관리 계정 그룹 이름. |
| content.data[].mgroups[].roles | array<object> |
해당 관리 그룹이 이 워크스페이스에서 부여한 역할. |
| content.data[].mgroups[].roles[].uuid | string | 역할 UUID. |
| content.data[].mgroups[].roles[].name | string | 역할 표시 이름. |
| content.data[].member_group | array<object> |
계정이 이 워크스페이스에서 소속된 팀. |
| content.data[].member_group[].uuid | string | 팀 UUID. |
| content.data[].member_group[].name | string | 팀 이름. |
| content.data[].member_group[].roles | array<object> |
팀이 이 워크스페이스에서 부여한 역할 요약. |
| content.data[].member_group[].roles[].uuid | string | 역할 UUID. |
| content.data[].member_group[].roles[].name | string | 역할 표시 이름. |
| content.data[].enablePersonalAPIKey | integer | 현재 워크스페이스의 개인 API Key 사용 스위치로 1은 켜짐, 0은 꺼짐입니다. 직접 역할 및 그룹 상속 역할을 병합하여 계산하며 owner는 항상 1이고, wsAdmin은 명시적 설정이 없으면 기본값 1이며, 기타는 기본값 0입니다. |
| content.declaration | object 또는 null | 워크스페이스 공용 선언이며 각 계정에 재귀적으로 삽입되지 않습니다. |
| pageInfo | object | 최상위 페이지 정보. |
| pageInfo.pageIndex | integer | 페이지 번호. |
| pageInfo.pageSize | integer | 페이지 크기. |
| pageInfo.count | integer | 현재 페이지에서 실제로 반환된 수. |
| pageInfo.totalCount | integer | 일치하는 계정 총수. |
{
"code": 200,
"content": {
"data": [
{
"id": 101,
"uuid": "acnt_example",
"name": "值班工程师",
"username": "xxx@guance.com",
"email": "xxx@guance.com",
"status": 0,
"creator": "SYS",
"updator": "",
"createAt": 1785430800,
"updateAt": -1,
"deleteAt": -1,
"nameSpace": "",
"userType": "common",
"source": "local",
"countryCode": "",
"exterId": "",
"extend": {},
"userIconUrl": null,
"isUsed": 1,
"agreeTerms": 1,
"canaryPublic": false,
"enableMFA": false,
"language": "zh",
"tokenHoldTime": 3600,
"tokenMaxValidDuration": 86400,
"timezone": "Asia/Shanghai",
"attributes": {},
"customAttributes": {},
"statusPageSubs": 0,
"defaultWorkspace": "wksp_example",
"brandKey": "guance",
"scheduleMobile": "",
"scheduleEmail": "",
"ifScheduleMobileEnable": false,
"ifScheduleEmailEnable": false,
"accountStatus": "",
"roles": [
{
"uuid": "readOnly",
"name": "只读成员"
}
],
"mgroups": [],
"member_group": [],
"enablePersonalAPIKey": 0
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"pageIndex": 1,
"pageSize": 10,
"count": 1,
"totalCount": 1
}
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 유형 및 값을 확인하십시오. |
| 500 | ft.InternalServerError | 멤버 정보 또는 연결된 역할 읽기 실패 | 내부 오류 | 나중에 다시 시도하십시오. 계속 실패하면 traceId를 제공하십시오. |