콘텐츠로 이동

목록 조회



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를 기록하고 잠시 후 재시도하거나 지원팀에 문의합니다.

문서 평가

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