创建指标视图

接口描述

本接口用于创建指标视图。调用方可以配置视图名称、展示名、指标、维度、主时间筛选、普通筛选、指标结果筛选、排序规则，以及临时指标定义等内容。

创建成功后，服务端会将该指标视图标记为 OPENAPI 创建来源，并返回操作结果。

接口 URL

POST http://{anymetrics_host:anymetrics_port}/anymetrics/api/v1/analysisview/create

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 填写对应认证值。

Body 参数

参数	类型	是否必选	最大长度	描述
viewName	String	是	50	指标视图英文名称。仅支持字母、数字、下划线，租户内不可重复
displayName	String	是	128	指标视图展示名
description	String	否	-	指标视图描述
metrics	Array[String]	是	-	指标列表。元素可填写指标名称/展示名；接口会按租户内资源映射替换为内部 code。使用 metricDefinitions 定义的临时指标时，元素可填写临时指标 key
dimensions	Array[String]	否	-	维度列表。支持维度名称/展示名；带粒度时使用 维度__粒度 格式
timeConstraint	String	否	-	主时间筛选表达式，保存为 [metric_time] 相关表达式
filters	Array[String]	否	-	普通筛选表达式列表，表达式中的维度名称/展示名会被替换为内部 code
resultFilters	Array[String]	否	-	指标结果筛选表达式列表，只能筛选本次 metrics 中包含的指标或临时指标
orders	Array[Object]	否	-	排序规则。每个对象只配置一个字段，key 为指标或维度，value 为 ASC 或 DESC，大小写均可
metricDefinitions	Object	否	-	临时指标定义。key 为临时指标标识，value 为指标定义对象

metricDefinitions 对象说明

metricDefinitions 用于在视图内定义临时指标。它是一个 Map 结构，外层 key 是临时指标标识，value 是该临时指标的定义对象。

请求中的 metrics、orders、resultFilters 可以引用 metricDefinitions 的外层 key。在处理 metrics、orders、resultFilters 时，如果发现字段名属于 metricDefinitions 的 key，会按临时指标处理，不再把它替换成已有指标或维度的内部 code。

示例结构：

{
  "metrics": ["orderCountRecent7Days"],
  "orders": [
    {
      "orderCountRecent7Days": "DESC"
    }
  ],
  "metricDefinitions": {
    "orderCountRecent7Days": {
      "id": "orderCountRecent7Days",
      "refMetric": "订单数",
      "filters": [
        "[下单日期]>=DateAdd(Now(),-7,\"DAY\")"
      ]
    }
  }
}

metricDefinitions.{key} 参数

参数	类型	是否必选	描述
id	String	否	临时指标标识。建议与 metricDefinitions 外层 key 保持一致，便于在 metrics、orders、resultFilters 中引用
refMetric	String	是	临时指标引用的基础指标。支持传入指标 code、指标名称或展示名，接口会按当前租户资源映射替换为内部 code
period	String	否	统计周期标识。用于周期类派生或自定义周期场景，传入值需与系统中可识别的周期配置一致
metricGrain	String	否	指标计算粒度。常用于需要指定计算粒度的派生指标，取值通常为时间粒度，如 DAY、WEEK、MONTH 等
onlyContainsDateTag	String	否	日期标签限制。用于周期或同环比等带日期标签的计算场景，传入值需与系统日期标签配置一致
filters	Array[String]	否	临时指标内部筛选表达式列表。表达式中的维度支持名称/展示名，接口会替换为内部 code
indirections	Array[String]	否	派生计算配置列表。支持同环比、排名、占比、自定义聚合等派生协议字符串
specifyDimension	Object	否	指定维度配置，用于限定临时指标参与计算的维度范围
expr	String	否	表达式。用于表达式型临时指标或需要公式计算的场景
preAggs	Array[Object]	否	周期预聚合配置。用于先按指定粒度聚合，再进行后续指标计算的场景

indirections 说明

indirections 是派生计算协议字符串数组。每个字符串表示一种派生计算配置。

常见类型包括：

类型	说明	示例
sameperiod	同环比类计算	sameperiod__mom__value
rank	排名类计算	订单数__rank__商品类目
proportion	占比类计算	订单数__proportion__商品类目
multi_level_agg	多层聚合/自定义聚合	multi_level_agg__avg,商品类目

