Skip to content

Template Management

This document explains how to manage the capabilities corresponding to the 'Template Management' menu in the admin console via External API calls.

Interface Scope

Feature Method Path
Query template list GET /api/v1/sys_template/list
Get template details GET /api/v1/sys_template/{template_uuid}/get
Import custom template POST /api/v1/sys_template/custom/import
Delete custom template POST /api/v1/sys_template/custom/{systemplate_uuid}/delete
Batch delete custom templates POST /api/v1/sys_template/custom/batch_deletes

All interfaces use the common External API signature request headers.

Template Types

The type field for the import interface corresponds to the types on the 'Template Management' page in the admin console. Common values include:

type Description
dashboard Dashboard template
monitor Monitor template
customer-explorer Custom explorer template
pipeline Pipeline template
object-explorer Basic object explorer template
resource-catalog-explorer Resource Catalog explorer template
ci-explorer CI explorer template
rum-explorer RUM explorer template
tracing-default-explorer Tracing default explorer template
cloud-test-explorer Cloud testing explorer template
tracing-profile-explorer Profile explorer template
tracing-error-track-explorer Tracing error tracking explorer template
logging-default-explorer Logging default explorer template
security-check-explorer Security Check explorer template
network-explorer Network explorer template
cloud-billing-explorer Cloud billing explorer template
logging-error-track-explorer Logging error tracking explorer template
tracing-service-explorer Tracing service explorer template
keyevent-default-explorer Event default explorer template

Query Template List

curl '<Endpoint>/api/v1/sys_template/list?pageIndex=1&pageSize=10&type=dashboard&language=zh&isCustomSysTemp=true' \
  -H 'Content-Type: application/json' \
  -H 'X-Df-Access-Key: <AK key>' \
  -H 'X-Df-Nonce: <random characters>' \
  -H 'X-Df-Signature: <signature>' \
  -H 'X-Df-Timestamp: <timestamp>' \
  -H 'X-Df-SVersion: v20240417'

Common query parameters:

Parameter Type Required Description
pageIndex integer No Page number, defaults to 1
pageSize integer No Number of items per page, maximum 100; backend defaults to 500 if not provided
search string No Search by template name
language string No Template language, e.g., zh, en
type string No Template type
isCustomSysTemp string No Whether to query only custom templates; options true, false, 1, 0; true/1 for custom templates, false/0 for official templates

Get Template Details

curl '<Endpoint>/api/v1/sys_template/itgr_xxxx/get' \
  -H 'Content-Type: application/json' \
  -H 'X-Df-Access-Key: <AK key>' \
  -H 'X-Df-Nonce: <random characters>' \
  -H 'X-Df-Signature: <signature>' \
  -H 'X-Df-Timestamp: <timestamp>' \
  -H 'X-Df-SVersion: v20240417'

The content returned by the details interface is the template JSON. This JSON can be directly used as an element in the jsonContents[] array for the import interface.

Import Custom Template

The import logic of the admin console UI is: read one or more .json files, JSON.parse each, then submit the parsed objects as the jsonContents array.

When calling via External API, there is no need to upload files or submit filenames. The caller only needs to parse the JSON file contents and place them into jsonContents.

If the caller assembles the request body based on the form state of the admin console UI, it needs to be transformed according to the following rules:

UI Form Field External API Request Body
template Used only for UI type selection, not submitted
Uploaded file list Take the JSON object parsed from each file to form jsonContents[]
Outer title, summary for non-monitor types Not submitted; template name and description come from inside jsonContents[]
Outer title, summary for monitor type Submitted to the outer layer of the request body as the monitor template name and description
Overwrite selection result Only submit JSON objects that need to be overwritten, and pass isCover: true

Most types process jsonContents[] item by item. Explorer-derived types like ci-explorer, rum-explorer, tracing-* etc., only read jsonContents[0] on the backend, so for these types, only one JSON object should be passed per request.

Normal Template Import

curl '<Endpoint>/api/v1/sys_template/custom/import' \
  -H 'Content-Type: application/json' \
  -H 'X-Df-Access-Key: <AK key>' \
  -H 'X-Df-Nonce: <random characters>' \
  -H 'X-Df-Signature: <signature>' \
  -H 'X-Df-Timestamp: <timestamp>' \
  -H 'X-Df-SVersion: v20240417' \
  --data-raw '{
    "type": "dashboard",
    "language": "zh",
    "jsonContents": [
      {
        "title": "Example Dashboard Template",
        "summary": "Example description",
        "main": {
          "charts": [],
          "groups": [],
          "type": "template",
          "vars": []
        }
      }
    ]
  }'

Request body fields:

Field Type Required Description
type string Yes Template type
language string Yes Template language, usually zh or en
jsonContents array Yes Array of template JSON objects
isCover boolean No Whether to overwrite existing custom templates with the same name, defaults to false; see below for overwrite keys and limitations per type
title string Required for monitor type Monitor template name
summary string No Monitor template description, only valid for monitor type

Overwrite Import

If a custom template with the same name already exists, you can pass isCover: true to overwrite it. Overwrite only works on custom templates and will not overwrite official built-in templates.

