本文主要介绍使用阿里云QuickBI SDK调用QuickBI 开放数据服务API。

数据服务API

下面为您介绍数据服务 API 调用的使用说明,包含入参说明以及返回参数说明。

表 1. 入参说明
参数 类型 说明 是否必传 示例
serviceId string 数据服务API的ID。 89f3767c5c1f
returnFields json格式的字符串 返回参数的参数名。 否。

若为空,则默认返回所有指定的返回参数。

["area", "city", "price", "date"]
conditions json格式的字符串 请求参数的参数值,map类型的字符串。其中:

key为请求参数的参数名。

value为请求参数的参数替换值。

说明
  • value可能包含多个值的情况。此时value值是json形式的List,例如,area=["华东","华北","华南"]
  • 对于日期,根据类型不同,提供不同的入参格式:
    • 年:2019
    • 季:2019Q1
    • 月:201901
    • 周:2019-52
    • 日:20190101
    • 时:14:00:00
    • 分:14:12:00
    • 秒:14:34:34
  • 当请求参数为必填项时,conditions中必传该参数;否则,校验不通过。
{
"area": ["华东", "华北"],
"shopping_date": "2019Q1"
}
表 2. 返回参数说明
字段 类型 说明 示例
RequestId string 请求 ID。 f554a46a-8ccd-435e-9b1b-b19b6aedd5c6
Success boolean 结果状态位,表示是否成功。 true
Code string 错误码。
  • 0表示成功
  • 其他,为错误码,表示失败。
AE10000005
Message string 错误码原因说明。 Parameter validation failed
Result map 请求正确时的返回结果。 请参见示例
|_ headers list 字段头说明。 -
|__column string 字段名,对应物理表字段名。 -
|__dataType string 字段的数据类型。一般有number | string |date| datetime | time |geographic string
|__label string 字段别名,即,数据服务的返回字段的参数名。 -
|__type string 字段类型,用于区分是维度还是度量。 -
|__granularity string 维度字段的粒度,日期维度或者地理维度字段才会返回该字段,主要有:
  • 日期粒度:
    • yearRegion(年)
    • monthRegion(月)
    • weekRegion(周
    • dayRegion(日)
    • hourRegion(时)
    • minRegion(分)
    • secRegion(秒)
  • 地理维度粒度:
    • OUNTRY("国际级")
    • PROVINCE("省级")
    • CITY("市级")
    • XIAN("区县")
    • REGION("区域")
-
|__aggregator string 聚合操作符。当 |__type字段的取值是度量时才返回该参数。 SUM、AVG、MAX等
|_ values list 返回的数据行列。 -
|__v string value:返回值。 -
|__r string raw:实际值。 -
|__l string label:对应的字段名。 -
|_ sql string 本次请求查询的SQL。 select * from table_a

示例:

当接口正常请求到数据服务API时,返回结果如下:
{
    "RequestId":"f554a46a-8ccd-435e-9b1b-b19b6aedd5c6",   // 
    "Success":true,       // 正确时,返回结果为true;请求出错,为 false
    "Code":"0",           // 返回码, 0 表示成功;其他,为错误码,表示失败
    "Message":"success",  // 返回码说明。
    "Result":{            // 结果集
        "headers":[
            {
                "dataType":"string",
                "column":"province",
                "label":"province",
                "type":"StandardDimension"
            },
            {
                "dataType":"string",
                "granularity":"dateRegion",
                "column":"report_date",
                "label":"report_date",
                "type":"StrDateTypeDimension"
            },
            {
                "dataType":"string",
                "aggregator":"SUM",
                "column":"profit_amt",
                "label":"profit_amt",
                "type":"measureCol"
            }
        ],
        "values":[
            [
                {
                    "v":"上海省",
                    "r":"上海省",
                    "l":"province"
                },
                {
                    "v":"20130103",
                    "r":"20130103",
                    "l":"report_date"
                },
                {
                    "v":"-452.27",
                    "r":"-452.27",
                    "l":"profit_amt"
                }
            ]
        ],
        "sql":"SELECT * From TableA"   // 本次查询 SQL
    }
}

异常说明

流控限制

目前,数据服务 API 调用开启了流量控制策略,单个数据服务API的QPS最大为5;单个用户的所有API调用总QPS为50。如果流控超过阈值,返回的结果如下:
{
    "RequestId":"4DEA3AD2-ABE2-40BB-8918-B04A82302A32",   // 请求 ID
    "Code":"Throttling.User",                     // 错误码
    "Message":"Request was denied due to user flow control.",  // 错误原因
    "HostId":"quickbi-public.aliyuncs.com",
    "Recommend":"https://error-center.aliyun.com/status/search?Keyword=Throttling.User&source=PopGw"
}

其他异常

通过判断Success = true或者Code = "0"来判断请求是否成功。如果不是,通过Code和Message字段了解请求的错误原因。

Java SDK

具体源码请参见Java SDK

  • maven引入
    <!--引入QuickBI阿里云SDK-->
    <dependency>
      <groupId>com.aliyun</groupId>
      <artifactId>aliyun-java-sdk-quickbi-public</artifactId>
      <version>1.0.0</version>
    </dependency>
    
    <!--引入阿里云Core 包-->
    <dependency>
      <groupId>com.aliyun</groupId>
      <artifactId>aliyun-java-sdk-core</artifactId>
      <version>[4.3.2,5.0.0)</version>
    </dependency>
  • Java 示例
    IClientProfile profile = DefaultProfile.getProfile("null", "<客户阿里云AK>", "<客户阿里云SK>");
    DefaultProfile.addEndpoint("null", "quickbi-public", "quickbi-public.aliyuncs.com");
    DefaultAcsClient client = new DefaultAcsClient(profile);
    
    QueryDataServiceRequest request = new QueryDataServiceRequest();
    // 指定数据服务 API
    request.setServiceId("<数据服务的API ID>");
    
    // 构建返回字段
    List<String> returnFields = new LinkedList<String>();
    returnFields.addAll(Arrays.asList(new String[] {"province", "report_date", "profit_amt"}));
    
    // 构建入参查询参数
    Map<String, Object> conditions = new HashMap<String, Object>();
    conditions.put("report_date", "20191212");
    conditions.put("province", Arrays.asList(new String[] {"beijing", "shanghai"}));
    
    request.setReturnFields(JSONObject.toJSONString(returnFields));
    request.setConditions(JSONObject.toJSONString(conditions));
    
    // 执行查询。
    HttpResponse response = client.doAction(request);
    String result = new String(response.getHttpContent());