获取字段详情

获取「飞书人事」对象下某字段的详细信息，支持系统预置字段和自定义字段。可通过该接口获取某个选项字段包含的选项列表，某个自定义分组中包含的字段列表等。使用方式可参考「如何通过 OpenAPI 维护自定义字段」

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/corehr/v1/custom_fields/get_by_param
HTTP Method	GET
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	corehr:common_data.meta_data:read 获取元数据信息 corehr:corehr:readonly 获取核心人事信息 corehr:corehr 更新核心人事信息

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 值格式："Bearer access_token" 示例值："Bearer t-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

查询参数

名称	类型	必填	描述
object_api_name	string	是	所属对象 API name，可从获取飞书人事对象列表接口列举所有对象及其 API name 示例值：offboarding_info
custom_api_name	string	是	字段 API name，可通过获取自定义字段列表接口中返回的 custom_api_name 字段获取 示例值：custom_field_33__c

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ data	custom_field	字段详情
└ custom_api_name	string	字段 API name，即字段的唯一标识
└ name	name	字段名称
└ zh_cn	string	中文
└ en_us	string	英文
└ description	name	描述
└ zh_cn	string	中文
└ en_us	string	英文
└ is_open	boolean	是否启用
└ is_required	boolean	是否必填
└ is_unique	boolean	是否唯一
└ object_api_name	string	所属对象 apiname
└ type	int	字段类型 可选值有： - 1：文本 Text，“文本”和“超链接”属于该类型 - 2：布尔 Boolean - 3：数字 Number - 4：枚举 Enum，“单选”和“单选”属于该类型 - 5：查找 Lookup，“人员（单选）”、“人员（多选）”及“人员档案管理”页面中用户添加的自定义分组属于该类型 - 6：自动编码 Auto Number - 7：日期时间 Date Time - 8：附件 Attachment，“附件单选”和“附件多选”为该类型 - 9：图片 Image - 10：计算字段 Calculated - 11：反向查找 Back Lookup
└ common_schema_config	common_schema_config	字段类型配置信息，可以用来区分同一字段类型下的不同子类型。当前仅字段类型为「文本」「布尔」「数字」「枚举」「日期时间」「附件」「图片」时返回相应的配置信息，其余类型暂不返回
└ text_field_setting	text_field_setting	文本配置信息
└ is_multilingual	boolean	是否多语言
└ is_multiline	boolean	是否多行
└ max_length	int	最大长度
└ is_url_type	boolean	是否是“超链接”类型
└ number_field_setting	number_field_setting	数字配置信息
└ number_field_type	int	数字类型 可选值有： - 1：Percent 百分比（定点小数） - 2：Integer 整数 - 3：Value 数值（定点小数） - 4：Money 金额（定点小数）
└ decimal_places	int	小数点后的位数
└ round_type	int	四舍五入规则 可选值有： - 0：Round 四舍五入 - 1：Ceil 向上舍入 - 2：Floor 向下舍入
└ decimal_total_places	int	整数+小数的最大总位数
└ enum_field_setting	enum_field_setting	选项配置信息
└ enum_field_option_list	common_schema_option\[\]	选项信息
└ api_name	string	枚举常量集 API name，即一组选项集合的唯一标识。系统预置的枚举常量集可在枚举常量介绍文档中查询到
└ name	name	选项名称
└ zh_cn	string	中文
└ en_us	string	英文
└ description	name	选项描述
└ zh_cn	string	中文
└ en_us	string	英文
└ is_open	boolean	是否启用
└ is_multiple	boolean	是否为多选
└ lookup_field_setting	lookup_field_setting	查找字段配置信息
└ lookup_obj_api_name	string	查找字段所引用对象的 API name。对于“人员（单选）”和“人员（多选）”，其值为 employment。可通过获取自定义字段列表接口传入此参数的值来查询自定义分组中定义的自定义字段
└ is_multiple	boolean	是否为多值。例如“人员（单选）字段”此属性为 false，而“人员（多选）”字段此属性为 true。
└ date_time_field_setting	date_time_field_setting	日期时间配置信息
└ date_time_type	int	时间类型枚举 可选值有： - 1：Date 日期，如 2020-01-01 - 2：Time 时间，如 11:52:00 - 3：DateTime 日期时间，如 2020-01-01 11:52:00 - 4：CusDateTime 时间戳
└ attachment_field_setting	attachment_field_setting	附件配置信息
└ is_multiple	boolean	是否支持多个文件
└ file_type	int	废弃属性，不建议使用，通常为空值
└ image_field_setting	image_field_setting	图片配置信息
└ image_type	int	图片类型枚举 可选值有： - 1：Avatar 头像 - 2：BadgePhoto 工卡照片 - 3：Logo 标志
└ display_style	int	显示样式枚举 可选值有： - 1：SquareImage 方形 - 2：RoundImage 圆形
└ calculated_field_setting	calculated_field_setting	计算字段配置信息
└ type	int	字段类型
└ create_time	string	创建时间，秒级时间戳
└ update_time	string	更新时间，秒级时间戳

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "data": {
            "custom_api_name": "custom_field_33__c",
            "name": {
                "zh_cn": "cn",
                "en_us": "en"
            },
            "description": {
                "zh_cn": "cn",
                "en_us": "en"
            },
            "is_open": true,
            "is_required": true,
            "is_unique": true,
            "object_api_name": "offboarding_info",
            "type": 1,
            "common_schema_config": {
                "text_field_setting": {
                    "is_multilingual": true,
                    "is_multiline": true,
                    "max_length": 1,
                    "is_url_type": true
                },
                "number_field_setting": {
                    "number_field_type": 1,
                    "decimal_places": 1,
                    "round_type": 1,
                    "decimal_total_places": 1
                },
                "enum_field_setting": {
                    "enum_field_option_list": [
                        {
                            "api_name": "custom_enum_option_33",
                            "name": {
                                "zh_cn": "cn",
                                "en_us": "en"
                            },
                            "description": {
                                "zh_cn": "cn",
                                "en_us": "en"
                            },
                            "is_open": true
                        }
                    ],
                    "is_multiple": false
                },
                "lookup_field_setting": {
                    "lookup_obj_api_name": "employment",
                    "is_multiple": false
                },
                "date_time_field_setting": {
                    "date_time_type": 1
                },
                "attachment_field_setting": {
                    "is_multiple": false,
                    "file_type": 1
                },
                "image_field_setting": {
                    "image_type": 1,
                    "display_style": 1
                },
                "calculated_field_setting": {
                    "type": 1
                }
            },
            "create_time": "1625542287",
            "update_time": "1625542639"
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
500	1160005	custom field format error	存在非法的字段脏数据，请联系技术支持处理
400	1160006	required parameter is empty	请检查输入参数，确认必填参数均已正确填写
500	1160997	unknown meta rpc error	服务内部错误，请稍后重试。如有问题请联系技术支持
400	1162010	object does not exist	找不到指定对象，请检查 object_api_name 入参是否正确
400	1162020	field does not exist	找不到指定字段，请检查 custom_api_name 入参是否正确