템플릿 - 템플릿 상세 조회¶
GET /api/v1/sys_template/{template_uuid}/get
개요¶
하나의 템플릿에서 이식 가능한 콘텐츠를 읽으며, Integration과 Pipeline에 따라 서로 다른 JSON 구조를 반환합니다.
호출 전 준비 및 사용 단계¶
이것은 사이트 수준 템플릿 라이브러리이며, 특정 워크스페이스에 이미 생성된 대시보드/모니터/Pipeline 인스턴스가 아닙니다. 라이브러리 템플릿을 삭제하거나 덮어쓰는 것은 이미 인스턴스화된 리소스를 삭제/업그레이드하는 것과 같지 않습니다. 이 모듈은 데이터 쿼리를 수행하거나 실행 중인 수집 설정을 게시하지 않습니다. uuid는 템플릿 목록에서 가져옵니다. Integration은 uuid/name/language 등 전체 레코드 외피 없이 meta를 직접 반환하며, Pipeline은 pipelines 배열을 반환하고 content/testData는 Base64 디코딩이 필요합니다. 원본 콘텐츠를 복사하기 전에 유형과 실제 필드를 먼저 확인하십시오. 현재 External의 pl_ 레코드 읽기에는 관리 백엔드 전용 isSysTemplate 검사도 없고 워크스페이스 파라미터도 없으므로, 이를 근거로 백엔드 리소스 격리 보장을 적용할 수 없습니다. 템플릿 목록에서 얻은 템플릿 UUID만 사용할 것을 권장합니다.
경로 파라미터¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| template_uuid | string | Y | itgr_는 Integration 템플릿, pl_은 Pipeline을 나타냅니다. 여기의 값은 템플릿 identifier/fileName이 아니며 워크스페이스 UUID도 허용하지 않습니다. 예시: itgr_example001획득 또는 입력 방법: 템플릿 목록의 content.data[].uuid에서 가져오며, 정확한 접두사를 유지하고 공백을 추가하지 않습니다. |
요청 헤더¶
| 파라미터명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로와 요청 본문의 서명 버전입니다. 이를 생략한 채 이 페이지의 알고리즘을 계속 사용할 수 없습니다. 예시: v20240417획득 또는 입력 방법: 이 페이지의 예시는 이 고정 버전을 사용하며, 예시 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 읽기 인터페이스는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 인터페이스는 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 초 문자열을 생성합니다. |
파라미터 추가 설명¶
조회 시 템플릿의 비즈니스 콘텐츠를 파싱하거나 실행하지 않습니다. 템플릿의 isHidden/status/isCustomSysTemp는 목록에서 확인해야 하며, 상세 meta에 해당 키가 없다고 해서 기본 활성화되었거나 삭제 가능하다고 간주할 수 없습니다.
요청 예시¶
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/itgr_example001/get'
query = {}
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"))
응답¶
HTTP 200, application/json 표준 External 외피입니다. content는 이 페이지의 분기에 따라 객체/배열/null/true가 되며, OpenAPI declaration이 자동으로 추가되지 않고, 목록 페이지네이션은 content.pageInfo에 있습니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | object 또는 null | Integration은 원본 meta, Pipeline은 {pipelines:[...]}이며, 접두사는 인식되었지만 레코드가 없거나 삭제된 경우 현재 null을 반환하고 404로 통일하지 않습니다. |
| content.title | string | 일반적인 템플릿 제목이며 생략될 수 있습니다. |
| content.summary | string | 일반적인 템플릿 요약입니다. |
| content.identifier | string | dashboard에서 흔히 사용하는 고유 식별자입니다. |
| content.isHidden | boolean 또는 integer | 선택적 숨김/표시 설정입니다. |
| content.iconSet | object | 선택적 아이콘 설정입니다. |
| content.iconSet.url | string | 선택적 아이콘 리소스 주소이며 현재 템플릿 설정을 따릅니다. |
| content.main | object 또는 array | dashboard는 {groups,charts,vars}, monitor는 {checkers}이며, 탐색기는 일반적으로 패널 배열이고, security 등은 원본 유효 템플릿 구조를 따릅니다. |
| content.main.groups | array | dashboard 그룹 전체 배열입니다. |
| content.main.charts | 객체 배열 | dashboard 차트 전체 배열이며, 구체적인 구조는 전역 식별자 가져오기를 참고하십시오. 템플릿 저장은 공간에 적용되었음을 의미하지 않습니다. |
| content.main.vars | 객체 배열 | dashboard 변수 배열이며, 유효한 템플릿에 따라 그대로 보존됩니다. |
| content.main.checkers | 객체 배열 | monitor 감지기 전체 정의 배열입니다. |
| content.main.checkers[].jsonScript | object | 감지기 설정이며, 해당 모니터링 유형에 맞게 제공해야 하고 유형은 유효한 템플릿에서 가져옵니다. |
| content.main.checkers[].jsonScript.title | string | 모니터 표시 제목입니다. |
| content.main.checkers[].jsonScript.type | string | 모니터 검사 유형이며, 현재 버전의 유형 집합 내에 있어야 합니다. |
| content.main[] | object | 탐색기 패널 항목이며, 전용 유형에 따라 원본 구조를 유지합니다. |
| content.main[].class | string | 데이터 네임스페이스 카테고리입니다. 예: object, custom_object, logging. |
| content.main[].source | string 또는 object 또는 array | 탐색기 데이터 소스 키/표시 매핑이며, 구체적인 정규화는 가져오기 페이지를 참고하십시오. |
| content.main[].source.key | string | 객체 형태의 소스 키입니다. |
| content.main[].source.name | string | 객체 형태의 소스 표시 이름입니다. |
| content.기타 필드 | JSON 값 | 원본 템플릿의 추가 키이며 카테고리와 버전에 따라 동적으로 변합니다. 이 모듈은 대부분 저장/조회만 수행하며, 모든 키가 이후 비즈니스에서 소비된다고 보장하지 않습니다. |
| content.pipelines | 객체 배열 | Pipeline 상세 전용이며, 한 항목이 현재 읽은 레코드입니다. Integration 상세에는 이 래퍼가 없습니다. |
| content.pipelines[].category | string | Pipeline 카테고리입니다. |
| content.pipelines[].name | string | Pipeline 이름입니다. |
| content.pipelines[].type | string | 저장된 실행 유형입니다. 예: local/central/없음. 이 값은 사용자 정의 템플릿 가져오기 분기에서 현재 다시 채워지지 않습니다. |
| content.pipelines[].asDefault | boolean 또는 integer | 저장된 기본값 표시이며, 가져오기 시 현재 이 입력 파라미터를 무시합니다. |
| content.pipelines[].enableByLogBackup | boolean 또는 integer | 저장된 로그 백업 스위치이며, 가져오기 시 현재 이 입력 파라미터를 무시합니다. |
| content.pipelines[].source | 문자열 배열 | 연결된 source 목록입니다. |
| content.pipelines[].source[] | string | 단일 source입니다. |
| content.pipelines[].isDisable | boolean | 저장된 status가 2인지 여부이며, 가져오기 시 현재 이 입력 파라미터에 따라 비활성화하지 않습니다. |
| content.pipelines[].content | string | UTF-8 스크립트 텍스트의 Base64 문자열이며, 직접 읽을 수 있는 스크립트가 아닙니다. |
| content.pipelines[].testData | string 또는 null | 저장된 테스트 데이터 텍스트를 다시 Base64로 인코딩한 값이며, 디코딩 후에는 JSON 객체/배열이어야 합니다. 비정상적인 과거 비텍스트 데이터 인코딩은 null을 반환할 수 있습니다. |
| content.pipelines[].dataType | string | 저장된 데이터 형식이며, 가져오기 시 현재 이 필드에 따라 설정하지 않고 새로 추가 시 기본값은 line_protocol입니다. |
| content.pipelines[].extend | object | 추가 JSON이며, RUM 템플릿 가져오기 시 appID가 []로 정규화됩니다. |
{
"code": 200,
"content": {
"title": "业务指标",
"identifier": "business-dashboard",
"main": {
"groups": [],
"charts": [],
"vars": []
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
접두사는 인식되었지만 대상이 없거나 삭제된 경우:
{
"code": 200,
"content": null,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
Pipeline 상세 예시:
{
"code": 200,
"content": {
"pipelines": [
{
"category": "logging",
"name": "example_pipeline",
"type": "",
"asDefault": 0,
"enableByLogBackup": 0,
"source": [],
"isDisable": false,
"content": "YWRkX2tleSgiZXhhbXBsZSIsICJ2YWx1ZSIp",
"testData": "eyJzYW1wbGUiOnsibWVzc2FnZSI6ImV4YW1wbGUifX0=",
"dataType": "line_protocol",
"extend": {}
}
]
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 404 | ft.NotFoundTemplateUUID | UUID 접두사가 pl 또는 itgr이 아님 | 지정된 템플릿 UUID를 찾을 수 없음 | 템플릿 목록에서 올바른 uuid를 복사하십시오. 접두사가 올바르지만 존재하지 않는 경우 현재 content=null을 반환할 수 있습니다. |
| 500 | ft.InternalServerError | 템플릿 연합 조회, meta JSON 파싱, 특수 탐색기 유형 인식 또는 Pipeline 콘텐츠 인코딩 이상 | 내부 오류 | traceId를 보관하고 UUID와 템플릿 원본 구조를 확인하십시오. 잠시 후 제한적으로 재시도하며, 실패를 존재하지 않는 것으로 간주해서는 안 됩니다. |