コンテンツにスキップ

テンプレート - 一覧



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

フィードバック

このページは役に立ちましたか?