获取周期列表

批量获取周期的基本信息，如周期的名称、类型等信息。支持根据时间段、周期年份、周期类型等过滤条件进行筛选。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/performance/v1/semesters
HTTP Method	GET
接口频率限制	10 次/分钟
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	performance:performance 管理绩效数据 performance:performance:readonly 查看绩效数据 performance:semester:read 查看周期数据
字段权限要求	> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头

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

查询参数

名称	类型	必填	描述
start_time	string	否	周期开始时间最小值，毫秒时间戳，小于该时间开始的周期会被过滤掉 示例值：1630425599999
end_time	string	否	周期结束时间最大值，毫秒时间戳，大于该时间结束的周期会被过滤掉 示例值：1640425000000
year	int	否	周期年份，填写时按照周期年份筛选 示例值：2024 数据校验规则： - 取值范围：0 ～ 9999
type_group	string	否	周期类型分组，填写时按照周期类型分组 示例值：Annual 可选值有： - Annual: 年 - Semi-annual: 半年 - Quarter: 季度 - Bimonth: 双月 - Month: 月 - Non-standard: 非标准周期
type	string	否	周期类型，填写时按照周期类型筛选 示例值：April 可选值有： - Annual: 全年 - H1: 上半年 - H2: 下半年 - Q1: 第一季度 - Q2: 第二季度 - Q3: 第三季度 - Q4: 第四季度 - January-February: 1-2 双月 - March-April: 3-4 双月 - May-June: 5-6 双月 - July-August: 7-8 双月 - September-October: 9-10 双月 - November-December: 11-12 双月 - January: 1月份 - February: 2月份 - March: 3月份 - April: 4月份 - May: 5月份 - June: 6月份 - July: 7月份 - August: 8月份 - September: 9月份 - October: 10月份 - November: 11月份 - December: 12月份 - Custom: 自定义
user_id_type	string	否	用户 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

注：参数之间是「与」关系，都不传时返回所有周期。

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ items	semester\[\]	周期列表
└ id	string	周期 ID
└ year	int	周期年份
└ type_group	string	周期类型分组
└ type	string	周期类型
└ name	i18n	周期名称
└ zh-CN	string	周期中文名称
└ en-US	string	周期英文名称
└ progress	string	周期状态 可选值有： - initiating: 初始化 - enabled: 已启动
└ start_time	string	周期开始时间，毫秒时间戳
└ end_time	string	周期结束时间，毫秒时间戳
└ create_time	string	周期创建时间，毫秒时间戳
└ modify_time	string	周期更新时间，毫秒时间戳
└ create_user_id	string	周期创建人 ID，与入参 user_id_type 类型一致
└ modify_user_id	string	周期更新人 ID，与入参 user_id_type 类型一致

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "id": "6992035450862224940",
                "year": 2024,
                "type_group": "Quarter",
                "type": "Q1",
                "name": {
                    "zh-CN": "2024 全年绩效周期",
                    "en-US": "2024 full year semester"
                },
                "progress": "enabled",
                "start_time": "1625068800000",
                "end_time": "1640966399999",
                "create_time": "1625068800000",
                "modify_time": "1625068800000",
                "create_user_id": "ou_ce613028fe74745421f5dc320bb9c709",
                "modify_user_id": "ou_ce613028fe74745421f5dc320bb9c709"
            }
        ]
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	1580901	tenant no licnese	租户无绩效席位，请联系租户管理员开通绩效席位

更多错误码信息，参见通用错误码。