创建指标

接口描述

本接口适用于在指标管理系统中新建指标。

版本支持

本文接口契约适用于 CAN 发布版本：V1.62.10+、V2.3.0+。

接口URL

POST Http://{anymetrics_host:anymetrics_port}/anymetrics/api/v1/metrics/createV2

anymetrics_host:anymetrics_port 获取方式请参考：调用方式

请求参数

公共请求参数(HEADERS)

参数	类型	是否必选	描述
tenant-id	String	是	`租户ID`，用于指标查询内容所在的租户
auth-type	String	是	认证方式。支持 `UID`、`TOKEN`、`ACCOUNT`、`APIKEY`
auth-value	String	是	与 `auth-type` 对应的认证值

公共参数获取方式

tenant-id 可在 Aloudata CAN 顶部导航栏选择指标应用，左边菜单栏选择 API 集成，在 API 集成界面获取；auth-value 请按 auth-type 填写对应认证值。

请求参数

请求参数说明

参数	类型	是否必选	说明
metricName	String	是	指标英文标识，映射到代码中的 `enDisplayName`。发布时必填，长度不超过 120。代码校验正则为 `^[a-z0-9A-Z_(\\-)]{1,128}$`
metricDisplayName	String	是	指标展示名称，发布时必填，长度不超过 120
metricCode	String	否	指标编码。若租户开启指标编码相关能力，建议始终传入；长度不超过 120
type	String	是	指标类型。当前接口实际支持：`ATOMIC`、`DERIVED`、`COMPOSITE`
owner	String	否	技术负责人账号 `account`，接口内部会转换为用户 `userId`
businessOwner	String	否	业务负责人账号 `account`，接口内部会转换为用户 `userId`
businessCaliber	String	否	业务口径，长度不超过 5000
caliber	Object	是	指标计算口径，按指标类型区分，见下文
unit	String	否	指标单位，见“指标单位枚举”
metricCategoryId	String	否	类目 ID。不传时默认 `-1`，表示“未分类”
isPublish	Boolean	否	是否直接发布。`true`：发布；`false`：保存草稿。默认 `true`
isNewDimensionDefaultEnable	Boolean	否	新增维度是否默认可用，作用于当前指标
availableDimensions	Array[String]	否	当前指标显式启用的维度列表
disableDimensions	Array[String]	否	当前指标显式禁用的维度列表
basicAttributes	Map[String, Object]	否	基础属性
businessAttributes	Map[String, Object]	否	业务属性
technicalAttributes	Map[String, Object]	否	技术属性
managementAttributes	Map[String, Object]	否	管理属性

指标计算口径

1. 原子指标 `ATOMIC`

参数	类型	是否必选	说明
datasetName	String	是	数据集名称
expr	String	是	聚合表达式
filters	Array[Object]	否	业务限定列表，建议参考：业务限定
metricTime	String	是	指标时间字段名。字段必须存在于 `datasetName` 中，且字段类型必须为 `DATE`、`DATE_TIME`、`DATETIME` 或 `TIMESTAMP`
enableNonAdditiveDimensions	Boolean	否	是否开启半累加维度
nonAdditiveDimensions	Array[Object]	否	半累加维度配置

nonAdditiveDimensions 参数说明

参数	类型	是否必选	说明
dimensions	Array[String]	是	半累加维度列表
windowChoice	String	是	窗口聚合方式。代码模型为 `AggType`，半累加场景通常使用 `MAX` 或 `MIN`
windowGroupings	Array[String]	否	窗口分组字段列表

2. 派生指标 `DERIVED`

参数	类型	是否必选	说明
refMetricCode	String	是	引用的上游指标系统 `code`
period	Object	否	统计周期。具体语法建议参考：API-时间限定语法说明
filters	Array[Object]	否	业务限定列表
preAggs	Array[Object]	否	预聚合方式
indirection	Object	否	衍生方式

发布创建时，period、filters、indirection 不能同时为空。

`indirection` 公共说明

indirection.type 支持以下 4 种取值：

SAME_PERIOD
RANK
PROPORTION
CUSTOM_AGG

同环比 `SAME_PERIOD`

参数	类型	是否必选	说明
type	String	是	固定为 `SAME_PERIOD`
samePeriodType	String	是	支持 `VALUE`、`GROWTH_VALUE`、`GROWTH`
granularity	String	否	兼容字段，可不传
offset	Object	是	偏移配置。当前代码实际依赖该字段做粒度与偏移判断

offset 参数说明：

参数	类型	是否必选	说明
granularity	String	是	粒度，例如 `DAY`、`WEEK`、`MONTH`、`QUARTER`、`YEAR`
offset	Integer	否	偏移值，例如 `-1`
dateTag	String	否	日期标识
specifyDateInPeriod	String	否	周期内指定日期

排名 `RANK`

