模板管理¶

本文说明如何通过 External API 调用管理后台「模板管理」菜单对应能力。

接口范围¶

功能	方法	路径
查询模板列表	`GET`	`/api/v1/sys_template/list`
获取模板详情	`GET`	`/api/v1/sys_template/{template_uuid}/get`
导入自定义模板	`POST`	`/api/v1/sys_template/custom/import`
删除自定义模板	`POST`	`/api/v1/sys_template/custom/{systemplate_uuid}/delete`
批量删除自定义模板	`POST`	`/api/v1/sys_template/custom/batch_deletes`

所有接口都使用 External API 公共签名请求头。

模板类型¶

导入接口的 type 字段与管理后台「模板管理」页面的类型一致，常用值包括：

type	说明
`dashboard`	视图模板
`monitor`	监控器模板
`customer-explorer`	自定义查看器模板
`pipeline`	Pipeline 模板
`object-explorer`	基础对象查看器模板
`resource-catalog-explorer`	资源目录查看器模板
`ci-explorer`	CI 查看器模板
`rum-explorer`	RUM 查看器模板
`tracing-default-explorer`	Tracing 默认查看器模板
`cloud-test-explorer`	云拨测查看器模板
`tracing-profile-explorer`	Profile 查看器模板
`tracing-error-track-explorer`	Tracing 错误追踪查看器模板
`logging-default-explorer`	日志默认查看器模板
`security-check-explorer`	安全巡检查看器模板
`network-explorer`	Network 查看器模板
`cloud-billing-explorer`	云账单查看器模板
`logging-error-track-explorer`	日志错误追踪查看器模板
`tracing-service-explorer`	Tracing 服务查看器模板
`keyevent-default-explorer`	事件默认查看器模板

查询模板列表¶

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: <随机字符>' \
  -H 'X-Df-Signature: <签名>' \
  -H 'X-Df-Timestamp: <时间戳>' \
  -H 'X-Df-SVersion: v20240417'

常用 query 参数：

参数	类型	必选	说明
`pageIndex`	integer	否	页码，默认 `1`
`pageSize`	integer	否	每页数量，最大 `100`；不传时后端默认 `500`
`search`	string	否	按模板名称搜索
`language`	string	否	模板语言，例如 `zh`、`en`
`type`	string	否	模板类型
`isCustomSysTemp`	string	否	是否只查询自定义模板；可选 `true`、`false`、`1`、`0`；`true`/`1` 为自定义模板，`false`/`0` 为官方模板

获取模板详情¶

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: <随机字符>' \
  -H 'X-Df-Signature: <签名>' \
  -H 'X-Df-Timestamp: <时间戳>' \
  -H 'X-Df-SVersion: v20240417'

详情接口返回的 content 就是模板 JSON。该 JSON 可以直接作为导入接口 jsonContents[] 中的一个元素使用。

导入自定义模板¶

管理后台 UI 的导入逻辑是：读取一个或多个 .json 文件，逐个 JSON.parse，再把解析后的对象组成 jsonContents 数组提交。

External API 调用时不需要上传文件，也不需要提交文件名。调用方只需要把 JSON 文件内容解析后放入 jsonContents。

如果调用方是按管理后台 UI 的表单状态组装请求体，需要按以下规则转换：

UI 表单字段	External API 请求体
`template`	仅用于 UI 类型选择，不提交
上传文件列表	取每个文件解析后的 JSON 对象，组成 `jsonContents[]`
非 `monitor` 类型的外层 `title`、`summary`	不提交，模板名称和说明来自 `jsonContents[]` 内部
`monitor` 类型的外层 `title`、`summary`	提交到请求体外层，作为监控器模板名称和说明
覆盖勾选结果	只提交需要覆盖的 JSON 对象，并传 `isCover: true`

大多数类型会逐项处理 jsonContents[]。ci-explorer、rum-explorer、tracing-* 等查看器派生类型在后端只读取 jsonContents[0]，因此这类类型一次请求只应传一个 JSON 对象。

普通模板导入¶

curl '<Endpoint>/api/v1/sys_template/custom/import' \
  -H 'Content-Type: application/json' \
  -H 'X-Df-Access-Key: <AK key>' \
  -H 'X-Df-Nonce: <随机字符>' \
  -H 'X-Df-Signature: <签名>' \
  -H 'X-Df-Timestamp: <时间戳>' \
  -H 'X-Df-SVersion: v20240417' \
  --data-raw '{
    "type": "dashboard",
    "language": "zh",
    "jsonContents": [
      {
        "title": "示例视图模板",
        "summary": "示例说明",
        "main": {
          "charts": [],
          "groups": [],
          "type": "template",
          "vars": []
        }
      }
    ]
  }'

请求体字段：

字段	类型	必选	说明
`type`	string	是	模板类型
`language`	string	是	模板语言，通常为 `zh` 或 `en`
`jsonContents`	array	是	模板 JSON 对象数组
`isCover`	boolean	否	是否覆盖同名自定义模板，默认 `false`；各类型覆盖键和限制见下方说明
`title`	string	`monitor` 类型必填	监控器模板名称
`summary`	string	否	监控器模板描述，仅 `monitor` 类型有效

