UIP TM 自定义字段

“uip tm 自定义字段”的语法和选项，用于管理 Test Manager 项目中的自定义字段定义、标签行和值行。

uip tm customfield 管理 Test Manager 项目的自定义字段定义。自定义字段使用项目特定的元数据扩展需求、测试用例和测试集。此命令组包含三个子组：

• customfield — 管理字段定义本身（列出、获取、创建、更新、删除）
• customfield label — 管理标签类型字段行（每个对象的字段名称到一个或多个字符串值的 JSON 映射）
• customfield value — 管理文本类型字段行（每个对象的单个字符串值）

重要提示：

字段定义的主要标识符为 --field-id。标签和值行由 --label-id/--value-id 或自然键 --object-type + --name + --object-id 标识。标志 --customfield-id 不存在。

大纲

# Field definitions
uip tm customfield list --project-key <key> [--object-types <types...>] [--data-types <types...>] [--name <name>] [--filter <text>] [--sort-by <expr>] [--limit <n>] [--offset <n>]
uip tm customfield get --project-key <key> (--field-id <uuid> | --name <name> --object-type <type>)
uip tm customfield create --project-key <key> --name <name> --data-type <Text|Label> (--object-type <type> | --scope-list <types...>) [--description <text>] [--default-value <value>] [--value-hints <hints>]
uip tm customfield update --project-key <key> (--field-id <uuid> | --name <name> --object-type <type>) [--rename-to <name>] [--description <text>] [--default-value <value>] [--value-hints <hints>] [--scope-list <types...>]
uip tm customfield delete --project-key <key> (--field-ids <uuid...> | --name <name> --object-type <type>) [-y]

# Labels
uip tm customfield label get --project-key <key> --object-type <type> --label-id <uuid>
uip tm customfield label list --project-key <key> --object-type <type> [--object-id <uuid>] [--filter <text>] [--sort-by <expr>] [--limit <n>] [--offset <n>]
uip tm customfield label create --project-key <key> --object-type <type> --object-id <uuid> --values <json>
uip tm customfield label add --project-key <key> --object-type <type> --custom-field-name <name> --object-ids <uuid...> --values <value...> [--replace-existing-values]
uip tm customfield label remove --project-key <key> --object-type <type> --custom-field-name <name> --object-ids <uuid...> (--values <value...> | --remove-all-values) [-y]

# Values
uip tm customfield value list --project-key <key> --object-type <type> [--object-id <uuid>] [--filter <text>] [--sort-by <expr>] [--limit <n>] [--offset <n>]
uip tm customfield value get --project-key <key> --object-type <type> (--value-id <uuid> | --name <name> --object-id <uuid>)
uip tm customfield value create --project-key <key> --object-type <type> --name <name> --object-id <uuid> --data-type <Text|Label> [--value <text>]
uip tm customfield value update --project-key <key> --object-type <type> (--value-id <uuid> | --name <name> --object-id <uuid>) [--data-type <Text|Label>] (--value <text> | --clear)
uip tm customfield value delete --project-key <key> --object-type <type> (--value-id <uuid> | --name <name> --object-id <uuid>) [-y]

所有动词都遵循全局选项和标准退出代码。每个动词接受 --log-level <level>（默认为 Information）和 -t, --tenant <name>（默认为经过身份验证的租户）。

备注：

此处的 -t, --tenant 是一个正常的可见选项。

--object-type（以及 --object-types/--scope-list，当变量为变量时）仅接受 Requirement、TestCase 或 TestSet。--data-type（和 --data-types）仅接受 Text 或 Label，没有 String、Integer 或 Boolean 数据类型。

---

字段定义命令

UIP TM 自定义字段列表

