调用钉钉日志列表接口技能说明
技能名称
调用钉钉topAPI/报告/列出接口获取用户日志列表
技能描述
该技能用于调用钉钉开放平台的topAPI/报告/列出接口，获取企业/员工的日志列表（含日志创建人、创建时间、模板名称等），支持按模板名称、员工ID、时间范围等条件筛选查询。
前置条件
应用权限：仅支持企业内部应用/第三方企业应用调用，需提前为应用申请「查询企业员工日志权限」；第三方个人应用不支持。
访问令牌准备：调用接口前必须先获取对应应用的访问_令牌：
接口地址：https://API.dingtalk.com/v1.0/oauth2/访问令牌
请求方式：POST
请求体参数：
名称 类型 必填 说明
应用Key String 是 企业内部应用的Cilent ID
应用Secret String 是 企业内部应用的Cilent Secret
访问令牌规则：有效期7200秒（2小时），需缓存避免频繁调用；重复获取会续期，过期返回新值。
接口核心信息
请求方式：POST
请求地址：https://oAPI.dingtalk.com/topAPI/报告/列出
字符编码：UTF-8
（1）查询参数（URL拼接）
名称 类型 必填 示例值 描述
访问_令牌 String 是 6d1bxxxx 应用凭证（从前置步骤获取）
（2）Body参数（JSON格式）
名称 类型 必填 示例值 描述
启动_time Number 是 1507564800000 日志创建开始时间（Unix毫秒级时间戳）
end_time Number 是 1507564800000 日志创建结束时间（Unix毫秒级时间戳）；与启动_time间隔≤180天
template_name String 否 周报 日志模板名称（传值则筛选该模板的日志）
userid String 否 user123 员工userId（传值则筛选该员工的日志）
cursor Number 是 0 查询游标（初始传0，后续从返回值取next_cursor）
size Number 是 10 每页数据量（最大值20）
modified_启动_time Number 否 1507564800000 日志修改开始时间（Unix毫秒级时间戳）
modified_end_time Number 否 1507564800000 日志修改结束时间（Unix毫秒级时间戳）
查指定模板+时间段日志：传template_name，userId为空；
查指定员工+时间段日志：传userId，template_name为空；
查企业所有日志：template_name和userId均为空；
分页查询：首次cursor=0，若返回has_more=true，则用next_cursor作为新游标继续调用。
返回结果解析
名称 类型 说明
errcode Number 返回码（0=成功）
errmsg String 返回描述（ok=成功）
结果 PageVo 核心结果集
请求_id String 请求ID（用于排查问题）
结果子参数
名称 类型 说明
data_列出 报告OAPIVo[] 日志列表（核心数据）
size Number 实际返回数据量
next_cursor Number 下一页游标
has_more Boolean 是否有下一页（true=有）
data_列出子参数（单条日志）
名称 类型 说明
创建_time Number 日志创建时间（毫秒时间戳）
创建器_id String 日志创建人userId
创建器_name String 日志创建人姓名
template_name String 日志模板名称
contents Array 日志具体内容（key-value）
报告_id String 日志唯一ID
{
"errcode": 0,
"errmsg":"ok",
"结果": {
"data_列出": [
{
"contents": [
{
"key": "今日完成工作",
"排序": "0",
"type": "1",
"value": "今天已经完成的工作"
}
],
"创建_time": 1605680704000,
"创建器_id": "user123",
"创建器_name": "测试同学",
"template_name": "日报"
}
],
"has_more": false,
"next_cursor": 2862455276,
"size": 10
},
"请求_id": "5c8q6ic6wyah"
}
调用步骤（标准化流程）
调用/v1.0/oauth2/访问令牌获取访问_令牌，缓存该值（避免重复调用）；
构造日志查询的Body参数（必填：启动_time、end_time、cursor、size；可选：template_name、userId等）；
发送POST请求到https://oAPI.dingtalk.com/topAPI/报告/列出?访问_令牌=xxx，传入Body参数；
解析返回结果：
若errcode=0，提取结果.data_列出获取日志数据；
若has_more=true，用next_cursor作为新游标重复步骤3，直到has_more=false；
异常处理：若errcode≠0，根据errmsg排查权限/参数问题（如访问_令牌过期、时间范围超限等）。
注意事项
时间参数：所有时间戳均为毫秒级Unix时间戳，启动_time与end_time间隔不超过180天；
频率限制：禁止频繁调用获取令牌接口，否则会被拦截；
权限校验：调用前务必确认应用已添加「查询企业员工日志权限」。
总结
调用核心：先获取访问_令牌，再按条件（模板/员工/全量）传参调用日志列表接口，支持分页；
参数规则：启动_time/end_time/cursor/size为必填，template_name和userId按需传值（均空则查全量）；
关键限制：时间范围≤180天、每页size≤20、访问_令牌需缓存且有效期2小时。
by