参数	类型	是否必选	说明
type	String	是	固定为 `RANK`
rankRanges	Array[String]	否	排名范围
rankDimensions	Array[String]	否	排名维度
rankType	String	否	支持 `RANK`、`RANK_DENSE`、`ROW_NUMBER`
asc	Boolean	否	是否升序

占比 `PROPORTION`

参数	类型	是否必选	说明
type	String	是	固定为 `PROPORTION`
proportionRanges	Array[String]	否	占比范围
proportionDimensions	Array[String]	否	占比维度

自定义聚合 `CUSTOM_AGG`

参数	类型	是否必选	说明
type	String	是	固定为 `CUSTOM_AGG`
customDimensionGroups	Array[Object]	是	自定义聚合维度组，不能为空

customDimensionGroups 参数说明：

参数	类型	是否必选	说明
calculateType	String	是	支持 `MAX`、`MIN`、`AVG`、`SUM`
dimensions	Array[Object]	是	维度组合，不能为空

dimensions 参数说明：

参数	类型	是否必选	说明
name	String	是	维度名
granularity	String	否	仅时间维度需要，例如 `DAY`

3. 复合指标 `COMPOSITE`

参数	类型	是否必选	说明
expr	String	是	复合指标表达式。表达式中的指标引用使用 `[xxx]`
metricDefinitions	Map[String, Object]	否	临时派生指标定义

metricDefinitions 的 key 是临时指标名，value 结构如下：

参数	类型	是否必选	说明
refMetricCode	String	是	引用的上游指标系统 `code`
period	Object	否	统计周期
filters	Array[Object]	否	业务限定
preAggs	Array[Object]	否	预聚合
indirection	Object	否	衍生方式，结构与派生指标一致
displayName	String	否	临时指标展示名
dimensionConfig	Object	否	临时指标可用维度配置

复合指标 `dimensionConfig` 正确结构

这里和旧文档不同，当前代码实际识别的是下面这套结构：

{
  "isNewDimensionDefaultEnable": true,
  "publicDimension": {
    "availableDimensionNames": [
      "province"
    ],
    "disableDimensionNames": [
      "city"
    ]
  },
  "factorDimensions": [
    "dt"
  ]
}

说明：

availableDimensionNames 仅在 isNewDimensionDefaultEnable=false 时使用
disableDimensionNames 仅在 isNewDimensionDefaultEnable=true 时使用
factorDimensions 用于声明因子维度

指标单位参数说明

类别	单位代码	描述
货币单位	CNY_FEN	分
CNY_YUAN	元
CNY_WAN	万元
CNY_BAI_WAN	百万元
CNY_YI_YUAN	亿元
USD_CENT	美分
USD_DOLLAR	美元
EUR_EURO	欧元
HKD_DOLLAR	港元
时间单位	DAY	天
MONTH	月
WEEK	周
YEAR	年
HOUR	时
MINUTE	分
SECOND	秒
QUARTER	季度
MILLISECOND	毫秒
比例单位	DECIMAL	小数
PERCENTAGE	百分位数
PERMILLE	千分位数
名词	RANK	排名
对象量次	HOUSEHOLD	户
TRANSACTION	笔
ITEM	件
INDIVIDUAL	个
OCCURRENCE	次
PERSON_DAY	人日
FAMILY	家
HAND	手
SHEET	张
PACKAGE	包
重量单位	TON	吨
KILOGRAM	公斤
其他	OTHER	其他

请求示例

示例 1：发布创建原子指标

{
  "type": "ATOMIC",
  "metricName": "order_amount_sum_api_v2",
  "metricDisplayName": "订单金额",
  "metricCode": "ORDER_AMOUNT_SUM_API_V2",
  "owner": "can1",
  "businessOwner": "can1",
  "businessCaliber": "统计订单金额总和",
  "metricCategoryId": "-1",
  "unit": "CNY_YUAN",
  "isPublish": true,
  "isNewDimensionDefaultEnable": true,
  "disableDimensions": [
    "city"
  ],
  "caliber": {
    "datasetName": "can_order",
    "expr": "SUM(['can_order'/'order_amount'])",
    "metricTime": "order_date",
    "filters": [
      {
        "type": "EXPR",
        "expr": "IN(['can_order'/'order_status'],\"paid\")"
      }
    ]
  },
  "basicAttributes": {},
  "businessAttributes": {},
  "technicalAttributes": {},
  "managementAttributes": {}
}

示例 2：复合指标中临时派生维度配置示例

{
  "type": "COMPOSITE",
  "metricName": "order_amount_ratio_api_v2",
  "metricDisplayName": "订单金额占比",
  "owner": "can1",
  "businessOwner": "can1",
  "unit": "PERCENTAGE",
  "isPublish": true,
  "caliber": {
    "expr": "[tmp_same_period]/[total_amount]",
    "metricDefinitions": {
      "tmp_same_period": {
        "refMetricCode": "total_amount",
        "indirection": {
          "type": "SAME_PERIOD",
          "samePeriodType": "VALUE",
          "offset": {
            "granularity": "YEAR",
            "offset": -1
          }
        },
        "dimensionConfig": {
          "isNewDimensionDefaultEnable": true,
          "publicDimension": {
            "disableDimensionNames": [
              "is_weekend"
            ]
          }
        }
      }
    }
  }
}

