# 获取多部门应用使用概览
查看应用在某一天/某一周/某一个月的使用数据，可以根据部门做多层子部门的筛选
**注意事项**：1. 仅支持企业版/旗舰版租户使用
2. 一般每天早上10点产出前一天的数据
3. 已经支持的指标包括：应用的活跃用户数、累计用户数、新增用户数、访问页面数、打开次数
4. 按照部门查看数据时，可以分别展示当前部门以及其子部门的使用情况
5. 如果查询的部门在查询日期没有使用过应用，只返回指标：应用的活跃用户数指标
6. 数据从飞书4.10版本开始统计，使用飞书版本4.10及以下版本的用户数据不会被统计到
7. 调用频控为100次/分
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/application/v6/applications/:app_id/app_usage/department_overview
HTTP Method | POST
接口频率限制 | [100 次/分钟](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 获取员工使用应用的概览数据(application:application.app_usage_stats.overview:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 路径参数
名称 | 类型 | 描述
---|---|---
app_id | string | 目标应用 ID
**示例值**："cli_9f115af860f7901b"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
department_id_type | string | 否 | 调用中使用的部门ID的类型
**示例值**：open_department_id
**可选值有**：
- department_id：以自定义department_id来标识部门
- open_department_id：以open_department_id来标识部门
**默认值**：`open_department_id`
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
date | string | 是 | 查询日期，格式为yyyy-mm-dd，若cycle_type为1，date可以为任何自然日；若cycle_type为2，则输入的date必须为周一； 若cycle_type为3，则输入的date必须为每月1号
**示例值**："2021-07-08"
cycle_type | int | 是 | 活跃周期的统计类型
**示例值**：1
**可选值有**：
- 1：日活，指自然日，返回当前日期所在日的数据
- 2：周活，指自然周，返回当前日期所在周的数据。若到查询时当周还没结束，则返回周一到当前日期的数值。例如在2021/7/15 查询2021/7/5 这一周的数据，则代表的是2021/7/5 ~ 2021/7/11。但若是在2021/7/8 查询2021/7/5 这一周的数据，则返回的是2021/7/5 ~ 2021/7/7 的数据
- 3：月活，指自然月，返回当前日期所在月的数据。若不满一个月则返回当月1日到截止日期前的数据。例如在2021/8/15 查询 7月的数据，则代表2021/7/1~2021/7/31。 若在2021/8/15 查询8月的数据，则代表2021/8/1~2021/8/14的数据
department_id | string | 否 | 查询的部门id，获取方法可参考[部门ID概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview)
- 若部门id为空，则返回当前租户的使用数据；若填写部门id，则返回当前部门的使用数据（包含子部门的用户） 以及多级子部门的使用数据。
- 若路径参数中department_id_type为空或者为open_department_id，则此处应该填写部门的 open_department_id；若路径参数中department_id_type为department_id，则此处应该填写部门的 department_id。
- 若不填写则返回整个租户的数据
**示例值**："od-4e6ac4d14bcd5071a37a39de902c7141"
recursion | int | 否 | 是否需要查询部门下多层子部门的数据。未设置或为0时，仅查询department_id对应的部门。设置为n时，查询department_id及其n级子部门的数据。仅在department_id参数传递时有效，最大值为4。
**示例值**：0
**默认值**：`0`
**数据校验规则**：
- 取值范围：`0` ～ `4`
page_size | int | 否 | 分页大小，取值范围 1~20
**示例值**：10
**默认值**：`10`
**数据校验规则**：
- 取值范围：`1` ～ `20`
page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
**示例值**："new-1a8f509162ca3c95405838d05ccded09"
### 请求体示例
```json
{
"date": "2021-10-11",
"cycle_type": "1",
"department_id": "dfd2f9g16dd75ggd",
"recursion": 2,
"page_size": 10,
"page_token": "new-f556d0f964cf4baab7092b5b0093317c"
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
has_more | boolean | 是否还有更多项
page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
items | application.department_app_usage\[\] | 部门内员工使用应用的概览数据
department_id | string | 租户内部门的唯一标识，ID值与查询参数中的department_id_type 对应。
app | application.app_usage\[\] | 应用整体使用情况，指标值包括：uv：活跃用户数，total_users：累计用户数，new_users：新增用户数，pv：在应用（小程序或网页）中访问的页面数，lifecycle：打开应用（小程序或网页）的次数
metric_name | string | 指标名称
metric_value | int | 指标值
gadget | application.app_usage\[\] | 小程序使用情况，没有小程序形态时为null，指标值包括：uv（小程序活跃用户数）、pv（用户在小程序中的访问页面数）、lifecycle（小程序的打开次数）
metric_name | string | 指标名称
metric_value | int | 指标值
webapp | application.app_usage\[\] | 网页应用使用情况，没有网页应用形态时为null，指标值包括：uv（网页应用活跃用户数）、pv（用户在网页应用中的访问页面数）、lifecycle（网页应用的打开次数）
metric_name | string | 指标名称
metric_value | int | 指标值
bot | application.app_usage\[\] | 机器人使用情况，没有机器人形态时为null，
指标值包括：uv（机器人的活跃用户数）
metric_name | string | 指标名称
metric_value | int | 指标值
### 响应体示例
```json
{
"code": 0,
"data": {
"has_more": false,
"items": [
{
"department_id": "7a59bc779b7c1f19",
"app": [
{
"metric_name": "uv",
"metric_value": 141121
},
{
"metric_name": "total_users",
"metric_value": 141123
},
{
"metric_name": "new_users",
"metric_value": 141122
},
{
"metric_name": "pv",
"metric_value": 141122
},
{
"metric_name": "lifecycle",
"metric_value": 141122
}
],
"gadget": [
{
"metric_name": "uv",
"metric_value": 141124
},
{
"metric_name": "pv",
"metric_value": 141122
},
{
"metric_name": "lifecycle",
"metric_value": 141122
}
],
"webapp": [
{
"metric_name": "uv",
"metric_value": 141127
},
{
"metric_name": "pv",
"metric_value": 141122
},
{
"metric_name": "lifecycle",
"metric_value": 141122
}
]
},
{
"app": [
{
"metric_name": "uv",
"metric_value": 0
}
],
"department_id": "33a1ec888371b1f8"
}
],
"page_token": ""
},
"msg": "success"
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
403 | 211004 | no authority for quota limit | 检查是否是企业版/旗舰版租户
400 | 211005 | invalid app id | 检查 app id
400 | 211007 | invalid date format | 检查 date 字段的格式是否符合"2021-07-01"
400 | 211010 | invalid date range | 检查 date 的取值范围是否正确
404 | 211011 | data not found | 数据不存在。可能是该应用在目标查询日期范围内没有数据。请检查请求参数
400 | 210501 | invalid page_token | page_token 在应用间不互通，请检查该 page_token 是否由调用接口的应用获取到
400 | 210500 | page_token does not exist or has expired | 请检查 page_token 是否合法，page_token 过期时间为 2h，若超过 2h 请重新获取
## 附录-统计指标说明
指标 | 指标定义 | 备注
---|---|---
小程序应用活跃用户数 | - 打开小程序的唯一用户数，按用户ID去重 | - 支持查看某一天/某一周/某一个月的数据
网页应用活跃用户数 | - 打开网页应用的唯一用户数，按用户ID去重
- 只统计飞书内webview容器部分的数据，不包含三方浏览器容器的内容 | - 支持查看某一天/某一周/某一个月的数据
机器人应用活跃用户数 | - 满足以下条件之一就算作机器人的活跃用户：
- 机器人消息已读
- 主动给机器人发消息
- 单个统计周期内按照用户ID合并去重； | - 支持查看某一天/某一周/某一个月的数据
应用活跃用户数 | - 满足以下条件之一就算作应用的活跃用户：
- 打开小程序
- 打开h5
- 给机器人发消息
- 阅读机器人消息
- 单个统计时间周期内按 用户ID去重计数，以上所有条件合并去重 | - 支持查看某一天/某一周/某一个月的数据
应用累计用户数 | - 历史上所有使用过应用的用户数 | - 由于累计用户数与时间周期无关，所以只支持截止到某一天的累计用户数
- 即cycle_type只能为1
- 只支持查看应用粒度的累计用户数，不支持区分小程序网页和机器人。
- 注：累计用户数会包含离职人员的统计，所以可能会出现累计用户数大于租户成员数的情况
应用新增用户数 | - 统计周期内首次访问的唯一用户数 | - 支持查看某一天/某一周/某一个月的数据
- 只支持查看应用粒度的累计用户数，不支持区分小程序网页和机器人。
应用打开次数 | - 在飞书客户端内打开应用（小程序或网页）的次数 | - 注：当用户主动退出应用或切换至其他应用超 5min 后记为一次打开
页面访问数 | - 在应用（小程序或网页）中访问的页面次数 | - 注：若应用使用过程中切换到其他应用，再切换回飞书打开此应用时，pv会增加