调用钉钉日志列表接口技能说明\r

技能名称\r

调用钉钉topapi/report/list接口获取用户日志列表\r \r

技能描述\r

该技能用于调用钉钉开放平台的topapi/report/list接口，获取企业/员工的日志列表（含日志创建人、创建时间、模板名称等），支持按模板名称、员工ID、时间范围等条件筛选查询。\r \r

前置条件\r

1. 应用权限：仅支持企业内部应用/第三方企业应用调用，需提前为应用申请「查询企业员工日志权限」；第三方个人应用不支持。\r
2. AccessToken准备：调用接口前必须先获取对应应用的access_token：\r
   • 接口地址：https://api.dingtalk.com/v1.0/oauth2/accessToken\r
   • 请求方式：POST\r
   • 请求体参数：\r | 名称 | 类型 | 必填 | 说明 |\r |-----------|--------|------|--------------------------|\r | appKey | String | 是 | 企业内部应用的Cilent ID |\r | appSecret | String | 是 | 企业内部应用的Cilent Secret |\r
   • AccessToken规则：有效期7200秒（2小时），需缓存避免频繁调用；重复获取会续期，过期返回新值。\r \r

接口核心信息\r

1. 基础调用信息\r

• 请求方式：POST\r
• 请求地址：https://oapi.dingtalk.com/topapi/report/list\r
• 字符编码：UTF-8\r \r

2. 请求参数\r

（1）Query参数（URL拼接）\r

| 名称 | 类型 | 必填 | 示例值 | 描述 |\r |--------------|--------|------|------------|---------------------------------------|\r | access_token | String | 是 | 6d1bxxxx | 应用凭证（从前置步骤获取）|\r \r

（2）Body参数（JSON格式）\r

| 名称 | 类型 | 必填 | 示例值 | 描述 |\r |---------------------|--------|------|-----------------|----------------------------------------------------------------------|\r | start_time | Number | 是 | 1507564800000 | 日志创建开始时间（Unix毫秒级时间戳）|\r | end_time | Number | 是 | 1507564800000 | 日志创建结束时间（Unix毫秒级时间戳）；与start_time间隔≤180天 |\r | template_name | String | 否 | 周报 | 日志模板名称（传值则筛选该模板的日志）|\r | userid | String | 否 | user123 | 员工userId（传值则筛选该员工的日志）|\r | cursor | Number | 是 | 0 | 查询游标（初始传0，后续从返回值取next_cursor）|\r | size | Number | 是 | 10 | 每页数据量（最大值20）|\r | modified_start_time | Number | 否 | 1507564800000 | 日志修改开始时间（Unix毫秒级时间戳）|\r | modified_end_time | Number | 否 | 1507564800000 | 日志修改结束时间（Unix毫秒级时间戳）|\r \r

3. 参数传递规则（核心）\r

• 查指定模板+时间段日志：传template_name，userId为空；\r
• 查指定员工+时间段日志：传userId，template_name为空；\r
• 查企业所有日志：template_name和userId均为空；\r
• 分页查询：首次cursor=0，若返回has_more=true，则用next_cursor作为新游标继续调用。\r \r

返回结果解析\r

1. 返回参数结构\r

| 名称 | 类型 | 说明 |\r |-----------|-----------|--------------------------|\r | errcode | Number | 返回码（0=成功）|\r | errmsg | String | 返回描述（ok=成功）|\r | result | PageVo | 核心结果集 |\r | request_id| String | 请求ID（用于排查问题）|\r \r

result子参数\r

| 名称 | 类型 | 说明 |\r |-------------|----------------|--------------------------|\r | data_list | ReportOapiVo[] | 日志列表（核心数据）|\r | size | Number | 实际返回数据量 |\r | next_cursor | Number | 下一页游标 |\r | has_more | Boolean | 是否有下一页（true=有）|\r \r

data_list子参数（单条日志）\r

| 名称 | 类型 | 说明 |\r |---------------|--------|--------------------------|\r | create_time | Number | 日志创建时间（毫秒时间戳） |\r | creator_id | String | 日志创建人userId |\r | creator_name | String | 日志创建人姓名 |\r | template_name | String | 日志模板名称 |\r | contents | Array | 日志具体内容（key-value） |\r | report_id | String | 日志唯一ID |\r \r

2. 返回示例\r

{\r
    "errcode": 0,\r
    "errmsg":"ok",\r
    "result": {\r
        "data_list": [\r
            {\r
                "contents": [\r
                    {\r
                        "key": "今日完成工作",\r
                        "sort": "0",\r
                        "type": "1",\r
                        "value": "今天已经完成的工作"\r
                    }\r
                ],\r
                "create_time": 1605680704000,\r
                "creator_id": "user123",\r
                "creator_name": "测试同学",\r
                "template_name": "日报"\r
            }\r
        ],\r
        "has_more": false,\r
        "next_cursor": 2862455276,\r
        "size": 10\r
    },\r
    "request_id": "5c8q6ic6wyah"\r
}\r
```\r
\r
## 调用步骤（标准化流程）\r
1. 调用`/v1.0/oauth2/accessToken`获取access_token，缓存该值（避免重复调用）；\r
2. 构造日志查询的Body参数（必填：start_time、end_time、cursor、size；可选：template_name、userId等）；\r
3. 发送POST请求到`https://oapi.dingtalk.com/topapi/report/list?access_token=xxx`，传入Body参数；\r
4. 解析返回结果：\r
   - 若`errcode=0`，提取`result.data_list`获取日志数据；\r
   - 若`has_more=true`，用`next_cursor`作为新游标重复步骤3，直到`has_more=false`；\r
5. 异常处理：若`errcode≠0`，根据`errmsg`排查权限/参数问题（如access_token过期、时间范围超限等）。\r
\r
## 注意事项\r
1. 时间参数：所有时间戳均为**毫秒级Unix时间戳**，start_time与end_time间隔不超过180天；\r
2. 频率限制：禁止频繁调用gettoken接口，否则会被拦截；\r
3. 权限校验：调用前务必确认应用已添加「查询企业员工日志权限」。\r
\r
### 总结\r
1. 调用核心：先获取access_token，再按条件（模板/员工/全量）传参调用日志列表接口，支持分页；\r
2. 参数规则：start_time/end_time/cursor/size为必填，template_name和userId按需传值（均空则查全量）；\r
3. 关键限制：时间范围≤180天、每页size≤20、access_token需缓存且有效期2小时。