同环比短格式通常为：

sameperiod__{周期}__{计算方式}

带偏移量时通常为：

sameperiod__{偏移量}_{周期}__{计算方式}

常见周期标识：

标识	说明
yoy	年同比
qoq	季同比
mom	月同比
wow	周同比
dod	日同比
hod	小时同比

常见计算方式：

标识	说明
value	同比/环比值
growthvalue	同比/环比增长值
growth	同比/环比增长率

示例：

{
  "metricDefinitions": {
    "orderCountMomGrowth": {
      "id": "orderCountMomGrowth",
      "refMetric": "订单数",
      "indirections": [
        "sameperiod__mom__growth"
      ]
    }
  }
}

说明：如果 indirections 字符串中包含指标、维度名称，接口会尝试按当前租户资源映射替换为内部 code。使用临时指标 key 时不会替换该 key。

specifyDimension 对象说明

参数	类型	是否必选	描述
type	String	是	指定方式。支持 INCLUDE、EXCLUDE。INCLUDE 表示仅包含指定维度，EXCLUDE 表示排除指定维度
dimensions	String	是	维度列表，多个维度使用英文逗号分隔。支持维度名称/展示名，接口会替换为内部 code

示例：

{
  "specifyDimension": {
    "type": "INCLUDE",
    "dimensions": "商品类目,城市"
  }
}

preAggs 对象说明

参数	类型	是否必选	描述
granularity	String	是	时间粒度。支持 YEAR、QUARTER、MONTH、WEEK、DAY、HOUR、MINUTE、SECOND
calculateType	String	是	聚合方式。支持 COUNT、COUNT_DISTINCT、COUNTDISTINCT、SUM、AVG、MAX、MIN

示例：

{
  "preAggs": [
    {
      "granularity": "DAY",
      "calculateType": "SUM"
    }
  ]
}

请求示例

基础创建

{
  "viewName": "OrderAnalysisView",
  "displayName": "订单分析视图",
  "description": "订单指标视图",
  "metrics": ["订单数"],
  "dimensions": ["商品类目"],
  "timeConstraint": "[metric_time]>=Date(\"2023-01-01\",\"yyyy-MM-dd\") AND [metric_time]<=Date(\"2023-01-10\",\"yyyy-MM-dd\")",
  "filters": [
    "[是否草稿]=\"No\""
  ],
  "resultFilters": [
    "[订单数]>100"
  ],
  "orders": [
    {
      "商品类目": "ASC"
    },
    {
      "订单数": "DESC"
    }
  ]
}

使用临时指标

{
  "viewName": "OrderAnalysisViewWithTempMetric",
  "displayName": "订单分析视图-临时指标",
  "description": "包含临时指标的订单指标视图",
  "metrics": ["orderCountRecent7Days"],
  "dimensions": ["商品类目"],
  "filters": [
    "[是否草稿]=\"No\""
  ],
  "resultFilters": [
    "[orderCountRecent7Days]>100"
  ],
  "orders": [
    {
      "orderCountRecent7Days": "DESC"
    }
  ],
  "metricDefinitions": {
    "orderCountRecent7Days": {
      "id": "orderCountRecent7Days",
      "refMetric": "订单数",
      "filters": [
        "[下单日期]>=DateAdd(Now(),-7,\"DAY\")"
      ]
    }
  }
}

响应参数

接口返回会经过全局响应包装。创建成功时，data 为 true。

参数	类型	是否必选	描述
success	Boolean	是	请求是否成功
code	String	是	响应码，成功为 200
data	Boolean	是	操作结果。创建成功为 true
traceId	String	是	跟踪 ID，用于问题排查
errorMsg	String	否	错误信息，失败时返回
detailErrorMsg	String	否	详细错误信息，失败时返回

响应示例

成功响应

{
  "data": true,
  "success": true,
  "code": "200",
  "traceId": "fdde6861bd554805998343f9ff2dcd70.292.16857691758642861"
}

失败响应

{
  "success": false,
  "code": "ANALYSIS_VIEW_NAME_INVALID",
  "errorMsg": "指标视图名称不合法",
  "detailErrorMsg": "fdde6861bd554805998343f9ff2dcd70.292.16857691758642861",
  "traceId": "fdde6861bd554805998343f9ff2dcd70.292.16857691758642861"
}