콘텐츠로 이동

템플릿 - 목록



GET /api/v1/sys_template/list

개요

사이트 시스템 템플릿 라이브러리에 있는 통합 유형 템플릿과 Pipeline 시스템 템플릿을 페이지 단위로 나열합니다.

호출 전 및 사용 단계

이것은 사이트 수준 템플릿 라이브러리이며, 특정 워크스페이스에 이미 생성된 대시보드/모니터/Pipeline 인스턴스가 아닙니다. 라이브러리 템플릿을 삭제하거나 덮어쓰는 것은 이미 인스턴스화된 리소스를 삭제/업그레이드하는 것과 같지 않습니다. 이 모듈은 데이터 쿼리를 수행하거나 실행 중인 수집 설정을 게시하지 않습니다. r 또는 w 권한의 External 서명을 사용합니다. 먼저 type/language/isCustomSysTemp로 템플릿을 찾은 다음 uuid로 상세 정보를 호출합니다. 기본 정렬은 사용자 정의 표시 우선, 생성 시간 내림차순, 이름 GBK 순서입니다. 전체를 순회해야 하는 경우 pageSize<=100을 명시적으로 지정하고 totalCount를 모두 소비할 때까지 페이지를 넘깁니다. Pipeline 요약에는 스크립트가 없고 dashboard 요약에서는 tagInfo도 제거되므로, 목록의 meta를 무손실 내보내기로 간주할 수 없습니다.

요청 헤더

파라미터명 타입 필수 설명
X-Df-SVersion string 원본 경로 및 요청 본문 서명 버전입니다. 생략한 후 본 페이지의 알고리즘을 계속 사용할 수 없습니다.
예: v20240417
획득 또는 입력 방법: 본 페이지 예시는 이 고정 버전을 사용하며, 예시 서명 알고리즘과 함께 사용합니다.
X-Df-Access-Key string Y 읽기 API는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 API는 w 자격 증명이 필요합니다.
예: <external-access-key>
획득 또는 입력 방법: 사이트 관리자가 External API AK를 할당하며, 워크스페이스 OpenAPI Key는 사용할 수 없습니다.
X-Df-Nonce string Y 임시 일련번호입니다. 실패 후 재전송할 때도 새 값을 생성하고 서명을 다시 계산합니다.
예: 97d275ee9f774315a7885ba7347acbd9
획득 또는 입력 방법: 요청마다 uuid.uuid4().hex를 다시 생성합니다.
X-Df-Signature string Y 대문자 메서드, nonce, 원본 전체 경로, timestamp 및 원본 UTF-8 요청 본문을 공백으로 연결한 후 HMAC-SHA256을 수행하고 hex 다이제스트를 취합니다.
예: <hmac-sha256-hex>
획득 또는 입력 방법: External API 서명 인증에 따라 대응하는 SK로 계산하며, 전체 실행 가능한 템플릿은 아래를 참조하세요.
X-Df-Timestamp string Y 사이트에 구성된 서명 유효 시간 범위 내에 있어야 하며, 예시 시간을 재사용할 수 없습니다.
예: 1785427200
획득 또는 입력 방법: 전송 시 str(int(time.time()))로 현재 Unix 초 문자열을 생성합니다.

Query 요청 파라미터

