목록 조회¶
GET /api/v1/tag/list
개요¶
현재 워크스페이스의 유효한 태그와 리소스 연결 및 권한 요약을 페이지 단위로 조회합니다.
호출 전 및 사용 단계¶
태그 id 내림차순으로 정렬하며 status=0인 항목만 조회합니다. 현재 공개 진입점은 이 페이지의 네 가지 Query만 지원하며, Front의 scope/includeGlobal/displayType 또는 KV 필터를 전달하지 않습니다. 내부적으로 지원되더라도 이러한 미선언 필드를 추가해서는 안 됩니다. 목록의 scope는 호출자가 사용 가능한 태그를 선택하기 위한 것이며, scope가 리소스 권한을 대체하지는 않습니다.
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Query 요청 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| filter | string | 선택 사항입니다. 해당 유형에서 현재 참조 중인 태그만 조회하며, 참조가 없으면 빈 결과를 반환합니다. search와 AND로 조합됩니다. 전달하지 않으면 일반 태그 및 콜론 이름 태그를 포함한 모든 유효 태그를 조회합니다. null 허용: False 선택 가능 값: ['BoardRefTagObject', 'ViewerRefTagObject', 'CheckerRefTagObject', 'SmartCheckerRefTagObject', 'AiCheckerRefTagObject', 'DialingRefTagObject'] 예시: BoardRefTagObject가져오기 또는 입력 방법: 리소스 연결 유형을 선택합니다. BoardRefTagObject 대시보드, ViewerRefTagObject 탐색기, CheckerRefTagObject 일반 모니터, SmartCheckerRefTagObject 지능형 모니터링, AiCheckerRefTagObject AI 모니터, DialingRefTagObject 신서틱 테스트입니다. |
|
| pageIndex | integer | 선택 사항이며 기본값은 1이고 최솟값은 1입니다. null 허용: False $minValue: 1 예시: 1가져오기 또는 입력 방법: 1부터 시작하여 최상위 pageInfo에 따라 페이지별로 읽습니다. |
|
| pageSize | integer | 선택 사항이며 기본값은 10이고 최댓값은 10000이며, 작은 페이지 크기를 권장합니다. null 허용: False $maxValue: 10000 $minValue: 1 예시: 10가져오기 또는 입력 방법: 1..10000 범위에서 적절한 페이지 크기를 선택합니다. |
|
| search | string | 선택 사항입니다. name 기준 포함 일치로 검색하며 앞뒤 공백을 제거합니다. %/_는 SQL LIKE 의미를 그대로 따르며 설명은 검색하지 않습니다. null 허용: False 예시: production가져오기 또는 입력 방법: 대상 태그 이름 키워드입니다. |
파라미터 추가 설명¶
데이터 설명
- 요청 파라미터 설명
| 파라미터명 | type | 설명 |
|---|---|---|
| filter | string | 열거형 값(대시보드와 연결된 태그: BoardRefTagObject, 탐색기와 연결된 태그: ViewerRefTagObject, 일반 모니터와 연결된 태그: CheckerRefTagObject, 지능형 모니터와 연결된 태그: SmartCheckerRefTagObject, AI 시맨틱 모니터와 연결된 태그: AiCheckerRefTagObject) |
- 응답 파라미터 설명
| 파라미터명 | type | 설명 |
|---|---|---|
| name | string | 태그 이름 |
| description | string | 필드 설명 정보 |
| color | string | 프런트엔드와 백엔드에서 약속한 색상 유형, default,style_key1,style_key2 ~~ |
- 색상 color 필드의 유형별 색상 매핑:
{ "default": {"background": "#CCE6FF", "color": "rgba(0,0,0,0.8)"}, "style_key1": {"background": "#3333FE", "color": "#FFFFFF"}, "style_key2": {"background": "#428BCA", "color": "#FFFFFF"}, "style_key3": {"background": "#364450", "color": "#FFFFFF"}, "style_key4": {"background": "#E0E1FF", "color": "rgba(0,0,0,0.8)"}, "style_key5": {"background": "#9400D3", "color": "#FFFFFF"}, "style_key6": {"background": "#EDDBFF", "color": "rgba(0,0,0,0.8)"}, "style_key7": {"background": "#CC328B", "color": "#FFF"}, "style_key8": {"background": "#FCDEF0", "color": "rgba(0,0,0,0.8)"}, "style_key9": {"background": "#DC143D", "color": "#FFFFFF"}, "style_key10": {"background": "#FCBABA", "color": "rgba(0,0,0,0.8)"}, "style_key11": {"background": "#BD0B48", "color": "#FFFFFF"}, "style_key12": {"background": "#FDECD2", "color": "rgba(0,0,0,0.8)"}, "style_key13": {"background": "#FFC29C", "color": "rgba(0,0,0,0.8)"}, "style_key14": {"background": "#ED9120", "color": "#FFFFFF"}, "style_key15": {"background": "#CD5B44", "color": "#FFFFFF"}, "style_key16": {"background": "#FAF570", "color": "rgba(0,0,0,0.8)"}, "style_key17": {"background": "#C29953", "color": "#FFFFFF"}, "style_key18": {"background": "#02B140", "color": "#FFFFFF"}, "style_key19": {"background": "#D5F4D5", "color": "rgba(0,0,0,0.8)"}, "style_key20": {"background": "#009966", "color": "#FFFFFF"}, "style_key21": {"background": "#023220", "color": "#FFFFFF"}, "style_key22": {"background": "#E7E7E7", "color": "rgba(0,0,0,0.8)"}, "style_key23": {"background": "#808080", "color": "#FFFFFF"} }
요청 예시¶
curl --get 'https://openapi.guance.com/api/v1/tag/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[].uuid | string | tag_태그 UUID입니다. |
| content.data[].name | string | 태그 이름입니다. |
| content.data[].description | string | 용도 설명입니다. |
| content.data[].colour | string | 색상 표현입니다. |
| content.data[].scope | array<string> |
정규화된 범위이며, 과거 null/빈 scope는 ["all"]로 반환됩니다. |
| content.data[].scope[] | string | all/scene/monitor/dialing/security/infrastructure/catalog 중 하나입니다. |
| content.data[].creator | string | 생성 주체입니다. |
| content.data[].updator | string | 최근 수정 주체입니다. |
| content.data[].createAt | integer | 생성 Unix 초입니다. |
| content.data[].updateAt | integer | 업데이트 Unix 초이며, 업데이트되지 않은 경우 -1입니다. |
| content.data[].id | string | 목록 호환 필드로 uuid와 동일하며, 데이터베이스 숫자 id가 아닙니다. |
| content.data[].creatorInfo | object | 주체 요약이며, 일치하는 프로필이 없으면 {}입니다. |
| content.data[].creatorInfo.uuid | string | 주체 UUID이며 생략할 수 있습니다. |
| content.data[].creatorInfo.status | integer | 계정/주체 상태이며 생략할 수 있습니다. |
| content.data[].creatorInfo.wsAccountStatus | integer | 워크스페이스 멤버십 상태이며 생략할 수 있습니다. |
| content.data[].creatorInfo.name | string | 표시 이름입니다. |
| content.data[].creatorInfo.username | string | 로그인 이름이며 생략할 수 있습니다. |
| content.data[].creatorInfo.email | string | 이메일 또는 시스템 주체 식별자이며 생략할 수 있습니다. |
| content.data[].creatorInfo.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.data[].creatorInfo.countryCode | string | 국가/지역 코드이며 생략할 수 있습니다. |
| content.data[].creatorInfo.iconUrl | string | 아바타이며 생략할 수 있습니다. |
| content.data[].creatorInfo.acntWsNickname | string | 워크스페이스 닉네임이며 생략할 수 있습니다. |
| content.data[].updatorInfo | object | 주체 요약이며, 일치하는 프로필이 없으면 {}입니다. |
| content.data[].updatorInfo.uuid | string | 주체 UUID이며 생략할 수 있습니다. |
| content.data[].updatorInfo.status | integer | 계정/주체 상태이며 생략할 수 있습니다. |
| content.data[].updatorInfo.wsAccountStatus | integer | 워크스페이스 멤버십 상태이며 생략할 수 있습니다. |
| content.data[].updatorInfo.name | string | 표시 이름입니다. |
| content.data[].updatorInfo.username | string | 로그인 이름이며 생략할 수 있습니다. |
| content.data[].updatorInfo.email | string | 이메일 또는 시스템 주체 식별자이며 생략할 수 있습니다. |
| content.data[].updatorInfo.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.data[].updatorInfo.countryCode | string | 국가/지역 코드이며 생략할 수 있습니다. |
| content.data[].updatorInfo.iconUrl | string | 아바타이며 생략할 수 있습니다. |
| content.data[].updatorInfo.acntWsNickname | string | 워크스페이스 닉네임이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo | object | dashboard 유형 태그 권한 설정이며, 설정되지 않은 경우 {}입니다. 현재 호출자의 최종 인증 결과는 아닙니다. |
| content.data[].tagPermissionInfo.id | integer | 엔터티 레코드 번호입니다. 목록의 id는 UUID 문자열이며, 목록 필드를 참조하십시오. |
| content.data[].tagPermissionInfo.uuid | string | tag_태그 UUID입니다. |
| content.data[].tagPermissionInfo.workspaceUUID | string | 소속 워크스페이스입니다. |
| content.data[].tagPermissionInfo.status | integer | 0은 유효, 3은 삭제이며, 기타 과거 상태는 실제 데이터를 기준으로 합니다. |
| content.data[].tagPermissionInfo.creator | string | 생성 주체입니다. |
| content.data[].tagPermissionInfo.updator | string | 최근 수정 주체입니다. |
| content.data[].tagPermissionInfo.createAt | integer | 생성 Unix 초입니다. |
| content.data[].tagPermissionInfo.updateAt | integer | 업데이트 Unix 초이며, 업데이트되지 않은 경우 -1입니다. |
| content.data[].tagPermissionInfo.deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다. |
| content.data[].tagPermissionInfo.tagUUID | string | 현재 태그 UUID입니다. |
| content.data[].tagPermissionInfo.type | string | 이 목록 조회에서는 dashboard 권한 유형으로 고정됩니다. |
| content.data[].tagPermissionInfo.permissionSet | array<string> |
설정된 작업 주체 목록입니다. |
| content.data[].tagPermissionInfo.permissionSet[] | string | 계정/팀/역할 식별자입니다. |
| content.data[].tagPermissionInfo.permissionSetInfo | object | 해당 목록이 비어 있지 않은 경우에만 주체 식별자→프로필 매핑을 제공합니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体 | object | 계정 전체 주체 요약 또는 역할/팀 name/status이며, 프로필이 없으면 {}일 수 있습니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体.uuid | string | 주체 UUID이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体.status | integer | 계정/주체 상태이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体.wsAccountStatus | integer | 워크스페이스 멤버십 상태이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体.name | string | 표시 이름입니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体.username | string | 로그인 이름이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体.email | string | 이메일 또는 시스템 주체 식별자이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体.countryCode | string | 국가/지역 코드이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体.iconUrl | string | 아바타이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.permissionSetInfo.主体.acntWsNickname | string | 워크스페이스 닉네임이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.readPermissionSet | array<string> |
설정된 읽기 주체 목록입니다. |
| content.data[].tagPermissionInfo.readPermissionSet[] | string | 계정/팀/역할 식별자입니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo | object | 해당 목록이 비어 있지 않은 경우에만 주체 식별자→프로필 매핑을 제공합니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体 | object | 계정 전체 주체 요약 또는 역할/팀 name/status이며, 프로필이 없으면 {}일 수 있습니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体.uuid | string | 주체 UUID이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体.status | integer | 계정/주체 상태이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体.wsAccountStatus | integer | 워크스페이스 멤버십 상태이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体.name | string | 표시 이름입니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体.username | string | 로그인 이름이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体.email | string | 이메일 또는 시스템 주체 식별자이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体.mobile | string | 휴대폰 번호이며 비어 있을 수 있습니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体.countryCode | string | 국가/지역 코드이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体.iconUrl | string | 아바타이며 생략할 수 있습니다. |
| content.data[].tagPermissionInfo.readPermissionSetInfo.主体.acntWsNickname | string | 워크스페이스 닉네임이며 생략할 수 있습니다. |
| content.declaration | object | 공통 선언입니다. |
| pageInfo.pageIndex | integer | 페이지 번호입니다. |
| pageInfo.pageSize | integer | 페이지 크기입니다. |
| pageInfo.count | integer | 이 페이지의 수량입니다. |
| pageInfo.totalCount | integer | 조건에 맞는 총수입니다. |
{
"code": 200,
"content": {
"data": [
{
"uuid": "tag_example",
"name": "production",
"description": "生产资源统一标记。",
"colour": "default",
"scope": [
"scene",
"monitor"
],
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"id": "tag_example",
"tagPermissionInfo": {},
"creatorInfo": {},
"updatorInfo": {}
}
],
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE",
"pageInfo": {
"pageIndex": 1,
"pageSize": 10,
"count": 1,
"totalCount": 1
}
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 선언되지 않은 Query 파라미터를 사용했거나 파라미터가 규칙을 위반한 경우 | 파라미터 파싱 실패 | Query 파라미터 표와 예시를 확인하십시오. |
| 500 | ft.InternalServerError | 태그, 참조/권한 또는 주체 프로필 읽기와 응답 포맷팅에 실패한 경우 | 내부 오류 | 워크스페이스와 조회 조건을 확인하고 잠시 후 다시 시도하십시오. 계속 실패하면 traceId를 제공하십시오. |