テンプレート - 一覧¶
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 とテンプレートの元の構造を確認してください。後で回数を限定して再試行しますが、失敗を存在しないものとして扱うことはできません。 |