Dingtalk Log

---
name: dingtalk-log
description: "dingtalk-log"
---

# 调用钉钉日志列表接口技能说明
## 技能名称
调用钉钉topapi/report/list接口获取用户日志列表

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

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

## 接口核心信息
### 1. 基础调用信息
- 请求方式：POST
- 请求地址：`https://oapi.dingtalk.com/topapi/report/list`
- 字符编码：UTF-8

### 2. 请求参数
#### （1）Query参数（URL拼接）
| 名称         | 类型   | 必填 | 示例值     | 描述                                  |
|--------------|--------|------|------------|---------------------------------------|
| access_token | String | 是   | 6d1bxxxx   | 应用凭证（从前置步骤获取）|

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

### 3. 参数传递规则（核心）
- 查指定模板+时间段日志：传`template_name`，`userId`为空；
- 查指定员工+时间段日志：传`userId`，`template_name`为空；
- 查企业所有日志：`template_name`和`userId`均为空；
- 分页查询：首次`cursor=0`，若返回`has_more=true`，则用`next_cursor`作为新游标继续调用。

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

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

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

### 2. 返回示例
```json
{
    "errcode": 0,
    "errmsg":"ok",
    "result": {
        "data_list": [
            {
                "contents": [
                    {
                        "key": "今日完成工作",
                        "sort": "0",
                        "type": "1",
                        "value": "今天已经完成的工作"
                    }
                ],
                "create_time": 1605680704000,
                "creator_id": "user123",
                "creator_name": "测试同学",
                "template_name": "日报"
            }
        ],
        "has_more": false,
        "next_cursor": 2862455276,
        "size": 10
    },
    "request_id": "5c8q6ic6wyah"
}
```

## 调用步骤（标准化流程）
1. 调用`/v1.0/oauth2/accessToken`获取access_token，缓存该值（避免重复调用）；
2. 构造日志查询的Body参数（必填：start_time、end_time、cursor、size；可选：template_name、userId等）；
3. 发送POST请求到`https://oapi.dingtalk.com/topapi/report/list?access_token=xxx`，传入Body参数；
4. 解析返回结果：
   - 若`errcode=0`，提取`result.data_list`获取日志数据；
   - 若`has_more=true`，用`next_cursor`作为新游标重复步骤3，直到`has_more=false`；
5. 异常处理：若`errcode≠0`，根据`errmsg`排查权限/参数问题（如access_token过期、时间范围超限等）。

## 注意事项
1. 时间参数：所有时间戳均为**毫秒级Unix时间戳**，start_time与end_time间隔不超过180天；
2. 频率限制：禁止频繁调用gettoken接口，否则会被拦截；
3. 权限校验：调用前务必确认应用已添加「查询企业员工日志权限」。

### 总结
1. 调用核心：先获取access_token，再按条件（模板/员工/全量）传参调用日志列表接口，支持分页；
2. 参数规则：start_time/end_time/cursor/size为必填，template_name和userId按需传值（均空则查全量）；
3. 关键限制：时间范围≤180天、每页size≤20、access_token需缓存且有效期2小时。