文档首页/ 需求管理 CodeArts Req/ API参考/ API/ IPD字段管理/ 更新租户层字段 - UpdateIpdTenantField
更新时间：2026-09-01 GMT+08:00
在线调试
CLI示例
查看PDF
分享

更新租户层字段 - UpdateIpdTenantField

功能介绍

更新租户级字段。支持更新字段名称、描述，以及对单选列表、多选列表、层级字段选项的增删改。

调用方法

请参见如何调用API。

授权信息

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

URI

POST /v1/ipdprojectservice/tenant/fields/{field_id}

表1 路径参数

参数

是否必选

参数类型

描述

field_id

是

String

参数解释： 工作项字段ID，可通过。 查询IPD项目租户字段列表接口获取，响应消息体中的field_id字段的值就是工作项字段field_id。

约束限制： 2~32个字符。

取值范围： 不涉及。

默认取值： 不涉及。

请求参数

表2 请求Body参数

参数

是否必选

参数类型

描述

id

否

String

参数解释：

字段唯一标识。

取值范围：

5~32个字符。

code

否

String

参数解释：

字段编码。在项目中使用时一般使用code作为字段标识而不是字段ID。

取值范围：

不涉及。

display_name

否

String

参数解释：

字段显示名称。

取值范围：

不涉及。

created_by

否

String

参数解释：

字段创建人ID。

取值范围：

不涉及。

created_date

否

String

参数解释：

字段创建时间。时间戳格式，单位毫秒。

取值范围：

不涉及。

modified_by

否

String

参数解释：

字段最后修改人ID。

取值范围：

不涉及。

modified_date

否

String

参数解释：

字段最后修改时间。时间戳格式，单位毫秒。

取值范围：

不涉及。

field_type

否

String

参数解释：

字段类型标识。

取值范围：

不涉及。

field_type_id

否

String

参数解释：

字段类型ID。用于区分不同的字段类型。

取值范围：

不涉及。

field_type_name

否

String

参数解释：

字段类型名称。如单选列表、多选列表、多行文本等。

取值范围：

不涉及。

definition_type

否

String

参数解释：

字段定义类型。用于区分系统字段和自定义字段。

取值范围：

  • 1：系统字段。

  • 2：系统字段。

  • 3：系统字段。

  • 4：租户自定义字段。

  • 5：项目自定义字段。

show_on_card

否

Boolean

参数解释：

是否显示在云服务类型的迭代看板卡片模式中。

取值范围：

  • true：显示。

  • false：不显示。

optional

否

Boolean

参数解释：

字段是否为必填项。

取值范围：

  • true：必填。

  • false：非必填。

controlled

否

Boolean

参数解释：

字段是否受控。如果工作项已经基线，修改受控字段值时会触发变更评审。

取值范围：

  • true：受控。

  • false：不受控。

immutable

否

Boolean

参数解释：

字段是否不可变。更新接口无法更新不可变字段。

取值范围：

  • true：不可变。

  • false：可变。

no

否

Integer

参数解释：

字段排序序号。数值越小越靠前显示。

取值范围：

0~9999的整数。

default_value

否

String

参数解释：

字段默认值。创建工作项时自动填充。

取值范围：

不涉及。

option

否

OptionEntity object

参数解释：

字段选项。单选列表类型字段的选项信息，包含选项ID、编码、显示名称等属性。

取值范围：

不涉及。

all_options

否

Array of OptionEntity objects

参数解释：

字段所有选项。多选列表类型字段的全部选项信息，数组元素包含选项ID、编码、显示名称等属性。

取值范围：

不涉及。

has_same_display_name

否

Boolean

参数解释：

是否存在同名字段。用于检测字段名称冲突。

取值范围：

  • true：存在同名字段。

  • false：不存在同名字段。
表3 OptionEntity

参数

是否必选

参数类型

描述

id

否

String

参数解释：

选项id。

取值范围：

不涉及

code

否

String

参数解释：

选项code值。

取值范围：

不涉及

display_value

否

String

参数解释：

选项名称。

取值范围：

不涉及

value

否

String

参数解释：

选项唯一标识。

取值范围：

不涉及

level

否

Integer

参数解释：

选项层级。用于区分层级字段的层级深度。

取值范围：

1~4的整数，层级字段最多支持4层。

sequence

否

Integer

参数解释：

选项排序序号。数值越小越靠前显示。

取值范围：

0~2147483647。

parent_id

否

String

参数解释：

父选项ID。层级选项中指向父级选项的标识，顶级选项为空或null。

取值范围：

2~32个字符。

响应参数

状态码：200

表4 响应Body参数

参数

参数类型

描述

id

String

参数解释：

字段唯一标识。

取值范围：

5~32个字符。

code

String

