QueryDataService接口用于调用在数据服务中已创建的API。

前提条件

您通过Quick BI的数据服务,创建数据服务的API,具体请参见数据服务

使用限制

  • 数据服务功能仅针对专业版客户开放。
  • 数据服务API调用,接口超时时间为60s,单个API的QPS为10次/秒。
  • 数据服务API所引用数据集,如果开启了行级权限,API调用的时候可能会被行级权限策略拦截。

请求参数

名称 类型 是否必选 示例值 描述
Action String QueryDataService

系统规定参数。取值:QueryDataService。

ApiId String f4cc43bc3***

数据服务中的API ID,请参见:数据服务

Conditions String { "area": ["华东", "华北"], "shopping_date": "2019Q1", }

数据服务的查询条件,以Key和Value的形式传入。map类型的字符串。其中,Key为请求参数的参数名,Value为请求参数的参数值。Key和Value必须成对出现。

说明:
  • value包含多个值时,则value值是JSON形式的List。例如: area=["华东","华北","华南"]
  • 对于日期,根据类型不同,提供不同的入参格式:
    • 年:2019
    • 季:2019Q1
    • 月:201901 (携带0)
    • 周:2019-52
    • 日:20190101
    • 时:14:00:00 (分、秒为00)
    • 分:14:12:00 (秒为00)
    • 秒:14:34:34
ReturnFields String ["area", "city", "price", "date"]

返回参数的参数名列表,List 类型字符串。

返回数据

名称 类型 示例值 描述
RequestId String 0c52dbfa-85de-41e8-9dab-43af8e1952a3

请求 ID。

Result Struct

返回接口查询结果。

Headers Array of Headers

列头。

Aggregator String SUM

聚合操作符。度量字段才会有,例如SUM、AVG和MAX。

Column String 具体的物理字段名

字段名,对应物理表字段名。

DataType String string

字段的数据类型。一般有

number、string、date、datetime、time、geographic。

Granularity String yearRegion

维度字段的粒度。

当请求字段为日期维度或地理维度字段,才会返回该字段,取值范围:

  • 日期粒度:yearRegion(年)、 monthRegion(月)、weekRegion(周)、dayRegion(日)、hourRegion(时)、minRegion(分)、secRegion(秒)
  • 地理信息粒度:COUNTRY("国际级")、PROVINCE("省级")、CITY("市级")、XIAN("区县")、REGION("区域")
Label String area

字段别名,结果参数values中Map数据行的Key。

Type String StandardDimension

字段类型,用于区分是字段类型为维度或度量字段。

Sql String SELECT COMPANY_T_1_.`area` AS D_AREA_2_, COMPANY_T_1_.`city` AS D_CITY_3_, SUM(COMPANY_T_1_.`profit_amt`) AS D_PROFIT_4_ FROM `quickbi_test`.`company_sales_record_copy` AS COMPANY_T_1_ WHERE COMPANY_T_1_.`area` LIKE '%华东%' GROUP BY COMPANY_T_1_.`area`, COMPANY_T_1_.`city` HAVING SUM(COMPANY_T_1_.`order_amt`) > 1 LIMIT 0, 10

请求查询的 SQL。

Values List [{"area":"华东","city":"三明市"},{"area":"华东","city":"上海市"}]

返回数据的行和列。

此参数为List<Map>结构,每个Map即一行数据。其中Map中的Key对应 Headers#Label字段。

Success Boolean true

是否请求成功。取值范围:

  • true:请求成功
  • false:请求失败

示例

请求示例

http(s)://quickbi-public.aliyuncs.com?Action=QueryDataService
&<公共请求参数>

正常返回示例

XML格式

<RequestId>0c52dbfa-85de-41e8-9dab-43af8e1952a3</RequestId>
<Success>true</Success>
<Result>
    <Headers>
        <Type>StandardDimension</Type>
        <Column>具体的物理字段名</Column>
        <Label>area</Label>
        <DataType>string</DataType>
        <Aggregator>SUM</Aggregator>
        <Granularity>yearRegion</Granularity>
    </Headers>
    <Values>[{"area":"华东","city":"三明市"},{"area":"华东","city":"上海市"}]</Values>
    <Sql>SELECT COMPANY_T_1_.`area` AS D_AREA_2_, COMPANY_T_1_.`city` AS D_CITY_3_, SUM(COMPANY_T_1_.`profit_amt`) AS D_PROFIT_4_ FROM `quickbi_test`.`company_sales_record_copy` AS COMPANY_T_1_ WHERE COMPANY_T_1_.`area` LIKE '%华东%' GROUP BY COMPANY_T_1_.`area`, COMPANY_T_1_.`city` HAVING SUM(COMPANY_T_1_.`order_amt`) &gt; 1 LIMIT 0, 10</Sql>
</Result>

JSON格式

{"RequestId":"0c52dbfa-85de-41e8-9dab-43af8e1952a3","Success":"true","Result":{"Headers":[{"Type":"StandardDimension","Column":"具体的物理字段名","Label":"area","DataType":"string","Aggregator":"SUM","Granularity":"yearRegion"}],"Values":"[{\"area\":\"华东\",\"city\":\"三明市\"},{\"area\":\"华东\",\"city\":\"上海市\"}]","Sql":"SELECT COMPANY_T_1_.`area` AS D_AREA_2_, COMPANY_T_1_.`city` AS D_CITY_3_, SUM(COMPANY_T_1_.`profit_amt`) AS D_PROFIT_4_ FROM `quickbi_test`.`company_sales_record_copy` AS COMPANY_T_1_ WHERE COMPANY_T_1_.`area` LIKE '%华东%' GROUP BY COMPANY_T_1_.`area`, COMPANY_T_1_.`city` HAVING SUM(COMPANY_T_1_.`order_amt`) > 1 LIMIT 0, 10"}}

错误码

HttpCode 错误码 错误信息 描述
500 API.No.Permission You are not authorized to call the data service API operation. 您无权调用此数据服务API。
500 API.Not.Exist The data service API operation does not exist. 数据服务 API 不存在。
500 Cube.Not.Exist The Cube does not exist. 数据集不存在。
500 Invalid.Parameter.Conditions The specified Conditions is invalid. %s is not defined. 参数 Conditions 错误:%s 未在模型中定义。
500 Invalid.Parameter.ReturnFields The specified returnFields is invalid. %s is not defined. 参数ReturnFields错误:%s 未在模型中定义。
500 Missing.Conditions The specified Conditions is invalid. You must specify %s. 输入参数Conditions 错误: %s 是必须项。
500 Missing.Dimension.Measure The dimension or measure %s does not exist in Cube. Cube 模型中缺少维度或度量 %s 。
500 Instance.Expired Your instance has expired. 您的购买实例已经过期。
500 Instance.Not.Exist The specified instance does not exist. 暂未匹配到您的购买实例。
500 Rowlevel.Permission.Forbbiden The request is denied by row level permission. The dataset is %s, %s %s. 请求被行级权限限制,数据集为%s,%s %s。
500 Internal.System.Error An internal system error occurred. 系统内部异常。

访问错误中心查看更多错误码。