文档首页/ 需求管理 CodeArts Req/ API参考/ API/ Scrum项目的设置/ 更新模板字段配置 - UpdateFieldTemplateById
更新时间:2026-09-15 GMT+08:00
分享

更新模板字段配置 - UpdateFieldTemplateById

功能介绍

更新模板字段的必填状态和显示状态。调用方通过接口传入字段配置列表,系统逐个校验并更新字段的is_required和is_visible属性。

调用方法

请参见如何调用API

授权信息

当前API调用无需身份策略权限。

URI

PUT /v2/projects/{project_id}/field-templates/{template_id}

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

参数解释

项目的32位uuid,项目唯一标识,通过查询项目列表接口获取,响应消息体中的project_id字段的值就是项目ID。

约束限制

32位的数字和字母组成的字符串。

取值范围

不涉及。

默认取值

不涉及。

template_id

String

参数解释

模板ID,通过查询模板字段配置获取,响应消息体中的template_id字段的值就是模板ID。

约束限制

不涉及。

取值范围

不涉及。

默认取值

不涉及。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

String

参数解释:

用户Token。 通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值)。

约束限制:

不涉及。

取值范围:

长度为10~32768个字符。

默认取值:

不涉及。

表3 请求Body参数

参数

是否必选

参数类型

描述

fields

Array of fields objects

参数解释

字段配置列表,用于批量更新模板中字段的必填状态和显示状态。

约束限制

数组类型,每个元素包含field、is_required、is_visible三个属性。

取值范围

不涉及。

默认取值

不涉及。

表4 fields

参数

是否必选

参数类型

描述

field

String

参数解释

字段标识,用于指定要更新的字段。

约束限制

不涉及。

取值范围

不涉及。

默认取值

不涉及。

is_required

Integer

参数解释

字段是否为必填状态。

约束限制

取值为0或1。

取值范围

  • 0:非必填

  • 1:必填

默认取值

0

is_visible

Boolean

参数解释

字段是否显示。

约束限制

取值为true或false。

取值范围

  • true:显示

  • false:隐藏

默认取值

true

响应参数

状态码:200

表5 响应Body参数

参数

参数类型

描述

success

Boolean

参数解释

请求是否成功。

取值范围

  • true:成功

  • false:失败

error_configs

Array of error_configs objects

参数解释

更新失败的字段模板信息。

取值范围

不涉及。

表6 error_configs

参数

参数类型

描述

field

String

参数解释

字段名称。

取值范围

不涉及。

field_type

String

参数解释

字段类型。

取值范围

不涉及。

is_visible

Boolean

参数解释

是否可见。

取值范围

不涉及。

is_required

Integer

参数解释

是否必填。

取值范围

不涉及。

error_message

String

参数解释

错误信息。

取值范围

不涉及。

状态码:400

表7 响应Body参数

参数

参数类型

描述

error_code

String

错误码

error_msg

String

错误描述

请求示例

更新模板字段配置

PUT https://{endpoint}/v2/projects/a6a33eca679b435b85574bd2fde46ce7/field-templates/384006

{
  "fields" : [ {
    "field" : "developer",
    "is_required" : 1,
    "is_visible" : true
  }, {
    "field" : "custom_field16",
    "is_required" : 0,
    "is_visible" : true
  }, {
    "field" : "status_id",
    "is_required" : 0,
    "is_visible" : true
  } ]
}

响应示例

状态码:200

{
  "success" : false,
  "error_configs" : [ {
    "field" : "assigned_to_id",
    "field_type" : "select",
    "is_required" : 1,
    "error_message" : "System field is_required cannot be changed."
  } ]
}

状态码

状态码

描述

200

更新模板字段配置接口成功的响应。

400

接口请求失败的响应。

错误码

请参见错误码

相关文档