# 获取妙搭应用运营数据趋势

获取妙搭应用运营数据趋势

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/spark/v1/apps/:app_id/query_analytics_data
HTTP Method | POST
接口频率限制 | [20 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 获取妙搭应用信息(spark:app:read)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`<br>或<br>`user_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 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<br>**示例值**："app_4jbp6bx8fwjgm"<br>**数据校验规则**：<br>- 长度范围：`1` ～ `1000` 字符

### 请求体

名称 | 类型 | 必填 | 描述
---|---|---|---
metric_types | string\[\] | 是 | 指标名列表<br>**示例值**：["TOTAL_USER , ACTIVE_USER, NEW_USER, PAGE_VIEW"]<br>**可选值有**：<br>- TOTAL_USER：累计用户数<br>- ACTIVE_USER：活跃用户数<br>- NEW_USER：新增用户数<br>- PAGE_VIEW：页面访问数<br>- API_REQUEST：暂不支持<br>**数据校验规则**：<br>- 长度范围：`1` ～ `20`
start_timestamp_ns | string | 是 | 起始时间戳，单位：纳秒<br>**示例值**："1782132931498000000"<br>**数据校验规则**：<br>- 长度范围：`1` ～ `20` 字符
end_timestamp_ns | string | 是 | 结束时间戳，单位：纳秒<br>**示例值**："1782132931498000000"<br>**数据校验规则**：<br>- 长度范围：`1` ～ `20` 字符
time_aggregation_unit | string | 是 | 时间聚合单元: DAY、WEEK、MONTH<br>**示例值**："DAY"<br>**可选值有**：<br>- DAY：天<br>- WEEK：周<br>- MONTH：月
filter | open_api_analytics_filter | 否 | 其他过滤条件，key: 匹配字段名称（所有指标共享）
page | string | 否 | 页面路径<br>**示例值**："/home"<br>**数据校验规则**：<br>- 长度范围：`1` ～ `10000` 字符
device_types | string\[\] | 否 | 终端类型<br>**示例值**：["mobile"]<br>**数据校验规则**：<br>- 长度范围：`1` ～ `10`
need_pack_lack_point | boolean | 否 | 是否需要补点：<br>- true 时对缺失的时间点补 0；<br>- false 时只返回原始数据点。<br>**示例值**：true
group_by | string | 否 | 按字段聚合，当前只支持 device_ytpe<br>**示例值**："device_type"<br>**数据校验规则**：<br>- 长度范围：`1` ～ `1000` 字符

### 请求体示例
```json
{
    "metric_types": [
        "TOTAL_USER , ACTIVE_USER, NEW_USER, PAGE_VIEW"
    ],
    "start_timestamp_ns": "1782132931498000000",
    "end_timestamp_ns": "1782132931498000000",
    "time_aggregation_unit": "DAY",
    "filter": {
        "page": "/home",
        "device_types": [
            "mobile"
        ]
    },
    "need_pack_lack_point": true,
    "group_by": "device_type"
}
```

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
series | open_api_analytics_data_series\[\] | 序列
metric_type | string | 指标类型<br>**可选值有**：<br>- TOTAL_USER：累计用户数<br>- ACTIVE_USER：活跃用户数<br>- NEW_USER：新增用户数<br>- PAGE_VIEW：页面访问数<br>- API_REQUEST：API 请求数
points | open_api_analytics_data\[\] | 数据点
timestamp_ns | string | 数据点的时间戳，单位：纳秒
value | number(float) | 数据点的值
dimensions | kv\[\] | 数据点的维度
key | string | key
value | string | value

### 响应体示例
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "series": [
            {
                "metric_type": "TOTAL_USER",
                "points": [
                    {
                        "timestamp_ns": "1782132931498000000",
                        "value": 1,
                        "dimensions": [
                            {
                                "key": "foo",
                                "value": "bar"
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
```

### 错误码

HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 3340001 | param is invalid | 请求参数无效，请检查参数是否符合要求。
404 | 3340004 | App not found | 请确定应用是否存在或是否具有开发者权限
500 | 3340500 | Internal server error | 服务端异常，请稍后再试