覆盖导入¶

如果同名自定义模板已存在，可传 isCover: true 覆盖。覆盖只对自定义模板生效，不会覆盖官方内置模板。

模板类型	是否支持 `isCover`	覆盖匹配依据	主要限制
`dashboard`	支持	`title`	同名同 `identifier` 的自定义模板可覆盖；`identifier` 指向其他模板时仍会失败
`pipeline`	支持	`category + name`	`content`、`testData` 必须是合法 base64
`monitor`	支持	外层 `title`	多个 JSON 文件的 checker 会合并为同一个模板
`object-explorer`	支持	`main[0].source` 归一化后的模板文件名	`main[0].class` 必须为 `object`
`resource-catalog-explorer`	支持	`main[0].source` 归一化后的模板文件名	`main[0].class` 必须为 `custom_object`
`ci-explorer`、`rum-explorer`、`tracing-*` 等查看器派生类型	支持	类型对应的固定模板文件名	只读取 `jsonContents[0]`
其他集成模板类型	支持	`title`	模板 JSON 内必须包含可识别的 `title`

{
  "type": "dashboard",
  "language": "zh",
  "isCover": true,
  "jsonContents": [
    {
      "title": "已有模板名称",
      "main": {
        "charts": [],
        "groups": [],
        "type": "template",
        "vars": []
      }
    }
  ]
}

覆盖导入只表示允许覆盖同名自定义模板。若模板结构不合法、导入包内部重名，或者 dashboard identifier 指向其他模板，仍会失败。

监控器模板导入¶

monitor 类型比较特殊，模板名称和说明来自外层 title、summary。

{
  "type": "monitor",
  "language": "zh",
  "title": "MySQL 监控器模板",
  "summary": "MySQL 监控器模板说明",
  "jsonContents": [
    {
      "checkers": [
        {
          "jsonScript": {
            "title": "CPU 使用率过高",
            "type": "simpleCheck"
          }
        }
      ]
    }
  ]
}

也可以使用 main.checkers 结构：

{
  "type": "monitor",
  "language": "zh",
  "title": "MySQL 监控器模板",
  "jsonContents": [
    {
      "main": {
        "checkers": [
          {
            "jsonScript": {
              "title": "CPU 使用率过高",
              "type": "simpleCheck"
            }
          }
        ]
      }
    }
  ]
}

后端会将 jsonContents 内所有 checker 合并到同一个监控器模板中，并把每个 checker 的 monitorName 设置为外层 title。

Pipeline 模板导入¶

pipeline 类型的 content 和 testData 需要是 base64 编码字符串。通过详情接口导出的 Pipeline 模板可以直接再次导入。

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

导入返回¶

导入接口返回标准 External API 响应；下面数组是响应体 content 字段内的结构，每个元素表示一个导入项的校验结果。

[
  {
    "index": 0,
    "name": "示例视图模板",
    "err_fields": [],
    "is_exists_name": false,
    "import_exists_name": false
  }
]

常见字段：

字段	说明
`index`	对应 `jsonContents` 的下标；`monitor` 缺少外层 `title` 时可能返回 `-1`
`name`	后端识别出的模板名称
`err_fields`	字段错误列表，非空表示模板结构不符合当前类型要求
`is_exists_name`	与系统已有自定义模板重名
`import_exists_name`	本次导入数据内部重名
`is_exists_identify`	dashboard `identifier` 指向其他已有模板
`import_exists_identity_id`	本次导入数据内部 dashboard `identifier` 重复

如果存在不允许提交的错误，本次导入会整体不提交。

删除自定义模板¶

只能删除自定义模板，官方模板不支持删除。

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: <随机字符>' \
  -H 'X-Df-Signature: <签名>' \
  -H 'X-Df-Timestamp: <时间戳>' \
  -H 'X-Df-SVersion: v20240417'

批量删除：

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: <随机字符>' \
  -H 'X-Df-Signature: <签名>' \
  -H 'X-Df-Timestamp: <时间戳>' \
  -H 'X-Df-SVersion: v20240417' \
  --data-raw '{
    "systemplateUUIDs": ["itgr_xxxx", "pl_xxxx"]
  }'

与管理后台 UI 的等价关系¶

UI 操作	External API 调用方式
筛选模板类型、语言、自定义/官方、搜索	调用 list，并传 `type/language/isCustomSysTemp/search`
查看模板	调用 get
下载模板	调用 get 后保存 `content` 为 JSON 文件
上传 JSON 文件导入	将每个 JSON 文件内容解析为对象，放入 `jsonContents[]` 调用 import
覆盖导入	调用 import，并传 `isCover: true`
删除自定义模板	调用 delete 或 batch_deletes

注意事项¶

External API 不接收 zip 文件。
External API 不接收浏览器文件对象。
jsonContents 中放的是 JSON 对象，不是 JSON 字符串。
monitor 类型必须传外层 title。
删除接口只对自定义模板生效。
只读 External API 账号只能调用查询类接口，不能调用导入和删除接口。