示例 3：创建派生指标

{
    "type": "DERIVED",
    "metricName": "cyl0year_ordercount_3",
    "metricDisplayName": "派生指标占比",
    "businessCaliber": "派生指标",
    "owner": null,
    "businessOwner": "correctness_test_qq",
    "caliber": {
        "refMetricCode": "ordercount_3",
        "period": {
            "type": "TO_DATE",
            "typeParams": "-29 day of 0 day"
        },
        "preAggs": [
            {
                "granularity": "DAY",
                "calculateType": "AVG"
            }
        ],
        "indirection": {
            "type": "PROPORTION",
            "proportionRanges": [
                "can_order_region"
            ],
            "proportionDimensions": [
                "can_shop_city"
            ]
        }
    },
    "unit": "OTHER",
    "metricCategoryId": "-1",
    "basicAttributes": null,
    "businessAttributes": null,
    "technicalAttributes": null,
    "managementAttributes": null
}

示例 4：创建复合指标

{
    "type": "COMPOSITE",
    "metricName": "apitest",
    "metricDisplayName": "apitest",
    "owner": "can1",
    "businessOwner": "can1",
    "unit": "OTHER",
    "businessCaliber": "这是一个文档实例复合指标",
    "caliber": {
        "expr": "[GeYpElmCMBtZehtg]/[sum_PZJERMB]", /*GeYpElmCMBtZehtg 指标引用至下方中的临时派生指标。sum_PZJERMB为原始指标名称 */
        "metricDefinitions": {
                "GeYpElmCMBtZehtg": { /*临时派生指标名称建议使用16位uuid */
                    "refMetricCode": "sum_rmb",
                    "period": {
                        "type": "RELATIVE_DATE",
                        "periodGrain": null,
                        "onlyContainsDateTag": n    ull,
                        "typeParams": "0 day of 0 day",
                        "customDateTag": null,
                        "granularity": "DAY"
                    },
                    "filters": [
                        {
                            "type": "EXPR",
                            "periodGrain": null,
                            "onlyContainsDateTag": null,
                            "expr": "NotNull(['is_weekend'])"
                        }
                    ],
                    "preAggs": null,
                    "indirection": {
                        "type": "SAME_PERIOD",
                        "samePeriodType": "VALUE",
                        "granularity": null,
                        "offset": {
                            "granularity": "YEAR",
                            "offset": -1,
                            "dateTag": null,
                            "specifyDateInPeriod": null
                        }
                    },
                    "dimensionConfig": {
                        "isNewDimensionDefaultEnable": true,
                        "disableDimensions": [
                            "is_weekend"

                        ],
                        "availableDimensions": null,
                        "factorDimensions": null
                    },
                    "displayName": null
                }
            }
    },
    "metricCode": "api_up_radio2",
    "basicAttributes": {
    },
    "businessAttributes": {
    },
    "technicalAttributes": {
    },
    "managementAttributes": {
    }
}

响应参数

参数	类型	说明
data	String	新建成功后返回的指标系统 `code`
success	Boolean	是否成功
code	String	响应码
errorMsg	String	错误信息
detailErrorMsg	String	详细错误信息
traceId	String	请求追踪 ID

响应示例

{
  "data": "mcadb2046729c26c67c355bc4e32",
  "success": true,
  "code": "200",
  "errorMsg": null,
  "detailErrorMsg": null,
  "traceId": "9644bd804e2747088086bb04730e20ba.144.17194894357700043"
}

创建指标

接口描述

接口URL

请求参数

公共请求参数(HEADERS)

公共参数获取方式

请求参数

请求参数说明

指标计算口径

1. 原子指标 ATOMIC

nonAdditiveDimensions 参数说明

2. 派生指标 DERIVED

indirection 公共说明

同环比 SAME_PERIOD

排名 RANK

占比 PROPORTION

自定义聚合 CUSTOM_AGG

3. 复合指标 COMPOSITE

复合指标 dimensionConfig 正确结构

指标单位参数说明

请求示例

示例 1：发布创建原子指标

示例 2：复合指标中临时派生维度配置示例

示例 3：创建派生指标

示例 4：创建复合指标

响应参数

响应示例

1. 原子指标 `ATOMIC`

2. 派生指标 `DERIVED`

`indirection` 公共说明

同环比 `SAME_PERIOD`

排名 `RANK`

占比 `PROPORTION`

自定义聚合 `CUSTOM_AGG`

3. 复合指标 `COMPOSITE`

复合指标 `dimensionConfig` 正确结构