列出项目中的自定义字段定义。必须填写--project-key ；所有其他筛选条件为可选。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-types <types...> — 要按空格分隔的对象类型：Requirement、TestCase、TestSet。
• --data-types <types...> — 要按空格分隔的数据类型：Text、Label。
• --name <name> — 精确名称匹配（客户端筛选器；为定义字段的每个对象类型返回一行）。
• --filter <text> — 跨定义字段的服务器端子字符串搜索。
• --sort-by <expr> — 排序表达式，例如 name asc。
• --limit <n> — 页面大小。默认为50 。
• --offset <n> — 要跳过的结果。默认为0 。

示例

uip tm customfield list \
  --project-key DEMO \
  --object-types TestCase

数据形状

{
  "Code": "CustomFieldDefinitionsList",
  "Data": [
    {
      "Id": "a1b2c3d4-0000-0000-0000-000000000001",
      "ProjectId": "p1",
      "Name": "Priority",
      "Description": "Test priority",
      "DefaultValue": "Medium",
      "ValueHints": "",
      "ObjectType": "TestCase",
      "DataType": "Text",
      "ScopeList": ["TestCase"]
    }
  ]
}

---

UIP TM 自定义字段获取

获取单个自定义字段定义。通过 --field-id 识别，或通过 --name + --object-type 识别。

选项

• --project-key <key> （必填） — 拥有项目。
• --field-id <uuid> — 字段 UUID。
• --name <name> — 字段名称。与--object-type一起使用。
• --object-type <type> — 字段所属的对象类型：Requirement、TestCase、TestSet。与 --name 一起使用。

示例

uip tm customfield get \
  --project-key DEMO \
  --field-id a1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "CustomFieldDefinitionGet",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "ProjectId": "p1",
    "Name": "Priority",
    "Description": "Test priority",
    "DefaultValue": "Medium",
    "ValueHints": "",
    "ObjectType": "TestCase",
    "DataType": "Text",
    "ScopeList": ["TestCase"]
  }
}

---

UIP TM 自定义字段创建

创建新的自定义字段定义。为单个作用域提供 --object-type，为多个作用域提供 --scope-list — 两者互斥，必须选择一个。

选项

• --project-key <key> （必填） — 拥有项目。
• --name <name> （必填） — 字段名称。
• --data-type <type> （必填） — Text或Label 。
• --object-type <type> — 单个作用域：Requirement、TestCase、TestSet。与 --scope-list 互斥。
• --scope-list <types...> — 多对象作用域（以空格分隔）：Requirement、TestCase、TestSet。与 --object-type 互斥。
• --description <text> — 字段说明。
• --default-value <text> — 默认值种子到字段类型的每个现有对象。
• --value-hints <text> — 显示在字段旁边的用户界面提示文本。

示例

uip tm customfield create \
  --project-key DEMO \
  --name Priority \
  --data-type Text \
  --object-type TestCase \
  --description "Test priority" \
  --default-value Medium

数据形状

{
  "Code": "CustomFieldDefinitionCreate",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "ProjectId": "p1",
    "Name": "Priority",
    "Description": "Test priority",
    "DefaultValue": "Medium",
    "ValueHints": "",
    "ObjectType": "TestCase",
    "DataType": "Text",
    "ScopeList": ["TestCase"]
  }
}

---

UIP TM 自定义字段更新

更新现有自定义字段定义。通过 --field-id 识别，或通过 --name + --object-type 识别。未指定的字段将保留其当前值。

选项

• --project-key <key> （必填） — 拥有项目。
• --field-id <uuid> — 字段 UUID。
• --name <name> — 字段名称（用于查找）。与 --object-type 一起使用。
• --object-type <type> — 字段所属的对象类型。与 --name 一起使用。
• --rename-to <name> — 字段的新名称。
• --description <text> — 新说明。
• --default-value <text> — 新的默认值。
• --value-hints <text> — 新的用户界面提示文本。
• --scope-list <types...> — 新的多对象作用域（用空格分隔）。

示例

uip tm customfield update \
  --project-key DEMO \
  --field-id a1b2c3d4-0000-0000-0000-000000000001 \
  --rename-to Severity

数据形状

