云开发 /getStatistics

# cloudbase.getStatistics

> 本接口应在服务器端调用，详细说明参见[服务端API](https://developers.weixin.qq.com/miniprogram/dev/framework/server-ability/backend-api.html)。

> 本接口支持[云调用](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/openapi/openapi.html)。需开发者工具版本 >= `1.02.1904090`（最新[稳定版下载](https://developers.weixin.qq.com/miniprogram/dev/devtools/stable.html)），`wx-server-sdk` >= `0.4.0`

获取云开发数据接口

调用方式：

- [HTTPS 调用](https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/cloudbase/cloudbase.getStatistics.html#method-http)
- [云调用](https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/cloudbase/cloudbase.getStatistics.html#method-cloud)



## HTTPS 调用

### 请求地址

```text
POST https://api.weixin.qq.com/tcb/getstatistics?access_token=TOKEN
```

### 请求参数

| 属性                                  | 类型      | 默认值 | 必填 | 说明                                                         |
| :------------------------------------ | :-------- | :----- | :--- | :----------------------------------------------------------- |
| access_token / cloudbase_access_token | string    |        | 是   | [接口调用凭证](https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/access-token/auth.getAccessToken.html) |
| action                                | string    |        | 是   | 获取动作，目前支持（smsMarketingOverviewData：短信营销概览数据；smsMarketingConversionData：短信营销转化数据；smsMarketingRealTimeData：短信营销实时数据） |
| begin_date                            | number    |        | 是   | 开始时间戳                                                   |
| end_date                              | number    |        | 是   | 结束时间戳                                                   |
| page_offset                           | number    |        | 是   | 分页 offset【action 取 smsMarketingOverviewData、smsMarketingConversionData 时必填】 |
| page_limit                            | number    |        | 是   | 分页 limit【action 取 smsMarketingOverviewData、smsMarketingConversionData 时必填】 |
| condition                             | Condition |        | 是   | 查询条件                                                     |

### 返回值

### Object

返回的 JSON 数据包

| 属性          | 类型           | 说明                                                         |
| :------------ | :------------- | :----------------------------------------------------------- |
| env_id        | string         | [环境 ID](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/quickstart.html#_2-开通云开发、创建环境) |
| activity_id   | string         | 活动 ID                                                      |
| by_channel_id | string         | 是否按渠道划分（0：返回概览数据；1：返回各个渠道的数据，可以用于饼图）【action 取 smsMarketingOverviewData 时必填】 |
| channel_id    | string         | 渠道 ID（云开发 CMS 使用 `_cms_sms_`）【action 取 smsMarketingConversionData、smsMarketingRealTimeData 时必填】 |
| act_type      | string         | 行为数据（h5：打开 H5；wxapp：跳转小程序）【action == smsMarketingRealTimeData 时必填】 |
| errcode       | number         | 错误码                                                       |
| data_column   | Array.<Object> | 数据列定义                                                   |
| data_value    | Array.<Object> | 数据行                                                       |
| total_num     | number         | 总行数                                                       |

**errcode 的合法值**

| 值    | 说明                           | 最低版本 |
| :---- | :----------------------------- | :------- |
| 0     | 请求成功                       |          |
| -1    | 系统繁忙，此时请开发者稍候再试 |          |
| 10011 | 没有数据                       |          |

**data_column 的结构**

| 属性          | 类型   | 说明                                     |
| :------------ | :----- | :--------------------------------------- |
| col_id        | string | 列 id                                    |
| col_name      | string | 列名                                     |
| col_data_type | string | 数据类型（0:string；1:number；2:double） |

**data_value 的结构**

| 属性       | 类型           | 说明   |
| :--------- | :------------- | :----- |
| data_value | Array.<string> | 数据值 |

### 请求概览数据示例

```json
{
  "action":"smsMarketingOverviewData",
  "begin_date": 1614182400,
  "end_date": 1614268800,
  "page_offset":0,
  "page_limit":1000,
  "condition":
  {
    "env_id":"xxx",
    "activity_id":"xxx",
    "by_channel_id":"0"
  }
}
```

### 请求概览数据（按渠道）示例

```json
{
  "action":"smsMarketingOverviewData",
  "begin_date": 1614182400,
  "end_date": 1614268800,
  "page_offset":0,
  "page_limit":1000,
  "condition":
  {
    "env_id":"xxx",
    "activity_id":"xxx",
    "by_channel_id":"1"
  }
}
```

### 请求漏斗图数据示例

```json
{
  "action":"smsMarketingConversionData",
  "begin_date": 1614182400,
  "end_date": 1614268800,
  "page_offset":0,
  "page_limit":1000,
  "condition":
  {
    "env_id":"xxx",
    "activity_id":"xxx",
    "channel_id":"xxx"
  }
}
```

### 请求打开 H5 实时数据示例

```json
{
  "action":"smsMarketingRealTimeData",
  "begin_date": 1614182400,
  "end_date": 1614268800,
  "condition":
  {
    "env_id":"xxx",
    "activity_id":"xxx",
    "channel_id":"xxx",
    "act_type":"h5"
  }
}
```

### 返回漏斗数据示例

```json
{
  "data_column":[
    {
      "col_id":"appid",
      "col_name":"小程序id",
      "col_data_type":"0"
    },
    {
      "col_id":"env_id",
      "col_name":"环境id",
      "col_data_type":"0"
    },
    {
      "col_id":"activity_id",
      "col_name":"活动id",
      "col_data_type":"0"
    },
    {
      "col_id":"channel_id",
      "col_name":"渠道",
      "col_data_type":"0"
    },
    {
      "col_id":"h5_open_uercnt",
      "col_name":"h5打开人数",
      "col_data_type":"1"
    },
    {
      "col_id":"jump_wxapp_uercnt",
      "col_name":"小程序跳转人数",
      "col_data_type":"1"
    },
    {
      "col_id":"sms_send_uercnt",
      "col_name":"短信下发人数",
      "col_data_type":"1"
    },
    {
      "col_id":"sms_send_list",
      "col_name":"下发记录数组",
      "col_data_type":"0"
    },
    {
      "col_id":"jump_wxapp_uercnt_percent",
      "col_name":"跳转人数渠道占比",
      "col_data_type":"2"
    },
    {
      "col_id":"h5_open_uercnt_percent",
      "col_name":"h5打开人数渠道占比",
      "col_data_type":"2"
    },
    {
      "col_id":"h5_sms_rate",
      "col_name":"短信到h5转化率",
      "col_data_type":"2"
    },
    {
      "col_id":"jump_h5_rate",
      "col_name":"h5到跳转转化率",
      "col_data_type":"2"
    }
  ],
  "data_value":[
    {
      "data_value":[
        "xxxxxxxxxxxxxxxxxx",
        "wedcvfr",
        "21ded5cb6001691405171ba161c603d1",
        "_cms_sms_",
        "5000",
        "3000",
        "10000",
        "[task1:5000,task2:5000]",
        "0.535714",
        "0.625",
        "0.5",
        "0.6"
      ]
    }
  ],
  "total_num":1
}
```



## 云调用

> [云调用](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/openapi/openapi.html)是微信云开发提供的在云函数中调用微信开放接口的能力，需要在云函数中通过 `wx-server-sdk` 使用。

### 接口方法

```js
openapi.cloudbase.getStatistics
```

> 需在 `config.json` 中配置 `cloudbase.getStatistics` API 的权限，[详情](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/openapi/openapi.html#usage-3)

### 请求参数

| 属性       | 类型      | 默认值 | 必填 | 说明                                                         |
| :--------- | :-------- | :----- | :--- | :----------------------------------------------------------- |
| action     | string    |        | 是   | 获取动作，目前支持（smsMarketingOverviewData：短信营销概览数据；smsMarketingConversionData：短信营销转化数据；smsMarketingRealTimeData：短信营销实时数据） |
| beginDate  | number    |        | 是   | 开始时间戳                                                   |
| endDate    | number    |        | 是   | 结束时间戳                                                   |
| pageOffset | number    |        | 是   | 分页 offset【action 取 smsMarketingOverviewData、smsMarketingConversionData 时必填】 |
| pageLimit  | number    |        | 是   | 分页 limit【action 取 smsMarketingOverviewData、smsMarketingConversionData 时必填】 |
| condition  | Condition |        | 是   | 查询条件                                                     |

### 返回值

### Object

返回的 JSON 数据包

| 属性        | 类型           | 说明                                                         |
| :---------- | :------------- | :----------------------------------------------------------- |
| envId       | string         | [环境 ID](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/quickstart.html#_2-开通云开发、创建环境) |
| activityId  | string         | 活动 ID                                                      |
| byChannelId | string         | 是否按渠道划分（0：返回概览数据；1：返回各个渠道的数据，可以用于饼图）【action 取 smsMarketingOverviewData 时必填】 |
| channelId   | string         | 渠道 ID（云开发 CMS 使用 `_cms_sms_`）【action 取 smsMarketingConversionData、smsMarketingRealTimeData 时必填】 |
| actType     | string         | 行为数据（h5：打开 H5；wxapp：跳转小程序）【action == smsMarketingRealTimeData 时必填】 |
| errCode     | number         | 错误码                                                       |
| dataColumn  | Array.<Object> | 数据列定义                                                   |
| dataValue   | Array.<Object> | 数据行                                                       |
| totalNum    | number         | 总行数                                                       |

**errCode 的合法值**

| 值   | 说明 | 最低版本 |
| :--- | :--- | :------- |
| 0    | 成功 |          |

**dataColumn 的结构**

| 属性        | 类型   | 说明                                     |
| :---------- | :----- | :--------------------------------------- |
| colId       | string | 列 id                                    |
| colName     | string | 列名                                     |
| colDataType | string | 数据类型（0:string；1:number；2:double） |

**dataValue 的结构**

| 属性      | 类型           | 说明   |
| :-------- | :------------- | :----- |
| dataValue | Array.<string> | 数据值 |

### 异常

### Object

抛出的异常

| 属性    | 类型   | 说明   |
| :------ | :----- | :----- |
| errCode | number | 错误码 |

**errCode 的合法值**

| 值    | 说明                           | 最低版本 |
| :---- | :----------------------------- | :------- |
| -1    | 系统繁忙，此时请开发者稍候再试 |          |
| 10011 | 没有数据                       |          |

### 请求概览数据示例

```js
const cloud = require('wx-server-sdk')
cloud.init({
  env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.cloudbase.getStatistics({
        "action": 'smsMarketingOverviewData',
        "condition": {
          "envId": 'xxx',
          "activityId": 'xxx',
          "byChannelId": '0'
        },
        "beginDate": 1614182400,
        "endDate": 1614268800,
        "pageOffset": 0,
        "pageLimit": 1000
      })
    return result
  } catch (err) {
    return err
  }
}
```

### 请求概览数据（按渠道）示例

```js
const cloud = require('wx-server-sdk')
cloud.init({
  env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.cloudbase.getStatistics({
        "action": 'smsMarketingOverviewData',
        "condition": {
          "envId": 'xxx',
          "activityId": 'xxx',
          "byChannelId": '1'
        },
        "beginDate": 1614182400,
        "endDate": 1614268800,
        "pageOffset": 0,
        "pageLimit": 1000
      })
    return result
  } catch (err) {
    return err
  }
}
```

### 请求漏斗图数据示例

```js
const cloud = require('wx-server-sdk')
cloud.init({
  env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.cloudbase.getStatistics({
        "action": 'smsMarketingConversionData',
        "condition": {
          "envId": 'xxx',
          "activityId": 'xxx',
          "channelId": 'xxx'
        },
        "beginDate": 1614182400,
        "endDate": 1614268800,
        "pageOffset": 0,
        "pageLimit": 1000
      })
    return result
  } catch (err) {
    return err
  }
}
```

### 请求打开 H5 实时数据示例

```js
const cloud = require('wx-server-sdk')
cloud.init({
  env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.cloudbase.getStatistics({
        "action": 'smsMarketingRealTimeData',
        "condition": {
          "envId": 'xxx',
          "activityId": 'xxx',
          "channelId": 'xxx',
          "actType": 'h5'
        },
        "beginDate": 1614182400,
        "endDate": 1614268800
      })
    return result
  } catch (err) {
    return err
  }
}
```

### 返回漏斗数据示例

```json
{
  "dataColumn": [
    {
      "colId": "appid",
      "colName": "小程序id",
      "colDataType": "0"
    },
    {
      "colId": "env_id",
      "colName": "环境id",
      "colDataType": "0"
    },
    {
      "colId": "activity_id",
      "colName": "活动id",
      "colDataType": "0"
    },
    {
      "colId": "channel_id",
      "colName": "渠道",
      "colDataType": "0"
    },
    {
      "colId": "h5_open_uercnt",
      "colName": "h5打开人数",
      "colDataType": "1"
    },
    {
      "colId": "jump_wxapp_uercnt",
      "colName": "小程序跳转人数",
      "colDataType": "1"
    },
    {
      "colId": "sms_send_uercnt",
      "colName": "短信下发人数",
      "colDataType": "1"
    },
    {
      "colId": "sms_send_list",
      "colName": "下发记录数组",
      "colDataType": "0"
    },
    {
      "colId": "jump_wxapp_uercnt_percent",
      "colName": "跳转人数渠道占比",
      "colDataType": "2"
    },
    {
      "colId": "h5_open_uercnt_percent",
      "colName": "h5打开人数渠道占比",
      "colDataType": "2"
    },
    {
      "colId": "h5_sms_rate",
      "colName": "短信到h5转化率",
      "colDataType": "2"
    },
    {
      "colId": "jump_h5_rate",
      "colName": "h5到跳转转化率",
      "colDataType": "2"
    }
  ],
  "dataValue": [
    {
      "dataValue": [
        "xxxxxxxxxxxxxxxxxx",
        "wedcvfr",
        "21ded5cb6001691405171ba161c603d1",
        "_cms_sms_",
        "5000",
        "3000",
        "10000",
        "[task1:5000,task2:5000]",
        "0.535714",
        "0.625",
        "0.5",
        "0.6"
      ]
    }
  ],
  "totalNum": 1,
  "errMsg": "openapi.cloudbase.getStatistics:ok"
}
```