参数解释：

字段编码。在项目中使用时一般使用code作为字段标识而不是字段ID。

取值范围：

不涉及。

display_name

String

参数解释：

字段显示名称。

取值范围：

不涉及。

created_by

String

参数解释：

字段创建人ID。

取值范围：

不涉及。

created_date

String

参数解释：

字段创建时间。时间戳格式，单位毫秒。

取值范围：

不涉及。

modified_by

String

参数解释：

字段最后修改人ID。

取值范围：

不涉及。

modified_date

String

参数解释：

字段最后修改时间。时间戳格式，单位毫秒。

取值范围：

不涉及。

field_type

String

参数解释：

字段类型标识。

取值范围：

不涉及。

field_type_id

String

参数解释：

字段类型ID。用于区分不同的字段类型。

取值范围：

不涉及。

field_type_name

String

参数解释：

字段类型名称。如单选列表、多选列表、多行文本等。

取值范围：

不涉及。

definition_type

String

参数解释：

字段定义类型。用于区分系统字段和自定义字段。

取值范围：

  • 1：系统字段。

  • 2：系统字段。

  • 3：系统字段。

  • 4：租户自定义字段。

  • 5：项目自定义字段。

show_on_card

Boolean

参数解释：

是否显示在云服务类型的迭代看板卡片模式中。

取值范围：

  • true：显示。

  • false：不显示。

optional

Boolean

参数解释：

字段是否为必填项。

取值范围：

  • true：必填。

  • false：非必填。

controlled

Boolean

参数解释：

字段是否受控。如果工作项已经基线，修改受控字段值时会触发变更评审。

取值范围：

  • true：受控。

  • false：不受控。

immutable

Boolean

参数解释：

字段是否不可变。更新接口无法更新不可变字段。

取值范围：

  • true：不可变。

  • false：可变。

no

Integer

参数解释：

字段排序序号。数值越小越靠前显示。

取值范围：

0~9999的整数。

default_value

String

参数解释：

字段默认值。创建工作项时自动填充。

取值范围：

不涉及。

option

OptionEntity object

参数解释：

字段选项。单选列表类型字段的选项信息，包含选项ID、编码、显示名称等属性。

取值范围：

不涉及。

all_options

Array of OptionEntity objects

参数解释：

字段所有选项。多选列表类型字段的全部选项信息，数组元素包含选项ID、编码、显示名称等属性。

取值范围：

不涉及。

has_same_display_name

Boolean

参数解释：

是否存在同名字段。用于检测字段名称冲突。

取值范围：

  • true：存在同名字段。

  • false：不存在同名字段。
表5 OptionEntity

参数

参数类型

描述

id

String

参数解释：

选项id。

取值范围：

不涉及

code

String

参数解释：

选项code值。

取值范围：

不涉及

display_value

String

参数解释：

选项名称。

取值范围：

不涉及

value

String

参数解释：

选项唯一标识。

取值范围：

不涉及

level

Integer

参数解释：

选项层级。用于区分层级字段的层级深度。

取值范围：

1~4的整数，层级字段最多支持4层。

sequence

Integer

参数解释：

选项排序序号。数值越小越靠前显示。

取值范围：

0~2147483647。

parent_id

String

参数解释：

父选项ID。层级选项中指向父级选项的标识，顶级选项为空或null。

取值范围：

2~32个字符。

状态码：400

表6 响应Body参数

参数

参数类型

描述

error_code

String

参数解释：

错误码。

取值范围：

不涉及。

error_msg

String

参数解释：

错误描述，对error_code的补充解释。

取值范围：

不涉及。

请求示例

  • 更新租户字段

    POST https://{endpoint}/v1/ipdprojectservice/tenant/fields/1162422376023437316

{
  "field_type_id" : "10001",
  "display_name" : "更新租户字段选项2",
  "option" : [ {
    "id" : "1162422376023437313",
    "display_value" : "A",
    "value" : "1162422376023437313",
    "code" : "1162422376023437313",
    "value_py" : "A",
    "sequence" : 0,
    "level" : 1,
    "domain_id" : "-1",
    "belong_definition_type" : "4",
    "disabled" : true
  }, {
    "id" : "1162422376023437314",
    "display_value" : "B",
    "value" : "1162422376023437314",
    "code" : "1162422376023437314",
    "value_py" : "B",
    "sequence" : 1,
    "level" : 1,
    "domain_id" : "-1",
    "belong_definition_type" : "4",
    "disabled" : true
  }, {
    "id" : "1162422376023437315",
    "display_value" : "C",
    "value" : "1162422376023437315",
    "code" : "1162422376023437315",
    "value_py" : "C",
    "sequence" : 2,
    "level" : 1,
    "domain_id" : "-1",
    "belong_definition_type" : "4",
    "disabled" : true
  } ],
  "id" : "1162422376023437316",
  "definition_type" : "4"
}

  • 修改层级字段

    https://{endpoint}/v1/ipdprojectservice/tenant/fields/1162425805358092292