{
  "Code": "CustomFieldDefinitionUpdate",
  "Data": {
    "Id": "a1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Severity",
    "Result": "Updated"
  }
}

---

UIP TM 自定义字段删除

删除一个或多个自定义字段定义。通过 --field-ids（一个或多个 UUID）识别，或通过 --name + --object-type（单个，通过自然键）识别。硬删除不级联 —不清理孤立标签/值行。

选项

• --project-key <key> （必填） — 拥有项目。
• --field-ids <uuid...> — 要删除的字段 UUID（以空格分隔）。
• --name <name> — 字段名称（与 --object-type 一起使用）。
• --object-type <type> — 字段所属的对象类型（与 --name 一起使用）。
• -y, --yes — 确认此不可撤销的操作。必需 — CLI 从不提示。

示例

uip tm customfield delete \
  --project-key DEMO \
  --field-ids a1b2c3d4-0000-0000-0000-000000000001 \
  --yes

数据形状

{
  "Code": "CustomFieldDefinitionsDelete",
  "Data": { "Passed": 1, "Failed": 0 }
}

Passed/Failed 是计数，而不是每个 ID 的详细信息 — 响应不会回显失败的 UUID。经由 --field-ids 传递的未知 UUID 会转发到批量端点并计为 Failed，而不是预先拒绝。

---

标签命令

标签行的每个对象实例包含一个 JSON 对象，将自定义字段名称映射到字符串值数组 ({"Priority":["High"],"Tags":["smoke","critical"]})。

uip tm 自定义字段标签获取

按 --label-id 获取自定义字段标签行。要按对象查找，请使用 customfield label list --object-id <uuid>（作为单元素数组返回相同的行）。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-type <type> （必填项） — 标签所属的对象类型： Requirement 、 TestCase 、 TestSet 。
• --label-id <uuid> （必填） — 标签行的 UUID（而非标签名称）。

示例

uip tm customfield label get \
  --project-key DEMO \
  --object-type TestCase \
  --label-id f1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "CustomFieldLabelGet",
  "Data": {
    "Id": "f1b2c3d4-0000-0000-0000-000000000001",
    "ProjectId": "p1",
    "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ObjectType": "TestCase",
    "Values": { "Priority": ["High"], "Tags": ["smoke", "critical"] },
    "Created": "2025-01-01T00:00:00Z",
    "CreatedBy": "[e-mail]",
    "Updated": "2025-01-02T00:00:00Z",
    "UpdatedBy": "[e-mail]"
  }
}

---

uip tm 自定义字段标签列表

列出某一对象类型的标签行，并可选择缩小范围至特定对象。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-type <type> （必填） — 要为其列出标签的对象类型。
• --object-id <uuid> — 筛选出特定对象 UUID。
• --filter <text> — 按值搜索标签行。
• --sort-by <expr> — 排序表达式。
• --limit <n> — 页面大小。默认为50 。
• --offset <n> — 要跳过的结果。默认为0 。

示例

uip tm customfield label list \
  --project-key DEMO \
  --object-type TestCase \
  --object-id a1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "CustomFieldLabelsList",
  "Data": [
    {
      "Id": "f1b2c3d4-0000-0000-0000-000000000001",
      "ProjectId": "p1",
      "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
      "ObjectType": "TestCase",
      "Values": { "Priority": ["High"], "Tags": ["smoke", "critical"] },
      "Created": "2025-01-01T00:00:00Z",
      "CreatedBy": "[e-mail]",
      "Updated": "2025-01-02T00:00:00Z",
      "UpdatedBy": "[e-mail]"
    }
  ]
}

---

uip tm 自定义字段标签创建

更新插入对象的标签值。后端会将任何新的字段名称键合并到同一对象的现有行中 — 不会替换整行。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-type <type> （必填） — 要将标签附加到的对象类型。
• --object-id <uuid> （必填） — 要标记的对象的 UUID。
• --values <json> （必填） — 将字段名称映射到字符串数组的非空 JSON对象，例如{"Priority":["High"],"Tags":["smoke","critical"]} 。客户端会拒绝 JSON 数组或不是每个键的字符串数组的值。

