テンプレート - テンプレート詳細を取得¶
GET /api/v1/sys_template/{template_uuid}/get
概要¶
テンプレートの移植可能な内容を読み取り、Integration と Pipeline で異なる JSON 構造を返します。
呼び出し前と使用手順¶
これはサイトレベルのテンプレートライブラリであり、特定のワークスペースで作成済みのダッシュボード/モニター/Pipeline インスタンスではありません。ライブラリテンプレートの削除または上書きは、インスタンス化済みリソースの削除/アップグレードと同等ではありません。本モジュールはデータクエリや稼働中の収集設定の配信は行いません。テンプレート一覧から uuid を取得します。Integration は meta を直接返し、uuid/name/language などの完全なレコードラッパーは含みません。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 詳細専用。1 項目が現在読み取ったレコードです。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 とテンプレートの元の構造を確認してください。後で回数を限定して再試行してください。失敗を存在しないものとして扱わないでください。 |