飞书开放平台 Server API 文档

主题

创建自定义字段 ​

创建一个自定义字段，并将其加入一个资源上（目前资源只支持清单）。创建自定义字段必须提供字段名称，类型和相应类型的设置。

目前任务自定义字段支持数字(number)，成员(member)，日期(datetime)，单选(single_select),多选(multi_select), 文本(text)几种类型。分别使用"number_setting", "member_setting", "datetime_setting", "single_select_setting", "multi_select_setting","text_setting"来设置。

例如创建一个数字类型的自定义字段，并添加到guid为"ec5ed63d-a4a9-44de-a935-7ba243471c0a"的清单，可以这样发请求。

POST /task/v2/custom_fields
{
    "name": "价格",
    "type": "number",
    "resource_type": "tasklist",
    "resource_id": "ec5ed63d-a4a9-44de-a935-7ba243471c0a",
    "number_setting": {
         "format": "cny",
         "decimal_count": 2,
         "separator": "thousand"
    }
}

表示创建一个叫做“价格”的自定义字段，保留两位小数。在界面上显示时采用人民币的格式，并显示千分位分割符。

类似的，创建一个单选字段，可以这样调用接口：

POST /task/v2/custom_fields
{
  "name": "优先级",
  "type": "single_select",
  "resource_type": "tasklist",
  "resource_id":  "ec5ed63d-a4a9-44de-a935-7ba243471c0a",
  "single_select_setting": {
    "options": [
       {
          "name": "高",
          "color_index": 1
       },
       {
          "name": "中",
          "color_index": 11
       },
       {
          "name": "低",
          "color_index": 16
       }
   ]
  }
}

表示创建一个叫“优先级”的单选，包含“高”，“中”，“低”三个选项，每个选项设置一个颜色值。

Tip: 在一个资源上创建自定义字段需要该资源的可编辑权限。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/task/v2/custom_fields
HTTP MethodPOST
接口频率限制100 次/分钟
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用task:custom_field:write 查看、创建、更新自定义字段
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
resource_typestring是自定义字段要归属的资源类型，支持"tasklist"
示例值："tasklist"
默认值：tasklist
resource_idstring是自定义字段要归属的资源ID，当resource_type为"tasklist"时必须填写清单的GUID。
示例值："ec5ed63d-a4a9-44de-a935-7ba243471c0a"
数据校验规则：
- 最大长度：100 字符
namestring是字段名称，最大50个字符。
示例值："优先级"
typestring是自定义字段类型。
示例值："number"
可选值有：
- number: 数字 - datetime: 日期 - member: 成员 - single_select: 单选 - multi_select: 多选 - text: 文本
number_settingnumber_setting否数字类型的字段设置
  └ formatstring否数字类型的自定义字段的值在App展示的格式。
注意本设置仅影响App中的数字类型字段的字段值的显示格式，并不会影响openapi中输入/输出的字段值的格式。
示例值："normal"
可选值有：
- normal: 常规数字 - percentage: 百分比格式 - cny: 人民币格式 - usd: 美元格式 - custom: 自定义符号
默认值：normal
  └ custom_symbolstring否当format设为"custom"时，设置具体的自定义符号。
注意本设置仅影响App中的数字类型字段的字段值的显示格式，并不会影响openapi输入/输出的字段值的格式。
示例值："自定义符号"
  └ custom_symbol_positionstring否当format设为"custom"时，自定义符号相对于数字的显示位置。
注意本设置仅影响App中的数字类型字段的字段值的显示格式，并不会影响openapi输入/输出的字段值的格式。
示例值："left"
可选值有：
- left: 自定义符号显示在数字左边 - right: 自定义符号显示在数字右边
默认值：right
  └ separatorstring否数字类型自定义字段整数部分的分隔符样式。
注意本设置仅影响App中的数字类型字段的字段值的显示格式，并不会影响openapi输入/输出的字段值的格式。
示例值："thousand"
可选值有：
- none: 无分隔符 - thousand: 千分位分隔符
默认值：none
  └ decimal_countint否数字类型自定义字段的值保留的小数位数。多余的位数将被四舍五入。
默认为0。
示例值：2
默认值：0
数据校验规则：
- 取值范围：0 ～ 6
member_settingmember_setting否人员类型的字段设置
  └ multiboolean否是否支持多选。
默认为false。
示例值：true
默认值：false
datetime_settingdatetime_setting否时间日期类型的字段设置
  └ formatstring否日期时间格式，支持
- yyyy-mm-dd: 以短横分隔的年月日，例如2023-08-24 - yyyy/mm/dd: 以斜杠分隔的年月日，例如2023/08/04 - mm/dd/yyyy: 以斜杠分隔的月日年，例如08/24/2023 - dd/mm/yyyy: 以斜杠分隔的日月年，例如24/08/2023
默认为"yyyy-mm-dd"。
注意本设置仅影响App中的时间日期类型字段的字段值的显示格式，并不会影响openapi输入/输出的字段值的格式。
示例值："yyyy/mm/dd"
single_select_settingselect_setting否单选设置
  └ optionsoption\[\]否单选选项
数据校验规则：
- 长度范围：0 ～ 100
    └ namestring是选项名称，不能为空，最大50个字符
示例值："高优"
    └ color_indexint否选项的颜色索引值，取值0～54。如不填写会自动从未使用的颜色索引值中随机选一个。
示例值：1
数据校验规则：
- 取值范围：0 ～ 54
    └ is_hiddenboolean否选项是否隐藏。隐藏后的选项在界面不可见，也不可以再通过openapi将字段值设为该选项。
