如何通过 OpenAPI 维护自定义字段

如何获取自定义字段的元数据？

1.调用方式

Step 1: 传入employment和person调用「获取自定义字段列表」接口，获取自定义对象的的 API name

• 自定义对象：当用户在「人员档案配置」页面添加自定义分组时，默认会创建一个与分组同名的自定义对象；人员档案工作信息下创建的自定义分组对应对象为employment；个人信息、履历信息及资料附件下创建的自定义分组对应对象为person

Step 2: 根据对象的 object_api_name 调用「获取自定义字段列表」接口，获取字段的 API name

常见系统对象：

对象名称	object_api_name
个人信息	person
证件	national_id
地址	address
银行账户	bank_account
紧急联系人	emergency_contact
家庭成员	dependent
公民身份信息	citizenship_status
教育经历	education
工作经历	work_experience
资料附件	personal_profile
个人附加信息	person_info_chn
工作信息	employment
任职记录	job_data
离职信息	offboarding_info
试用期信息	probation_management
部门	department

Step 3: 根据 object_api_name, custom_api_name 调用「获取字段详情」接口，获得字段详情

2.示例

场景：「个人信息」对象下创建了一个自定义分组「个人证书」，需要查询「个人证书」下「职业证书等级」字段的枚举值有哪些。

怎么维护自定义字段的数据？

1. 自定义字段的数据

飞书人事对外提供的很多 OpenAPI 都支持写入自定义字段的数据，以创建个人信息为例：

• 设置请求体 custom_fields，以 custom_api_name、value 的结构写入具体数据

• 传参示例：

• 写入一个字段编码为 custom_field_1__c 的自定义字段的值
• 注意不同的接口参数名称可能不同，如 custom_api_name、field_name 等

{
	"custom_fields": [
		{
			"custom_api_name": "custom_field_1__c",
			"value": "\"这是一段单行文本\""
		}
	]
}

不同字段类型的数据传输格式

字段值是 JSON 转义后的字符串，根据元数据定义不同，字段格式不同，参考如下：

类型	Type 值	传入 Value 格式	说明
文本	1	单语单行："field__c": ""这是一段单行文本"" 单语多行："field__c": ""这是多行文本第一行\n这是多行文本第二行"" 多语单行："field__c": "{\"en-US\":\"这是英文\",\"zh-CN\":\"这是中文\"}" 多语多行："field__c": "{\"en-US\":\"这是英文第一行\\n这是英文第二行\",\"zh-CN\":\"这是中文第一行\\n这是中文第二行\"}"	文本属性（是否多语、是否多行等）可通过获取字段详情接口获得
是否	2	"field__c": "\"true\""
数字	3	"field__c": "\"2334.00\""
选项	4	单选："field__c": ""enum_api_name"" 多选："field__c": "["enum_api_name_1","enum_api_name_2"]"	传入选项的 API name，可通过获取字段详情接口获得
查找	5	人员（单选）："field__c": ""7050076802819163661"" 人员（多选）："field__c": "["6976524804564321805","6976446378482484773"]" 自定义分组："field__c": "[{\"wk_id\":\"7251542212374136358\",\"field_api_name_1\":\"文本1\",\"field_api_name_2\":\"enum_api_name_1\",\"field_api_name_3\":\"文本2\"}]"	人员（单选）和人员（多选）组件传入雇佣 ID，且只能用 people_corehr_id 类型的 user_id_type 自定义分组中的数据要更新时，需要输入 wk_id，可通过查询接口获得，不传 wk_id 认为是新增
自动编码	6	"field__c": "\"ABC123456XYZ\""	只能查询，不可修改
日期时间	7	日期："field__c": ""2023-01-24"" 日期时间："field__c": ""2024-01-23 05:06:07""
附件	8	附件单选："field__c": [{"field_name": "field_api_name","value": "\"[{\\\"file_id\\\":\\\"64489fc45cc11e4688d3daf1_d80d327756bd4140ad292fc94d9e9e0f\\\"}]""}] 附件多选："field__c": [{"field_name": "field_api_name","value": "\"[{\\\"file_id\\\":\\\"64489fc716ba39874c68c077_6fc1ba59668a4fae8a7f045816a18ecc\\\"},{\\\"file_id\\\":\\\"63eb3433fb14e3de87ac7f78_8f74c25f2e85401fbea1d787feea041b\\\"}]\""}]
图片	9	-	只能查询，不可修改
计算字段	10	-	只能查询，不可修改
反向查找	11	-	只能查询，不可修改

2. 自定义分组的数据

目前飞书人事仅支持在「人员档案配置」功能下创建自定义分组，因此仅人员相关的 OpenAPI（如：创建个人信息、更新个人信息等）支持更新自定义分组的数据。以更新个人信息为例：

• 传参示例：

  • 更新 2 条「个人证书」数据，第一条是更新数据；第二条是新建一条数据
  • 自定义分组「个人证书」对应的 object_api_name 为 custom_obj_6__c
  • 自定义分组内包含的 2 个自定义字段「职业证书名称」、「职业证书类型」，对应的 custom_api_name 分别为 custom_field_1__c、custom_field_2__c

{
	"custom_fields": [
		{
			"field_name": "custom_obj_6__c",
			"value": "[{\"custom_field_1__c\":\"证书名称一\",\"custom_field_2__c\":\"enum_api_name_1\",\"wk_id\":\"6863326262618752111\"},{\"custom_field_1__c\":\"证书名称二\",\"custom_field_2__c\":\"enum_api_name_2\"}]"
		}
	]
}

• 实现效果：

更新前	更新后
一条证书数据：1. 职业证书名称：证书名称一、职业证书等级：中级证书	两条证书数据：1. 职业证书名称：证书名称一、职业证书等级：高级证书；2.职业证书名称：证书名称二、职业证书等级：中级证书