> ## Documentation Index
> Fetch the complete documentation index at: https://docs-docflow.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 字段管理

> 管理文件类别下的普通字段和表格字段

<Tip>
  字段是文件类别中用于定义抽取内容的核心配置。DocFlow 支持两种类型的字段：普通字段（在 result.fields 中）和表格字段（在 result.tables\[].fields 中）。本文介绍如何通过 API 管理这些字段。
</Tip>

## 获取字段列表

获取指定文件类别下的所有字段列表，包括普通字段和表格字段：

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/list?workspace_id=<your-workspace-id>&category_id=<category-id>"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"

  host = "https://docflow.textin.com"
  url = "/api/app-api/sip/platform/v2/category/fields/list"

  resp = requests.get(
      url=f"{host}{url}",
      params={
          "workspace_id": workspace_id,
          "category_id": category_id
      },
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      fields = result.get("result", {}).get("fields", [])
      tables = result.get("result", {}).get("tables", [])

      print("普通字段：")
      for field in fields:
          print(f"  字段ID: {field.get('id')}, 名称: {field.get('name')}")

      print("\n表格字段：")
      for table in tables:
          print(f"  表格: {table.get('name')} (ID: {table.get('id')})")
          for field in table.get("fields", []):
              print(f"    字段ID: {field.get('id')}, 名称: {field.get('name')}")
  else:
      print(f"获取失败: {result.get('msg')}")
  ```
</CodeGroup>

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "fields": [
      {
        "id": "field_123",
        "name": "发票代码",
        "description": "发票代码描述",
        "prompt": "请抽取发票代码"
      },
      {
        "id": "field_456",
        "name": "发票金额",
        "description": "发票金额描述"
      }
    ],
    "tables": [
      {
        "id": "table_789",
        "name": "货物明细",
        "description": "发票货物明细表",
        "fields": [
          {
            "id": "field_101",
            "name": "货物名称",
            "description": "货物名称描述"
          },
          {
            "id": "field_102",
            "name": "数量",
            "description": "货物数量"
          }
        ]
      }
    ]
  }
}
```

## 新增字段

在指定文件类别下批量新增字段，支持新增普通字段和表格字段：

### 新增普通字段

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "fields": [
        {
          "name": "发票号码",
          "description": "发票号码描述",
          "prompt": "请抽取发票号码",
          "use_prompt": true,
          "alias": ["Invoice Number", "编号"],
          "identity": "invoice_number",
          "multi_value": false
        }
      ]
    }' \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/batch_add"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"

  host = "https://docflow.textin.com"
  url = "/api/app-api/sip/platform/v2/category/fields/batch_add"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "fields": [
          {
              "name": "发票号码",
              "description": "发票号码描述",
              "prompt": "请抽取发票号码",
              "use_prompt": True,
              "alias": ["Invoice Number", "编号"],
              "identity": "invoice_number",
              "multi_value": False
          }
      ]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      field_ids = result.get("result", {}).get("field_ids", [])
      print(f"字段创建成功，IDs: {field_ids}")
  else:
      print(f"创建失败: {result.get('msg')}")
  ```
</CodeGroup>

### 新增表格字段

如果要在表格下新增字段，需要传入 `table_id` 参数：

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "table_id": "<table-id>",
      "fields": [
        {
          "name": "单价",
          "description": "商品单价"
        }
      ]
    }' \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/batch_add"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"
  table_id = "<table-id>"

  host = "https://docflow.textin.com"
  url = "/api/app-api/sip/platform/v2/category/fields/batch_add"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "table_id": table_id,  # 指定表格ID，创建表格字段
      "fields": [
          {
              "name": "单价",
              "description": "商品单价"
          }
      ]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      field_ids = result.get("result", {}).get("field_ids", [])
      print(f"表格字段创建成功，IDs: {field_ids}")
  else:
      print(f"创建失败: {result.get('msg')}")
  ```
</CodeGroup>

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `table_id` (选填): 表格 ID。不传或为空：创建普通字段；传入表格ID：创建表格字段
* `fields` (必填): 字段数组，每个元素包含以下属性：
  * `name` (必填): 字段名称
  * `description` (选填): 字段描述
  * `prompt` (选填): 语义抽取提示词
  * `use_prompt` (选填): 是否使用语义提示词
  * `alias` (选填): 字段别名数组
  * `identity` (选填): 导出字段名
  * `multi_value` (选填): 是否多值抽取
  * `duplicate_value_distinct` (选填): 是否重复值去重（仅当 multi\_value 为 true 时有效）
  * `transform_settings` (选填): 转换配置