파라미터명 타입 필수 설명
isCustomSysTemp string 선택적 문자열 true/1은 사용자 정의만, false/0은 비사용자 정의만 반환합니다. 생략하면 두 유형 모두 반환합니다. 삭제는 사용자 정의 레코드만 처리하며, 이 필터 결과로 모두 삭제 가능하다고 추론해서는 안 됩니다.
null 허용: False
선택 가능 값: ['true', 'false', '1', '0']
예: true
획득 또는 입력 방법: 사용자 정의 템플릿을 관리하려면 먼저 true/1을 설정합니다.
isDisable string 선택 사항이며, 생략하면 상태 0과 2를 모두 포함합니다. true/1은 2를 필터링하고, false/0은 0을 필터링합니다. 비활성화 작업이 아니며, 삭제된 3은 나열되지 않습니다.
null 허용: False
선택 가능 값: ['true', 'false', '1', '0']
예: false
획득 또는 입력 방법: 활성 템플릿만 보려면 문자열 false/0, 비활성 템플릿만 보려면 true/1을 사용합니다.
language string 선택 사항: zh, en, zh-hant, id, ja, ko. 생략하거나 빈 문자열이면 언어로 필터링하지 않으며, 언어를 지정하면 language가 비어 있는 공통 레코드도 함께 포함합니다. 이 목록은 Accept-Language에 따라 다른 언어로 자동 폴백하지 않습니다.
빈 문자열 허용: True
null 허용: True
선택 가능 값: ['zh', 'en', 'zh-hant', 'id', 'ja', 'ko']
예: zh
획득 또는 입력 방법: 대상 템플릿 라이브러리 언어에 따라 선택합니다.
pageIndex integer 기본값 1, 최솟값 1.
null 허용: False
$minValue: 1
예: 1
획득 또는 입력 방법: 첫 페이지는 1이며, 이후 조건을 유지한 채 페이지마다 증가시킵니다.
pageSize integer 현재 컨트롤러에서 생략 시 기본값 500이며, 선언상 명시적으로 1~100만 허용합니다. 안정적인 연동을 위해 항상 100 이하를 명시적으로 전달할 것을 권장합니다.
null 허용: False
$maxValue: 100
$minValue: 1
예: 100
획득 또는 입력 방법: 1~100 정수를 명시적으로 사용하여 페이지를 나눕니다.
search string 선택 사항인 이름 포함 검색입니다. 입력값은 소문자로 변환되고 앞뒤 공백이 제거되며, 생략하거나 공백이면 필터링하지 않습니다. 실제 일치는 데이터베이스 정렬 규칙에 따릅니다.
null 허용: False
예: 业务指标
획득 또는 입력 방법: 템플릿 목록에 있는 기존 템플릿 name에서 이름 일부를 가져옵니다.
type string 선택적 템플릿 유형입니다. 탐색기 전용 유형은 저장 시 type=explorer와 고정 fileName으로 매핑되며, object-explorer는 object__ 접두사와 일치합니다. 응답의 type은 여전히 실제 저장 유형입니다. 전달하지 않으면 모든 유형을 조회합니다.
null 허용: False
선택 가능 값: ['dashboard', 'scene', 'monitor', 'security', 'explorer', 'pipeline', 'sec-checker', 'customer-explorer', 'object-explorer', 'resource-catalog-explorer', 'sensitive-data-scanner', 'integration', 'cloud-collector', 'other', 'ci-explorer', 'rum-explorer', 'tracing-default-explorer', 'cloud-test-explorer', 'tracing-profile-explorer', 'tracing-error-track-explorer', 'logging-default-explorer', 'keyevent-default-explorer', 'security-check-explorer', 'network-explorer', 'tracing-service-explorer', 'logging-error-track-explorer', 'cloud-billing-explorer']
예: dashboard
획득 또는 입력 방법: 템플릿 용도에 따라 선언된 열거형을 선택합니다.

파라미터 추가 설명

서명 방식은 External API 서명 인증을 참조하세요. language 필터는 공통 언어의 빈 레코드도 함께 포함합니다. 이름이 같은 다국어 템플릿은 uuid로 식별해야 하며, name만을 고유 키로 사용하지 않습니다. 목록 조회는 수정 부작용이 없습니다.

요청 예시

import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen

# 대상 사이트 주소와 관리자가 할당한 External API AK/SK로 교체합니다.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'GET'
path = '/api/v1/sys_template/list'
query = {'type': 'dashboard', 'language': 'zh', 'isCustomSysTemp': 'true', 'pageIndex': 1, 'pageSize': 100}
data = None
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
    "X-Df-Access-Key": access_key,
    "X-Df-Timestamp": timestamp,
    "X-Df-Nonce": nonce,
    "X-Df-Signature": signature,
    "X-Df-SVersion": "v20240417",
}
if data is not None:
    headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
    print(result.read().decode("utf-8"))

응답

HTTP200, application/json 표준 External 래퍼입니다. content는 본 페이지의 분기에 따라 객체/배열/null/true이며, OpenAPI declaration에 자동으로 추가되지 않습니다. 목록 페이지 정보는 content.pageInfo에 있습니다.