示例值：false
multi_select_settingselect_setting否多选设置
  └ optionsoption\[\]否多选选项
数据校验规则：
- 长度范围：0 ～ 100
    └ namestring是选项名称，不能为空，最大50个字符。
示例值："高优"
    └ color_indexint否选项的颜色索引值，可以是0～54中的一个数字。如果不填写则会随机选一个。
示例值：1
数据校验规则：
- 取值范围：0 ～ 54
    └ is_hiddenboolean否选项是否隐藏。隐藏后的选项在App界面不可见，也不可以通过oapi将字段值设为该选项。
示例值：false
text_settingtext_setting否文本类型设置（目前文本类型没有可设置项）

请求体示例 ​

json
{
    "resource_type": "tasklist",
    "resource_id": "ec5ed63d-a4a9-44de-a935-7ba243471c0a",
    "name": "优先级",
    "type": "number",
    "number_setting": {
        "format": "normal",
        "custom_symbol": "自定义符号",
        "custom_symbol_position": "left",
        "separator": "thousand",
        "decimal_count": 2
    },
    "member_setting": {
        "multi": true
    },
    "datetime_setting": {
        "format": "yyyy/mm/dd"
    },
    "single_select_setting": {
        "options": [
            {
                "name": "高优",
                "color_index": 1,
                "is_hidden": false
            }
        ]
    },
    "multi_select_setting": {
        "options": [
            {
                "name": "高优",
                "color_index": 1,
                "is_hidden": false
            }
        ]
    },
    "text_setting": {}
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ custom_fieldcustom_field创建的自定义字段
    └ guidstring自定义字段的GUID
    └ namestring自定义字段名称
    └ typestring自定义字段类型
    └ number_settingnumber_setting数字类型的字段设置
      └ formatstring数字展示的格式
可选值有：
- normal: 常规数字 - percentage: 百分比格式 - cny: 人民币格式 - usd: 美元格式 - custom: 自定义符号
      └ custom_symbolstring自定义符号。只有format设为custom时才会生效。
      └ custom_symbol_positionstring自定义符号的位置。默认为right。
可选值有：
- left: 自定义符号放在数字左边 - right: 自定义符号放在数字右边
      └ separatorstring分隔符样式
可选值有：
- none: 无分隔符 - thousand: 千分位分隔符
      └ decimal_countint保留小数位数。输入的数字值的小数位数如果比该设置多，多余的位数将被四舍五入后舍弃。如果format为"percentage"，表示变为百分数之后的小数位数。
    └ member_settingmember_setting人员类型的字段设置
      └ multiboolean是否支持多选
    └ datetime_settingdatetime_setting时间日期类型的字段设置
      └ formatstring日期显示格式
    └ single_select_settingselect_setting单选类型的字段设置
      └ optionsoption\[\]选项
        └ guidstring选项的GUID
        └ namestring选项名称，不能为空，最大50个字符
        └ color_indexint选项的颜色索引值，取值0～54。如不填写会自动从未使用的颜色索引值中随机选一个。
        └ is_hiddenboolean选项是否隐藏。隐藏后的选项在界面不可见，也不可以再通过openapi将字段值设为该选项。
    └ multi_select_settingselect_setting多选类型的字段设置
      └ optionsoption\[\]选项
        └ guidstring选项的GUID
        └ namestring选项名称，不能为空，最大50个字符。
        └ color_indexint选项的颜色索引值。
        └ is_hiddenboolean选项是否隐藏。隐藏后的选项在界面不可见，也不可以再通过openapi将字段值设为该选项。
    └ creatormember创建人
      └ idstring表示member的id
      └ typestring成员的类型
      └ rolestring成员角色
    └ created_atstring自定义字段创建的时间戳(ms)
    └ updated_atstring自定义字段的更新时间戳(ms)
    └ text_settingtext_setting文本类型设置（目前文本类型没有可设置项）

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "custom_field": {
            "guid": "34d4b29f-3d58-4bc5-b752-6be80fb687c8",
            "name": "优先级",
            "type": "number",
            "number_setting": {
                "format": "normal",
                "custom_symbol": "自定义符号",
                "custom_symbol_position": "left",
                "separator": "thousand",
                "decimal_count": 2
            },
            "member_setting": {
                "multi": true
            },
            "datetime_setting": {
                "format": "yyyy/mm/dd"
            },
            "single_select_setting": {
                "options": [
                    {
                        "guid": "4216f79b-3fda-4dc6-a0c4-a16022e47152",
                        "name": "高优",
                        "color_index": 1,
                        "is_hidden": false
                    }
                ]
            },
            "multi_select_setting": {
                "options": [
                    {
                        "guid": "4216f79b-3fda-4dc6-a0c4-a16022e47152",
                        "name": "高优",
                        "color_index": 1,
                        "is_hidden": false
                    }
                ]
            },
            "creator": {
                "id": "ou_2cefb2f014f8d0c6c2d2eb7bafb0e54f",
                "type": "user",
                "role": "creator"
            },
            "created_at": "1688196600000",
            "updated_at": "1688196600000",
            "text_setting": {}
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001470400参数错误，比如设置了自定义字段类型为"number", 却没有提供"number_setting"。错误原因见返回的msg提示的信息。
4031470403缺少在指定资源中创建自定义字段的权限检查调用身份是否有对应资源的有编辑权限。
4041470404要创建自定义字段的资源不存在或已删除。确认要创建自定义字段的字段是否还存在。
5001470500服务器错误。尝试重试调用。如持续失败，请联系支持人员进行反馈。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有