**响应示例：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "result": {
    "field_ids": ["field_new_123"]
  }
}
```

## 更新字段

批量更新指定字段的信息，支持更新普通字段和表格字段：

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "fields": [
        {
          "field_id": "<field-id>",
          "name": "更新后的字段名称",
          "description": "更新后的描述",
          "prompt": "更新后的提示词"
        }
      ]
    }' \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/batch_update"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"
  field_id = "<field-id>"

  host = "https://docflow.textin.com"
  url = "/api/app-api/sip/platform/v2/category/fields/batch_update"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "fields": [
          {
              "field_id": field_id,
              "name": "更新后的字段名称",
              "description": "更新后的描述",
              "prompt": "更新后的提示词"
          }
      ]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      print("字段更新成功")
  else:
      print(f"更新失败: {result.get('msg')}")
  ```
</CodeGroup>

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `table_id` (选填): 表格 ID。对普通字段可不传；对表格字段需要传入其所属的表格ID
* `fields` (必填): 字段数组，每个元素包含以下属性：
  * `field_id` (必填): 字段 ID
  * 其他属性与创建字段相同（name、description、prompt 等）

<Note>
  更新表格字段时，需要传入 `table_id` 参数指定该字段所属的表格。
</Note>

## 删除字段

删除指定的字段，支持批量删除普通字段和表格字段：

### 删除普通字段

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "field_ids": ["field_123", "field_456"]
    }' \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/delete"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"

  host = "https://docflow.textin.com"
  url = "/api/app-api/sip/platform/v2/category/fields/delete"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "field_ids": ["field_123", "field_456"]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      print("普通字段删除成功")
  else:
      print(f"删除失败: {result.get('msg')}")
  ```
</CodeGroup>

### 删除表格字段

如果要删除表格字段，需要传入 `table_id` 参数：

<CodeGroup>
  ```bash curl icon=terminal wrap theme={null}
  curl -X POST \
    -H "x-ti-app-id: <your-app-id>" \
    -H "x-ti-secret-code: <your-secret-code>" \
    -H "Content-Type: application/json" \
    -d '{
      "workspace_id": "<your-workspace-id>",
      "category_id": "<category-id>",
      "table_id": "<table-id>",
      "field_ids": ["field_101", "field_102"]
    }' \
    "https://docflow.textin.com/api/app-api/sip/platform/v2/category/fields/delete"
  ```

  ```python Python icon=python expandable lines theme={null}
  import requests

  ti_app_id = "<your-app-id>"
  ti_secret_code = "<your-secret-code>"
  workspace_id = "<your-workspace-id>"
  category_id = "<category-id>"
  table_id = "<table-id>"

  host = "https://docflow.textin.com"
  url = "/api/app-api/sip/platform/v2/category/fields/delete"

  payload = {
      "workspace_id": workspace_id,
      "category_id": category_id,
      "table_id": table_id,  # 指定表格ID，删除表格字段
      "field_ids": ["field_101", "field_102"]
  }

  resp = requests.post(
      url=f"{host}{url}",
      json=payload,
      headers={
          "x-ti-app-id": ti_app_id,
          "x-ti-secret-code": ti_secret_code,
      },
      timeout=30,
  )

  result = resp.json()
  if result.get("code") == 200:
      print("表格字段删除成功")
  else:
      print(f"删除失败: {result.get('msg')}")
  ```
</CodeGroup>

**请求参数：**

* `workspace_id` (必填): 工作空间 ID
* `category_id` (必填): 文件类别 ID
* `field_ids` (必填): 要删除的字段 ID 数组
* `table_id` (选填): 表格 ID。不传：删除普通字段；传入表格ID：删除表格字段

<Warning>
  删除字段后无法恢复，请谨慎操作。
</Warning>

## 字段配置说明

### 字段类型

* **普通字段**：存储在 `result.fields` 中的键值对字段
* **表格字段**：存储在 `result.tables[].fields` 中的表格列字段

### 字段属性

* **name**: 字段名称，必填
* **description**: 字段描述，选填
* **prompt**: 语义抽取提示词，用于指导 AI 进行字段抽取
* **use\_prompt**: 是否使用语义提示词
* **alias**: 字段别名数组，用于字段识别
* **identity**: 导出字段名，用于结果导出时的字段标识
* **multi\_value**: 是否多值抽取，支持一个字段抽取多个值
* **duplicate\_value\_distinct**: 重复值去重，仅当 multi\_value 为 true 时有效
* **transform\_settings**: 转换配置，支持日期时间、枚举、正则等转换

### 转换配置示例

```json theme={null}
{
  "transform_settings": {
    "type": "datetime",
    "datetime_settings": {
      "format": "yyyy-MM-dd HH:mm:ss"
    },
    "mismatch_action": {
      "mode": "warning",
      "default_value": ""
    }
  }
}
```

## 下一步

* 学习[表格管理](./tables_management) - 管理文件类别下的表格
* 学习[样本管理](./samples_management) - 管理文件类别的样本文件
* 返回[文件类别快速启动](./quickstart) - 查看文件类别基础操作