필드 타입 설명
content object 목록 결과 객체입니다.
content.data 객체 배열 현재 페이지의 템플릿 요약이며, 일치 항목이 없으면 []입니다.
content.data[].uuid string 템플릿 UUID이며, Integration은 itgr_, Pipeline은 pl_입니다. 상세/삭제 시 복사하여 사용합니다.
content.data[].type string 실제 저장 유형이며, 탐색기 전용 필터는 explorer를 반환할 수 있습니다.
content.data[].path string 통합 템플릿의 내부 리소스 경로이며, 직접 요청할 수 있는 HTTP API나 로컬 다운로드 경로가 아닙니다. Pipeline은 비어 있습니다.
content.data[].name string 표시 이름입니다. 일부 고정 탐색기는 이름이 비어 있을 수 있으므로 fileName/type과 함께 확인해야 합니다.
content.data[].fileName string 템플릿 파일 식별자이며, Pipeline은 비어 있습니다. 업로드 파일명이 아닙니다.
content.data[].isHidden boolean 또는 integer 숨김 여부를 나타내는 표시 플래그이며, status 비활성화와 같지 않습니다.
content.data[].meta object Integration 원본 템플릿 JSON입니다. dashboard 목록에서는 tagInfo가 제거되고, Pipeline 목록은 항상 {}이며, 완전하고 이식 가능한 내용은 상세를 사용합니다.
content.data[].language string 레코드 언어이며, 비어 있으면 공통을 의미합니다.
content.data[].status integer 0 활성, 2 비활성.
content.data[].isCustomSysTemp boolean 또는 integer 사용자 정의 플래그이며, 1/true만 이 모듈에서 삭제 가능한 유형입니다.
content.data[].category string Pipeline 카테고리이며, Integration 목록에서는 보통 빈 문자열입니다.
content.data[].createAt integer 사용자 정의 레코드의 원래 생성 Unix 초입니다. 비사용자 정의 템플릿 목록에서는 강제로 0이 표시되므로 실제 원래 생성 시간을 추론하는 데 사용할 수 없습니다.
content.pageInfo object 페이지 정보는 최상위로 올라가지 않습니다.
content.pageInfo.pageIndex integer 페이지 번호입니다.
content.pageInfo.pageSize integer 이번 페이지 크기이며, 생략 시 기본값 500일 수 있습니다.
content.pageInfo.count integer 현재 페이지 항목 수입니다.
content.pageInfo.totalCount integer 일치하는 전체 항목 수입니다.
content.data[].meta.title string 일반적인 템플릿 제목이며, 생략될 수 있습니다.
content.data[].meta.summary string 일반적인 템플릿 요약입니다.
content.data[].meta.identifier string dashboard에서 흔히 사용되는 고유 식별자입니다.
content.data[].meta.isHidden boolean 또는 integer 선택적 숨김 표시 설정입니다.
content.data[].meta.iconSet object 선택적 아이콘 설정입니다.
content.data[].meta.iconSet.url string 선택적 아이콘 리소스 주소이며, 현재 템플릿 설정을 따릅니다.
content.data[].meta.main object 또는 array dashboard는 {groups,charts,vars}, monitor는 {checkers}이며, 탐색기는 보통 패널 배열이고, security 등은 원본 유효 템플릿 구조를 따릅니다.
content.data[].meta.main.groups array dashboard 그룹의 전체 배열입니다.
content.data[].meta.main.charts 객체 배열 dashboard 차트의 전체 배열입니다. 구체적인 구조는 전역 식별자 가져오기를 참조하세요. 템플릿 저장은 워크스페이스에 이미 적용되었음을 의미하지 않습니다.
content.data[].meta.main.vars 객체 배열 dashboard 변수 배열이며, 유효 템플릿에 따라 완전히 보존됩니다.
content.data[].meta.main.checkers 객체 배열 monitor 검사기의 전체 정의 배열입니다.
content.data[].meta.main.checkers[].jsonScript object 검사기 설정이며, 해당 모니터링 유형에 맞게 제공해야 하고 유형은 유효 템플릿에서 가져옵니다.
content.data[].meta.main.checkers[].jsonScript.title string 모니터 표시 제목입니다.
content.data[].meta.main.checkers[].jsonScript.type string 모니터 검사 유형이며, 현재 버전의 유형 집합 내에 있어야 합니다.
content.data[].meta.main[] object 탐색기 패널 항목이며, 전용 유형에 따라 원래 구조를 유지합니다.
content.data[].meta.main[].class string 데이터 네임스페이스 범주입니다(예: object, custom_object, logging).
content.data[].meta.main[].source string 또는 object 또는 array 탐색기 데이터 소스 키/표시 매핑이며, 구체적인 정규화는 가져오기 페이지를 참조하세요.
content.data[].meta.main[].source.key string 객체 형태의 소스 키입니다.
content.data[].meta.main[].source.name string 객체 형태의 소스 표시 이름입니다.
content.data[].meta.기타 필드 JSON 값 원본 템플릿의 추가 키이며, 카테고리 및 버전에 따라 동적으로 변합니다. 이 모듈은 대부분 저장/조회만 수행하며, 모든 키가 이후 비즈니스에서 소비된다고 보장하지 않습니다.
{
  "code": 200,
  "content": {
    "data": [
      {
        "uuid": "itgr_example001",
        "type": "dashboard",
        "path": "/dataflux-template/dashboard/zh/<template-file-id>",
        "name": "业务指标",
        "fileName": "<template-file-id>",
        "isHidden": 0,
        "meta": {
          "title": "业务指标",
          "main": {
            "groups": [],
            "charts": [],
            "vars": []
          }
        },
        "language": "zh",
        "status": 0,
        "isCustomSysTemp": 1,
        "category": "",
        "createAt": 1785427200
      }
    ],
    "pageInfo": {
      "pageIndex": 1,
      "pageSize": 100,
      "count": 1,
      "totalCount": 1
    }
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

오류 응답

인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.

HTTP 상태 errorCode 발생 조건 메시지 또는 응답 설명 처리 방법
406 ft.ParameterValidationFailed 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다 파라미터 파싱 실패 파라미터 위치, 필드 이름, 타입 및 값을 확인합니다.
500 ft.InternalServerError 템플릿 조인 조회, meta JSON 파싱, 특수 탐색기 유형 식별 또는 Pipeline 내용 인코딩 이상 내부 오류 traceId를 보존하고 UUID와 템플릿 원본 구조를 확인합니다. 이후 제한적으로 재시도하며, 실패를 존재하지 않음으로 간주해서는 안 됩니다.

문서 평가

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