示例

uip tm customfield label create \
  --project-key DEMO \
  --object-type TestCase \
  --object-id a1b2c3d4-0000-0000-0000-000000000001 \
  --values '{"Priority":["High"],"Tags":["smoke"]}'

数据形状

{
  "Code": "CustomFieldLabelCreate",
  "Data": {
    "Id": "f1b2c3d4-0000-0000-0000-000000000001",
    "ProjectId": "p1",
    "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ObjectType": "TestCase",
    "Values": { "Priority": ["High"], "Tags": ["smoke"] },
    "Created": "2025-01-01T00:00:00Z",
    "CreatedBy": "[e-mail]",
    "Updated": "2025-01-01T00:00:00Z",
    "UpdatedBy": "[e-mail]"
  }
}

---

UIP TM 自定义字段标签添加

通过单次调用将标签值添加到多个对象的命名自定义字段。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-type <type> （必填） — 对象类型。
• --custom-field-name <name> （必填） — 此对象类型的现有自定义字段定义的名称。
• --object-ids <uuid...> （必填） — 要应用标签的对象 UUID，以空格分隔。
• --values <value...> （必填） — 要添加的以空格分隔的标签值。
• --replace-existing-values — 替换现有值而不是合并（默认值：合并）。

示例

uip tm customfield label add \
  --project-key DEMO \
  --object-type TestCase \
  --custom-field-name Priority \
  --object-ids id1 id2 \
  --values High Critical

数据形状

{
  "Code": "CustomFieldLabelAdd",
  "Data": {
    "CustomFieldName": "Priority",
    "ObjectCount": 2,
    "Result": "Added"
  }
}

---

uip tm 自定义字段标签删除

从多个对象的一个命名自定义字段中移除标签值。这是破坏性操作 — 需要-y, --yes ； CLI 从不提示。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-type <type> （必填） — 对象类型。
• --custom-field-name <name> （必填） — 自定义字段的名称。
• --object-ids <uuid...> （必填项） — 以空格分隔的对象 UUID。
• --values <value...> — 要删除的以空格分隔的标签值。除非设置了 --remove-all-values，否则为必填项。
• --remove-all-values — 清除此字段在所列对象上的所有值。与 --values 互斥。
• -y, --yes — 确认此不可撤销的操作。必需 — CLI 从不提示。

示例

uip tm customfield label remove \
  --project-key DEMO \
  --object-type TestCase \
  --custom-field-name Priority \
  --object-ids id1 id2 \
  --values Critical \
  --yes

数据形状

{
  "Code": "CustomFieldLabelRemove",
  "Data": {
    "CustomFieldName": "Priority",
    "ObjectCount": 2,
    "Result": "Removed"
  }
}

---

值命令

每个对象的值行包含一个文本类型的值。

UIP TM 自定义字段值列表

列出对象类型的自定义字段值。除非提供 --object-id，否则结果为空。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-type <type> （必填） — 对象类型。
• --object-id <uuid> — 要列出其值的对象 UUID。实践中为必要项 — 省略时，结果为空。
• --filter <text> — 按内容搜索值。
• --sort-by <expr> — 排序表达式。
• --limit <n> — 页面大小。默认为50 。
• --offset <n> — 要跳过的结果。默认为0 。

示例

uip tm customfield value list \
  --project-key DEMO \
  --object-type TestCase \
  --object-id a1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "CustomFieldValuesList",
  "Data": [
    {
      "Id": "v1b2c3d4-0000-0000-0000-000000000001",
      "Name": "Priority",
      "Value": "High",
      "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
      "ObjectType": "TestCase",
      "DataType": "Text",
      "Updated": "2025-01-02T00:00:00Z"
    }
  ]
}

---

获取 UIP TM 自定义字段值

