Skip to content

读取模板字段结构和版本 ​

读取模板的字段、类型、写入限制、正文图文组件和版本。批量建码和修改模板之前先读取:按返回的 field_id 填写,版本用于后续预校验和修改。

请求 ​

text
POST https://open.cli.im/api/v2/rpc/templates/getSchema
项目要求
最低权限只读,见权限档位
需要的 scopetemplates.read
组织 Key不能调用,返回 403 credential_type_not_allowed,见历史组织 Key

请求参数 ​

请求体为 JSON。

字段类型必填说明
template_idstring是模板 ID,取自 templates/listEditable 或 templates/list 返回的 template_id。最长 128 个字符

请求示例 ​

示例里的 ID、幂等键等换成实际值。

bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/templates/getSchema' \
  -H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "template_id": "6801234"
}'

响应 ​

成功时 HTTP 状态码为 200,顶层 code 为 0,结果在 data 里。失败时的返回见错误码与调用额度和业务错误码。

字段类型一定返回说明
data.template_idstring是模板 ID
data.codingstring是模板的短编号
data.web_urlstring是模板的扫码地址
data.project_idinteger是模板所在分区 ID,0 为默认分区
data.category_idinteger是模板所在目录 ID
data.namestring是模板名称
data.template_versionstring是模板版本。预校验、提交和修改时原样传回;模板变化后需要重新读取
data.groupsobject[]是字段分组
data.groups[].group_idstring是分组 ID
data.groups[].namestring是分组名称
data.groups[].fieldsobject[]是分组内的字段
data.groups[].fields[].field_idstring是字段 ID,填值时作为 values 的键
data.groups[].fields[].namestring是字段名称
data.groups[].fields[].typestring是字段类型:text 单行文本、textarea 多行文本、number 数字、date 日期、image 图片、file 附件
data.groups[].fields[].variableboolean是true 表示每个码各自填写;false 表示所有码共用同一内容(公共字段)
data.groups[].fields[].requiredboolean是是否必填
data.groups[].fields[].max_lengthinteger否文本类字段的最大长度
data.groups[].fields[].max_countinteger否图片、附件字段最多可放的文件数
data.groups[].fields[].exampleany否该类型字段的取值示例
data.groups[].fields[].public_valueany否公共字段的当前内容;图片、附件以 [{"existing_resource_id": ...}] 引用已有文件,修改时原样传回即保留
data.name_ruleany[]是子码命名规则,按顺序拼接;没有规则时为空数组
data.unsupported_fieldsobject[]是模板里不能通过接口填写的字段
data.unsupported_fields[].field_idstring是字段 ID
data.unsupported_fields[].namestring是字段名称
data.unsupported_fields[].typestring是字段类型
data.unsupported_fields[].variableboolean是是否每个码各自填写
data.unsupported_fields[].requiredboolean是是否必填
data.capabilitiesobject是这个模板支持的操作
data.capabilities.typesstring[]是可填写的字段类型
data.capabilities.delete_fieldboolean是是否可以删除字段,目前固定为 false
data.capabilities.change_typeboolean是是否可以修改字段类型,目前固定为 false
data.capabilities.editboolean是是否可以通过 templates/edit 修改名称和字段
data.capabilities.create_childrenboolean是是否可以用它批量建码
data.capabilities.replace_componentsboolean是是否可以通过 templates/edit 的 patch.components 修改正文图文组件
data.capabilities.unsupported_reasonsstring[]是不支持某些操作的原因
data.capabilities.blockersobject[]是阻止批量建码的问题;为空表示可以建码
data.capabilities.blockers[].codestring是错误码,含义见规范顶层的 x-error-catalog
data.capabilities.blockers[].pathstring否出错字段在请求体中的位置,如 items.0.values.12345;没有具体位置时为空字符串
data.capabilities.blockers[].item_keystring否批量数据中出错那一项的 item_key;不针对某一项时为空字符串
data.capabilities.blockers[].retryableboolean否原样重试是否可能成功
data.capabilities.blockers[].next_actionstring否建议的下一步:correct_input 修正入参;retry_later 稍后重试;retry_same_idempotency_key 用原幂等键重试;inspect_created_qrcode、inspect_created_form、inspect_result 先读取已保存的内容核对
data.capabilities.blockers[].messagestring否补充说明,部分错误才有
data.componentsobject[]是页面上可通过接口管理的图文组件,按页面顺序
data.components[].refstring否组件引用,如 c_123。修改时用 {"type":"keep","ref":...} 保留该组件,或在新内容上带 ref 原地替换
data.components[].typestring是组件类型:basic_info 基础信息;rich_text 富文本;gallery 图片或图集;file 文件;button 链接按钮。可选值:basic_info、rich_text、gallery、file、button
data.components[].htmlstring否rich_text:保存后的富文本 HTML
data.components[].itemsobject[]否gallery:图片列表
data.components[].items[].urlstring是图片地址
data.components[].urlstring否file:文件地址;button:跳转地址
data.components[].namestring否file:文件名
data.components[].textstring否button:按钮文字

响应示例 ​

json
{
  "code": 0,
  "message": "ok",
  "data": {
    "template_id": "6801234",
    "coding": "qTpl001",
    "web_url": "https://qr61.cn/oAbCdE/qTpl001",
    "project_id": 0,
    "category_id": 120045,
    "name": "设备档案",
    "template_version": "v_7c1e0f5a9b3d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e0f",
    "groups": [
      {
        "group_id": "g_901_0",
        "name": "设备信息",
        "fields": [
          {
            "field_id": "71399639089153",
            "name": "设备名称",
            "type": "text",
            "variable": true,
            "required": true,
            "max_length": 2000,
            "max_count": 10,
            "example": "001"
          },
          {
            "field_id": "71399639089154",
            "name": "设备照片",
            "type": "image",
            "variable": true,
            "required": false,
            "max_length": 20000,
            "max_count": 10,
            "example": []
          }
        ]
      }
    ],
    "name_rule": [
      {
        "type": "cmpId",
        "value": "71399639089153"
      }
    ],
    "unsupported_fields": [],
    "capabilities": {
      "types": [
        "text",
        "textarea",
        "number",
        "date",
        "image",
        "file"
      ],
      "delete_field": false,
      "change_type": false,
      "edit": true,
      "create_children": true,
      "unsupported_reasons": [],
      "blockers": [],
      "replace_components": true
    },
    "components": [
      {
        "ref": "c_901",
        "type": "basic_info"
      }
    ]
  }
}

常见错误 ​

TEMPLATE_NOT_FOUND、TEMPLATE_LOCKED、PERMISSION_DENIED。含义和处理方式见业务错误码。


本页由 openapi.json 生成。全部接口见接口清单。