读取官方模板详情
读取官方模板详情:用途、creation_schema 可填写字段、保留的组件和 compatibility 限制。只读,不安装。can_create 为 true 可批量建码;仅 can_create_single 为 true 时只能用 gallery/create-qrcode 生成单个码。
请求
text
POST https://open.cli.im/api/v2/rpc/gallery/get| 项目 | 要求 |
|---|---|
| 最低权限 | 只读,见权限档位 |
| 需要的 scope | templates.read |
| 组织 Key | 不能调用,返回 403 credential_type_not_allowed,见历史组织 Key |
请求参数
请求体为 JSON。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
gallery_template_id | string | 是 | 官方模板 ID,取自 gallery/list;不是账号内模板的 template_id |
请求示例
示例里的 ID、幂等键等换成实际值。
bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/gallery/get' \
-H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"gallery_template_id": "30128"
}'响应
成功时 HTTP 状态码为 200,顶层 code 为 0,结果在 data 里。失败时的返回见错误码与调用额度和业务错误码。
| 字段 | 类型 | 一定返回 | 说明 |
|---|---|---|---|
data.template | object | 是 | 官方模板详情 |
data.template.gallery_template_id | string | 是 | 官方模板 ID |
data.template.package_id | string | 是 | 模板安装包 ID |
data.template.name | string | 是 | 模板名称 |
data.template.description | string | 是 | 模板简介 |
data.template.src_subtype | integer | 是 | 模板子类型编号 |
data.template.installation_mode | integer | 是 | 安装方式编号 |
data.template.form_count | integer | 是 | 模板包含的表单数 |
data.template.state_count | integer | 是 | 模板包含的状态数 |
data.template.supports_single | boolean | 是 | 是否支持生成单个码 |
data.template.long_description | string | 是 | 模板详细介绍 |
data.template.template_version | string | 是 | 模板版本 |
data.template.creation_schema | object | 是 | 批量建码时可填写的字段 |
data.template.creation_schema.groups | object[] | 是 | 字段分组 |
data.template.creation_schema.groups[].group_id | string | 是 | 分组 ID |
data.template.creation_schema.groups[].name | string | 是 | 分组名称 |
data.template.creation_schema.groups[].fields | object[] | 是 | 分组内的字段 |
data.template.creation_schema.unsupported_fields | object[] | 是 | 模板里不能通过接口填写的字段 |
data.template.creation_schema.unsupported_fields[].field_id | string | 是 | 字段 ID |
data.template.creation_schema.unsupported_fields[].name | string | 是 | 字段名称 |
data.template.creation_schema.unsupported_fields[].type | string | 是 | 字段类型 |
data.template.creation_schema.unsupported_fields[].variable | boolean | 是 | 是否每个码各自填写 |
data.template.creation_schema.unsupported_fields[].required | boolean | 是 | 是否必填 |
data.template.creation_schema.blockers | object[] | 是 | 阻止批量建码的问题 |
data.template.creation_schema.blockers[].code | string | 是 | 错误码,含义见规范顶层的 x-error-catalog |
data.template.creation_schema.blockers[].path | string | 否 | 出错字段在请求体中的位置,如 items.0.values.12345;没有具体位置时为空字符串 |
data.template.creation_schema.blockers[].item_key | string | 否 | 批量数据中出错那一项的 item_key;不针对某一项时为空字符串 |
data.template.creation_schema.blockers[].retryable | boolean | 否 | 原样重试是否可能成功 |
data.template.creation_schema.blockers[].next_action | string | 否 | 建议的下一步:correct_input 修正入参;retry_later 稍后重试;retry_same_idempotency_key 用原幂等键重试;inspect_created_qrcode、inspect_created_form、inspect_result 先读取已保存的内容核对 |
data.template.creation_schema.blockers[].message | string | 否 | 补充说明,部分错误才有 |
data.template.components | object[] | 是 | 模板包含的页面组件 |
data.template.components[].type | string | 是 | 组件类型 |
data.template.components[].behavior | string | 是 | 固定为 preserve,安装时原样保留 |
data.template.compatibility | object | 是 | 这个模板能做什么 |
data.template.compatibility.can_create | boolean | 是 | 是否可以用 gallery/prepare-creation 批量建码 |
data.template.compatibility.can_create_single | boolean | 是 | 是否可以用 gallery/create-qrcode 生成单个码 |
data.template.compatibility.can_add_fields | boolean | 是 | 准备方案时是否可以用 extra_fields 追加字段 |
data.template.compatibility.blockers | object[] | 是 | 阻止批量建码的问题;为空表示可以批量建码 |
data.template.compatibility.blockers[].code | string | 是 | 错误码,含义见规范顶层的 x-error-catalog |
data.template.compatibility.blockers[].path | string | 否 | 出错字段在请求体中的位置,如 items.0.values.12345;没有具体位置时为空字符串 |
data.template.compatibility.blockers[].item_key | string | 否 | 批量数据中出错那一项的 item_key;不针对某一项时为空字符串 |
data.template.compatibility.blockers[].retryable | boolean | 否 | 原样重试是否可能成功 |
data.template.compatibility.blockers[].next_action | string | 否 | 建议的下一步:correct_input 修正入参;retry_later 稍后重试;retry_same_idempotency_key 用原幂等键重试;inspect_created_qrcode、inspect_created_form、inspect_result 先读取已保存的内容核对 |
data.template.compatibility.blockers[].message | string | 否 | 补充说明,部分错误才有 |
data.template.compatibility.unsupported_fields | object[] | 是 | 模板里不能通过接口填写的字段 |
data.template.compatibility.unsupported_fields[].field_id | string | 是 | 字段 ID |
data.template.compatibility.unsupported_fields[].name | string | 是 | 字段名称 |
data.template.compatibility.unsupported_fields[].type | string | 是 | 字段类型 |
data.template.compatibility.unsupported_fields[].variable | boolean | 是 | 是否每个码各自填写 |
data.template.compatibility.unsupported_fields[].required | boolean | 是 | 是否必填 |
响应示例
json
{
"code": 0,
"message": "ok",
"data": {
"template": {
"gallery_template_id": "30128",
"package_id": "88213",
"name": "设备巡检",
"description": "适用于设备日常巡检和点检记录。",
"src_subtype": 1,
"installation_mode": 3,
"form_count": 1,
"state_count": 0,
"supports_single": true,
"long_description": "包含设备基础信息和巡检表单,扫码即可填写巡检记录。",
"template_version": "1d2c3b4a5f6e708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f809",
"creation_schema": {
"groups": [
{
"group_id": "placeholder_0",
"name": "设备信息",
"fields": [
{
"field_id": "f3a9c1e07b5d",
"name": "设备名称",
"type": "text",
"variable": true,
"required": true,
"max_length": 2000,
"max_count": 10,
"example": "001"
}
]
}
],
"unsupported_fields": [],
"blockers": []
},
"components": [
{
"type": "basicInfo",
"behavior": "preserve"
},
{
"type": "recordview",
"behavior": "preserve"
}
],
"compatibility": {
"can_create": true,
"blockers": [],
"unsupported_fields": [],
"can_create_single": true,
"can_add_fields": true
}
}
}
}常见错误
GALLERY_TEMPLATE_NOT_FOUND、GALLERY_PACKAGE_UNAVAILABLE。含义和处理方式见业务错误码。
本页由 openapi.json 生成。全部接口见接口清单。