获取单个自定义字段值行。通过 --value-id 识别，或通过 --name + --object-id 识别。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-type <type> （必填） — 对象类型。
• --value-id <uuid> — 值行 UUID。
• --name <name> — 字段名称。与--object-id一起使用。
• --object-id <uuid> — 对象 UUID。与--name一起使用。

示例

uip tm customfield value get \
  --project-key DEMO \
  --object-type TestCase \
  --value-id v1b2c3d4-0000-0000-0000-000000000001

数据形状

{
  "Code": "CustomFieldValueGet",
  "Data": {
    "Id": "v1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Priority",
    "Value": "High",
    "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ObjectType": "TestCase",
    "DataType": "Text",
    "Updated": "2025-01-02T00:00:00Z"
  }
}

---

UIP TM 自定义字段值创建

在对象上创建自定义字段值行。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-type <type> （必填） — 对象类型。
• --name <name> （必填） — 自定义字段名称（必须与现有定义匹配）。
• --object-id <uuid> （必填） — 此值附加到的对象 UUID。
• --data-type <type> （必填） — Text或Label （必须与定义相符）。
• --value <text> — 值内容。可选 — 省略此步骤，将创建空行。

示例

uip tm customfield value create \
  --project-key DEMO \
  --object-type TestCase \
  --name Priority \
  --object-id a1b2c3d4-0000-0000-0000-000000000001 \
  --data-type Text \
  --value High

数据形状

{
  "Code": "CustomFieldValueCreate",
  "Data": {
    "Id": "v1b2c3d4-0000-0000-0000-000000000001",
    "Name": "Priority",
    "Value": "High",
    "ObjectId": "a1b2c3d4-0000-0000-0000-000000000001",
    "ObjectType": "TestCase",
    "DataType": "Text",
    "Updated": "2025-01-02T00:00:00Z"
  }
}

---

更新 UIP TM 自定义字段值

更新现有的自定义字段值行。通过 --value-id 识别，或通过 --name + --object-id 识别。除非传递了 --value，否则 --clear 为必填项。

备注：

当行的字段名称不再映射到定义时，空的 --value 可能会导致行被删除而不是更新。传递 --clear 以确认该意图。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-type <type> （必填） — 对象类型。
• --value-id <uuid> — 值行 UUID。
• --name <name> — 字段名称。与--object-id一起使用。
• --object-id <uuid> — 对象 UUID。与--name一起使用。
• --data-type <type> — Text 或 Label。默认为行的当前数据类型。
• --value <text> — 新值。除非通过 --clear，否则为必填项。
• --clear — 确认空的 --value 可能会删除行。

示例

uip tm customfield value update \
  --project-key DEMO \
  --object-type TestCase \
  --value-id v1b2c3d4-0000-0000-0000-000000000001 \
  --value Critical

数据形状

{
  "Code": "CustomFieldValueUpdate",
  "Data": {
    "Id": "v1b2c3d4-0000-0000-0000-000000000001",
    "Result": "Updated"
  }
}

---

UIP TM 自定义字段值删除

删除自定义字段值行。通过 --value-id 识别，或通过 --name + --object-id 识别。

选项

• --project-key <key> （必填） — 拥有项目。
• --object-type <type> （必填） — 对象类型。
• --value-id <uuid> — 值行 UUID。
• --name <name> — 字段名称。与--object-id一起使用。
• --object-id <uuid> — 对象 UUID。与--name一起使用。
• -y, --yes — 确认此不可撤销的操作。必需 — CLI 从不提示。

示例

uip tm customfield value delete \
  --project-key DEMO \
  --object-type TestCase \
  --value-id v1b2c3d4-0000-0000-0000-000000000001 \
  --yes

数据形状

{
  "Code": "CustomFieldValueDelete",
  "Data": {
    "Id": "v1b2c3d4-0000-0000-0000-000000000001",
    "Result": "Deleted"
  }
}

---

相关内容

• requirements — 要求可以包含自定义字段值。
• 测试用例— 测试用例可以携带自定义字段值。

另请参阅

• Test Manager 概述