Skip to content

获取授予名单列表 ​

通过该接口可以获取特定勋章下的授予名单列表,授予名单的排列顺序按照创建时间倒序排列。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/admin/v1/badges/:badge_id/grants
HTTP MethodGET
接口频率限制100 次/分钟
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用admin:badge.grant 查看、创建、编辑、删除勋章授予名单
字段权限要求> Tip: 该接口返回体中存在下列敏感字段,仅当开启对应的权限后才会返回;如果无需获取这些字段,则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

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

路径参数 ​

名称类型描述
badge_idstring企业勋章的唯一ID
示例值:"m_DjMzaK"
数据校验规则:
- 长度范围:1 ~ 64 字符

查询参数 ​

名称类型必填描述
page_sizeint是分页大小
示例值:10
默认值:10
数据校验规则:
- 取值范围:1 ~ 50
page_tokenstring否分页标记,第一次请求不填,表示从头开始遍历;分页查询结果还有更多项时会同时返回新的 page_token,下次遍历可采用该 page_token 获取查询结果
示例值:"om5fn1"
数据校验规则:
- 长度范围:1 ~ 64 字符
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
department_id_typestring否此次调用中使用的部门ID的类型。
示例值:"open_department_id"
可选值有:
- department_id: 以自定义department_id来标识部门 - open_department_id: 以open_department_id来标识部门
默认值:open_department_id
namestring否授予名单名称,精确匹配。
示例值:"激励勋章的授予名单"
数据校验规则:
- 最小长度:1 字符

响应 ​

响应体 ​

名称类型描述
codeint错误码,非 0 表示失败
msgstring错误描述
data\--
  └ grantsgrant\[\]授予名单列表
    └ idstring租户内授予名单的唯一标识,该值由系统随机生成。
    └ badge_idstring企业勋章的唯一ID
    └ namestring勋章下唯一的授予事项,最多100个字符。
    └ grant_typeint授予名单类型
可选值有:
- 0: 手动选择有效期 - 1: 匹配系统入职时间
    └ time_zonestring授予名单的生效时间对应的时区,用于检查RuleDetail的时间戳的取值是否规范,取值范围为TZ database name
    └ rule_detailrule_detail规则详情
      └ effective_timestring开始生效的时间戳。1.手动设置有效期类型勋章,配置有效期限需要配置该字段;2.时间戳必须是所在时区当天的零点时间戳,如时区为Asia/Shanghai时区时的1649606400
      └ expiration_timestring结束生效的时间戳。1.手动设置有效期类型勋章,配置有效期限需要配置该字段;2.最大值:不得超过effective_time+100 年;3.非永久有效:时间戳必须是所在时区当天的23:59:59时间戳,如时区为Asia/Shanghai时区时的1649692799;4.永久有效:传值为0即可
      └ anniversaryint入职周年日。根据入职时间发放类型勋章,需要配置该字段。
      └ effective_periodint有效期限。根据入职时间发放类型勋章,需要配置该字段。
可选值有:
- 1: 有效期为一年 - 2: 永久有效
    └ is_grant_allboolean是否授予给全员。1.为false时,需要关联1~500个用户群体。2.为true时,不可关联用户、用户组、部门。
    └ user_idsstring\[\]授予的用户ID列表,授予名单列表接口返回结果中不返回该字段,只在详情接口返回
    └ department_idsstring\[\]授予的部门ID列表,授予名单列表接口返回结果中不返回该字段,只在详情接口返回
    └ group_idsstring\[\]授予的用户组ID列表,授予名单列表接口返回结果中不返回该字段,只在详情接口返回
  └ page_tokenstring分页标记,当 has_more 为 true 时,会同时返回新的 page_token,否则不返回 page_token
  └ has_moreboolean是否还有更多项

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "grants": [
            {
                "id": "g_49Z7CQ",
                "badge_id": "m_qTR2HM",
                "name": "激励勋章的授予名单",
                "grant_type": 0,
                "time_zone": "Asia/Shanghai",
                "rule_detail": {
                    "effective_time": "1649606400",
                    "expiration_time": "1649692799",
                    "anniversary": 1,
                    "effective_period": 1
                },
                "is_grant_all": false,
                "user_ids": [
                    "u273y71"
                ],
                "department_ids": [
                    "h121921"
                ],
                "group_ids": [
                    "g122817"
                ]
            }
        ],
        "page_token": "om5fn1",
        "has_more": false
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
5001051000unknown server error服务内部错误,请稍后重试
4001051001request contain invalid param请求中包含非法参数
4031051002request to exceed authority请求发生越权
4001051113cannot find this badge未找到该勋章的信息
4031051003the tenant's current payment plan does not support the use of this function该租户当前套餐不能使用勋章功能点

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