콘텐츠로 이동

멤버 목록



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를 제공하십시오.

문서 평가

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