Template Type Supports isCover? Overwrite Matching Basis Main Limitations
dashboard Yes title Custom templates with the same name and identifier can be overwritten; fails if identifier points to another template
pipeline Yes category + name content, testData must be valid base64
monitor Yes Outer title Checkers from multiple JSON files will be merged into the same template
object-explorer Yes Normalized template filename from main[0].source main[0].class must be object
resource-catalog-explorer Yes Normalized template filename from main[0].source main[0].class must be custom_object
Explorer-derived types like ci-explorer, rum-explorer, tracing-* Yes Fixed template filename corresponding to the type Only reads jsonContents[0]
Other integrated template types Yes title Template JSON must contain a recognizable title 
{
  "type": "dashboard",
  "language": "zh",
  "isCover": true,
  "jsonContents": [
    {
      "title": "Existing Template Name",
      "main": {
        "charts": [],
        "groups": [],
        "type": "template",
        "vars": []
      }
    }
  ]
}

Overwrite import only indicates that overwriting an existing custom template with the same name is allowed. It will still fail if the template structure is invalid, there are duplicate names within the import package, or the dashboard identifier points to another template.

Monitor Template Import

The monitor type is special; the template name and description come from the outer title and summary.

{
  "type": "monitor",
  "language": "zh",
  "title": "MySQL Monitor Template",
  "summary": "MySQL monitor template description",
  "jsonContents": [
    {
      "checkers": [
        {
          "jsonScript": {
            "title": "High CPU Usage",
            "type": "simpleCheck"
          }
        }
      ]
    }
  ]
}

You can also use the main.checkers structure:

{
  "type": "monitor",
  "language": "zh",
  "title": "MySQL Monitor Template",
  "jsonContents": [
    {
      "main": {
        "checkers": [
          {
            "jsonScript": {
              "title": "High CPU Usage",
              "type": "simpleCheck"
            }
          }
        ]
      }
    }
  ]
}

The backend will merge all checkers within jsonContents into the same monitor template and set each checker's monitorName to the outer title.

Pipeline Template Import

For the pipeline type, content and testData need to be base64-encoded strings. Pipeline templates exported via the details interface can be imported directly again.

{
  "type": "pipeline",
  "language": "zh",
  "jsonContents": [
    {
      "pipelines": [
        {
          "name": "nginx",
          "category": "logging",
          "content": "YmFzZTY0...",
          "testData": "W3sia2V5IjoidmFsdWUifV0=",
          "source": ["nginx"]
        }
      ]
    }
  ]
}

Import Response

The import interface returns a standard External API response; the array below is the structure within the content field of the response body, where each element represents the validation result of an imported item.

[
  {
    "index": 0,
    "name": "Example Dashboard Template",
    "err_fields": [],
    "is_exists_name": false,
    "import_exists_name": false
  }
]

Common fields:

Field Description
index Corresponds to the index in jsonContents; may return -1 for monitor type when outer title is missing
name Template name identified by the backend
err_fields List of field errors; non-empty indicates the template structure does not meet the requirements of the current type
is_exists_name Duplicate name with an existing custom template in the system
import_exists_name Duplicate name within the current import data
is_exists_identify Dashboard identifier points to another existing template
import_exists_identity_id Duplicate dashboard identifier within the current import data

If there are errors that prevent submission, the entire import will not be submitted.

Delete Custom Template

Only custom templates can be deleted; official templates do not support deletion.

curl '<Endpoint>/api/v1/sys_template/custom/itgr_xxxx/delete' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Df-Access-Key: <AK key>' \
  -H 'X-Df-Nonce: <random characters>' \
  -H 'X-Df-Signature: <signature>' \
  -H 'X-Df-Timestamp: <timestamp>' \
  -H 'X-Df-SVersion: v20240417'

Batch delete:

curl '<Endpoint>/api/v1/sys_template/custom/batch_deletes' \
  -H 'Content-Type: application/json' \
  -H 'X-Df-Access-Key: <AK key>' \
  -H 'X-Df-Nonce: <random characters>' \
  -H 'X-Df-Signature: <signature>' \
  -H 'X-Df-Timestamp: <timestamp>' \
  -H 'X-Df-SVersion: v20240417' \
  --data-raw '{
    "systemplateUUIDs": ["itgr_xxxx", "pl_xxxx"]
  }'

Equivalence with Admin Console UI

UI Operation External API Call Method
Filter template type, language, custom/official, search Call list, passing type/language/isCustomSysTemp/search
View template Call get
Download template Call get, then save content as a JSON file
Upload JSON file for import Parse each JSON file content into an object, place into jsonContents[], call import
Overwrite import Call import, passing isCover: true
Delete custom template Call delete or batch_deletes

Notes

  • External API does not accept zip files.
  • External API does not accept browser file objects.
  • jsonContents contains JSON objects, not JSON strings.
  • monitor type must pass the outer title.
  • Delete interfaces only work on custom templates.
  • Read-only External API accounts can only call query interfaces, not import or delete interfaces.

Feedback

Is this page helpful? ×