{
  "field_type_id" : "10011",
  "display_name" : "更新租户层级字段",
  "option" : [ {
    "parent_node_id" : null,
    "node_id" : "745aff525721e70a2b5ebd341aa4ca1",
    "id" : "1162425805358092289",
    "display_value" : "A",
    "value" : "1162425805358092289",
    "code" : "1162425805358092289",
    "value_py" : "A",
    "sequence" : 0,
    "level" : 1,
    "domain_id" : "-1",
    "belong_definition_type" : "4",
    "label" : "A"
  }, {
    "parent_node_id" : "745aff525721e70a2b5ebd341aa4ca1",
    "node_id" : "02599ef5cd454dca63e3e91bcef100d",
    "parent_id" : "1162425805358092289",
    "id" : "1162425805358092290",
    "display_value" : "AAa1",
    "value" : "1162425805358092290",
    "code" : "1162425805358092290",
    "value_py" : "AA1",
    "sequence" : 0,
    "level" : 2,
    "domain_id" : "-1",
    "belong_definition_type" : "4",
    "label" : "AAa1",
    "isFocused" : false
  }, {
    "parent_node_id" : "02599ef5cd454dca63e3e91bcef100d",
    "node_id" : "098ed9566865dafa6cac4a8862aeff2",
    "parent_id" : "1162425805358092290",
    "id" : "1162425805358092291",
    "display_value" : "AAA1",
    "value" : "1162425805358092291",
    "code" : "1162425805358092291",
    "value_py" : "AAA1",
    "sequence" : 0,
    "level" : 3,
    "domain_id" : "-1",
    "belong_definition_type" : "4",
    "label" : "AAA1",
    "isLeaf" : true
  }, {
    "parent_node_id" : "745aff525721e70a2b5ebd341aa4ca1",
    "node_id" : "a4f6e6374b1f19291015cbcf070b278",
    "parent_id" : "1162425805358092289",
    "sequence" : 1,
    "display_value" : "AA2",
    "level" : 2,
    "isFocused" : false,
    "label" : "AA2",
    "value" : "a4f6e6374b1f19291015cbcf070b278"
  }, {
    "parent_node_id" : "a4f6e6374b1f19291015cbcf070b278",
    "node_id" : "b1133b7f570622c8a5934dfd11db85b",
    "display_value" : "AAA2",
    "sequence" : 0,
    "level" : 3,
    "isFocused" : false,
    "label" : "AAA2",
    "isLeaf" : true,
    "value" : "b1133b7f570622c8a5934dfd11db85b"
  } ],
  "id" : "1162425805358092292",
  "definition_type" : "4"
}

响应示例

状态码：200

ok

{
  "display_name" : "更新租户字段选项2",
  "name" : "c7354343193790545920",
  "id" : "1162422376023437316",
  "default_value" : "",
  "created_by" : "c2d89e38a64a466f8f945f595df4402d",
  "created_date" : "1755072691000",
  "modified_by" : "c2d89e38a64a466f8f945f595df4402d",
  "modified_date" : "1755072755000",
  "field_type_id" : "10001",
  "field_type_name" : "单选列表",
  "optional" : true,
  "option" : [ {
    "id" : "1162422376023437313",
    "display_value" : "A",
    "value" : "1162422376023437313",
    "code" : "1162422376023437313",
    "value_py" : "A",
    "sequence" : 0,
    "level" : 1,
    "domain_id" : "-1",
    "belong_definition_type" : "4"
  }, {
    "id" : "1162422376023437314",
    "display_value" : "B",
    "value" : "1162422376023437314",
    "code" : "1162422376023437314",
    "value_py" : "B",
    "sequence" : 1,
    "level" : 1,
    "domain_id" : "-1",
    "belong_definition_type" : "4"
  }, {
    "id" : "1162422376023437315",
    "display_value" : "C",
    "value" : "1162422376023437315",
    "code" : "1162422376023437315",
    "value_py" : "C",
    "sequence" : 2,
    "level" : 1,
    "domain_id" : "-1",
    "belong_definition_type" : "4"
  } ],
  "user_visibility" : true,
  "has_same_display_name" : false
}

状态码：400

请求失败的响应。例如无操作权限、项目不存在。

{
  "error_code" : "PM.02174103",
  "error_msg" : "无操作权限"
}

状态码

状态码

描述

200

ok

400

请求失败的响应。例如无操作权限、项目不存在。

错误码

请参见错误码。

父主题： IPD字段管理

相关文档