목록 조회¶
GET /api/v1/workspace/member_group/list
개요¶
현재 워크스페이스의 팀과 유효한 멤버, 연결된 역할을 나열합니다.
호출 전 준비 및 사용 단계¶
팀 이름 검색만 지원하며 페이지네이션은 없고 content 배열을 직접 읽습니다. 팀 레코드 id 오름차순으로 정렬됩니다. member_count는 현재 워크스페이스에서 여전히 유효하고 조회 가능한 멤버 프로필만 계산하므로 과거 연결 레코드 수와 다를 수 있습니다. 멤버 및 역할 목록의 순서는 고정되지 않습니다. 빈 팀의 role_infos는 역할이 이미 구성되어 있어도 비어 있을 수 있습니다. 권한을 확인할 때는 기존 설정과 역할 관리 화면을 함께 확인해야 하며, 빈 배열만으로 역할이 없다고 판단해서는 안 됩니다.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| search | string | 팀 이름으로 부분 일치 검색합니다. 생략하면 모든 활성 팀을 조회합니다. null 허용: False 예시: 生产가져오기 또는 입력 방법: 팀 이름 키워드를 입력합니다. |
파라미터 추가 설명¶
반환된 team uuid는 수정, 삭제 및 객체 권한 구성에 사용할 수 있습니다. 팀 목록에는 pageIndex/pageSize 파라미터가 없습니다.
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/workspace/member_group/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode 'search=生产'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content | array<object> |
활성 팀 배열이며, 결과가 없으면 []입니다. |
| content[].id | integer | 데이터베이스 레코드 번호이며, 작업에는 uuid를 사용합니다. |
| content[].uuid | string | 팀 UUID. |
| content[].name | string | 팀 이름. |
| content[].workspaceUUID | string | 소속 워크스페이스 UUID. |
| content[].status | integer | 활성 팀은 0입니다. |
| content[].creator | string | 생성 주체. |
| content[].updator | string | 갱신 주체이며 비어 있을 수 있습니다. |
| content[].createAt | integer | 생성 Unix 초. |
| content[].updateAt | integer | 엔터티 갱신 시간 Unix 초이며, 갱신되지 않은 경우 -1입니다. 현재 수정 시 이 필드가 갱신된다는 보장이 없으므로 멤버/역할 변경 여부 판단에 사용할 수 없습니다. |
| content[].deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다. |
| content[].member_count | integer | 현재 조회 가능한 유효 멤버 수입니다. |
| content[].member_name_list | array<string> |
멤버 표시 이름 목록으로, 워크스페이스 닉네임을 우선 사용하고 없으면 계정 이름을 사용합니다. |
| content[].member_name_list[] | string | 개별 멤버 표시 이름입니다. |
| content[].member_infos | array<object> |
유효 멤버 프로필입니다. |
| content[].role_infos | array<object> |
현재 멤버 연결 경로로 조회된 역할 요약이며, 빈 팀은 빈 배열을 반환할 수 있습니다. |
| content[].declaration | object 또는 null | 각 팀의 워크스페이스 공용 선언입니다. |
| content[].member_infos[].id | integer | 멤버 데이터베이스 번호입니다. |
| content[].member_infos[].uuid | string | 멤버 계정 UUID. |
| content[].member_infos[].name | string | 계정 표시 이름입니다. |
| content[].member_infos[].email | string | 계정 이메일입니다. |
| content[].member_infos[].acntWsNickname | string | 이 워크스페이스 닉네임이며, 설정되지 않은 경우 빈 문자열입니다. |
| content[].member_infos[].username | string | 계정 로그인 사용자 이름입니다. |
| content[].member_infos[].source | string | 계정 소스입니다. |
| content[].member_infos[].userIconUrl | string | 아바타 주소이며, 설정되지 않은 경우 빈 문자열입니다. |
| content[].member_infos[].exterId | string | 외부 ID 시스템 ID이며 비어 있을 수 있습니다. |
| content[].member_infos[].mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content[].member_infos[].countryCode | string | 휴대폰 번호 국가/지역 코드이며 비어 있을 수 있습니다. |
| content[].member_infos[].namespace | string | 계정 네임스페이스입니다. |
| content[].member_infos[].attributes | JSON 값 | 계정 원시 속성이며, 대개 객체 또는 배열이고 파싱 실패 시 {}입니다. |
| content[].member_infos[].attributes.동적 필드 | JSON 값 | ID 공급자가 정의한 원시 속성 이름과 값이며, 통일된 고정 구조가 없습니다. |
| content[].member_infos[].customAttributes | JSON 값 | 계정 사용자 정의 속성이며, 대개 객체 또는 배열이고 파싱 실패 시 {}입니다. |
| content[].member_infos[].customAttributes.동적 필드 | JSON 값 | 사용자 또는 ID 시스템에서 구성한 사용자 정의 속성입니다. |
| content[].member_infos[].defaultWebhook | object | 일부 agent 멤버에만 존재하는 원시 Webhook 구성이며, 일반 멤버에서는 생략됩니다. |
| content[].member_infos[].defaultWebhook.동적 필드 | JSON 값 | agent에 저장된 구성 필드이며, API는 그대로 읽기만 하고 고정된 하위 필드 규약이 없습니다. |
| content[].role_infos[].uuid | string | 역할 UUID 또는 내장 역할 식별자로, roleUUIDs 요소로 사용할 수 있습니다. |
| content[].role_infos[].name | string | 역할 표시 이름입니다. |
{
"code": 200,
"content": [
{
"id": 42,
"uuid": "group_example",
"name": "生产运维",
"workspaceUUID": "wksp_example",
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"member_count": 1,
"member_name_list": [
"运维成员"
],
"member_infos": [
{
"id": 1,
"uuid": "acnt_example",
"name": "运维成员",
"email": "xxx@guance.com",
"acntWsNickname": "",
"username": "xxx@guance.com",
"source": "local",
"userIconUrl": "",
"exterId": "",
"mobile": "",
"countryCode": "",
"namespace": "",
"attributes": {},
"customAttributes": {}
}
],
"role_infos": [
{
"uuid": "role_example",
"name": "运维只读"
}
],
"declaration": {}
}
],
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 선언되지 않은 Query 파라미터를 사용했거나 파라미터가 규칙을 위반함 | 파라미터 파싱 실패 | Query 파라미터 표와 예시를 확인합니다. |
| 500 | ft.InternalServerError | 데이터베이스 또는 멤버 프로필 읽기 실패 | 내부 오류 | traceId를 기록하고 잠시 후 재시도하거나 지원팀에 문의합니다. |