附录:API调用示例

API调用方式分为Java SDK调用(AK/SK)、Python SDK、API-TOKEN方式、白名单免密调用方式。其中白名单方式仅使用私有网关的时候支持。本篇API调用示例为调用模板,您可根据模板配置API的调用示例。

Java SDK调用方式

Java SDK简介

Dataphin服务Java SDK是根据您自定义的所有API接口,自动生成的Java调用代码,让您无需复杂编程即可访问Dataphin服务。这里向您介绍如何使用Dataphin服务SDK。

代码文件的层级结构如下:

Java SDK文件夹

  • sdk/

    • ClientDemo.java这里提供了统一的API调用示例和方法。

  • lib

    • sdk-core-java-1.1.0.jarSDK的core包,为本SDK的核心依赖包。

    • sdk-core-java-1.1.0-sources.jar上述依赖包的源码。

    • dataphin-sdk-core-java-v1.0.0.jarSDK的param包,为本SDK的构造请求参数的依赖包。

      Java SDK获取方式如下:

      1. 在Dataphin首页选择服务 > 服务管理

      2. 在左侧导航栏单击调用示例

      3. 单击API调用示例页签,单击页面右上方的Java SDK下载image按钮,将下载SDK的param包添加至pom.xml中。

    • dataphin-sdk-core-java-v1.0.0-sources.jar上述依赖包的源码。

    • fastjson-1.2.80_noneautotype.jar格式化JSON包。

  • ApiDocument.mdAPI接口文档。

  • Readme.md本SDK使用指南。

  • LICENSE版权许可。

Java SDK调用流程

重要
  • 您首先需要初始化客户端方可调用API。

  • CallApiDemo使用异步调用,同步参考ApiClient#getSync。

  • 您可以实例QueryParamRequest对象,并且设置请求参数满足不同的查询需要,详情请参考调用实例中的packRequestParam(QueryParamRequest queryParamRequest)方法。

  • API文档。API请求和返回结果信息请查看APIDocument.md。

  • 人工帮助。如果在使用中遇到棘手的问题,请加入我们官方用户支持群来找我们。

步骤一:环境准备

  1. Dataphin服务Java SDK适用于JDK 1.6及以上版本。

  2. 您需要准备一对授权密钥供SDK生成鉴权和签名信息,即 [AppKey和AppSecret]。

    重要

    AppKey和AppSecret是Dataphin服务认证用户请求的密钥,这两个配置如果保存在客户端,请妥善加密。

  3. 在pom.xml中添加如下依赖, 如果添加dataphin-sdk-core-java报错请手动添加该jar文件,路径sdk/lib/dataphin-sdk-core-java-v1.0.0.jar(即单击页面右上方的Java SDK下载image按钮,下载SDK的param包)。

    <dependency>
        <groupId>com.aliyun.api.gateway</groupId>
        <artifactId>sdk-core-java</artifactId>
        <version>1.1.0</version>
    </dependency>
    <dependency>
        <groupId>com.alibaba</groupId>
        <artifactId>fastjson</artifactId>
        <version>1.2.80_noneautotype</version>
    </dependency>
    <dependency>
        <groupId>com.alibaba.dt</groupId>
        <artifactId>dataphin-sdk-core-java</artifactId>
        <version>v1.1.0</version>
    </dependency>

步骤二:引入Java SDK的API接口调用类

  1. 在API市场下载对应的API文档。

  2. 导入CallApiDemo.java,修正CallApiDemo.java类的import、package。

    /*
     * Copyright 2018 Alibaba.com All right reserved. This software is the confidential and proprietary
     * information of Alibaba.com ("Confidential Information"). You shall not disclose such Confidential
     * Information and shall use it only in accordance with the terms of the license agreement you
     * entered into with Alibaba.com.
     */
    import java.util.ArrayList;
    import java.util.HashMap;
    import java.util.List;
    
    import com.alibaba.cloudapi.sdk.constant.SdkConstant;
    import com.alibaba.cloudapi.sdk.enums.Scheme;
    import com.alibaba.cloudapi.sdk.model.ApiResponse;
    import com.alibaba.dt.dataphin.client.ApiClient;
    import com.alibaba.dt.dataphin.client.ApiClientBuilderParams;
    import com.alibaba.dt.dataphin.schema.OrderBy;
    import com.alibaba.dt.dataphin.schema.QueryParamRequest;
    import com.alibaba.fastjson.JSONObject;
    
    import com.google.common.base.Splitter;
    import com.google.common.collect.Lists;
    import com.google.common.collect.Maps;
    
    import static com.alibaba.cloudapi.sdk.constant.SdkConstant.CLOUDAPI_LF;
    
    public class CallApiDemo {
        private static final String HOST = "dataphin-os-gateway.atest-hadoop.aliyun.com";
    
        private static final int CODE = 200;
    
        public static void main(String[] args) throws Exception {
            callApi();
        }
    
        @SuppressWarnings("all")
        private static void callApi() {
            String apiId = "10008";
            String apiType = "get";
            String appKey = "敏感数据自行填充";
            String appSecret = "敏感数据自行填充";
            String apiReturnFields = "ds2,sex,age,name2,id";
            String listType = "LIST";
    
            //创建请求参数 ---------------------------------------
            QueryParamRequest queryParamRequest = new QueryParamRequest();
            //构造请求参数对象
            //---条件参数
            //添加查询条件,其中key为对应的查询字段,value为查询字段对应的值, 例如这里的id为请求字段名,1为id对应的值,可以设置多个查询参数
            HashMap<String, Object> condition = Maps.newHashMap();
            //注意:如果是 IN 类型的参数,使用 list 包装参数值。
            queryParamRequest.setConditions(condition);
    
            //-- 排序(可选设置) 
            // 注意oracle和sqlServer使用分页需要同时使用排序
            // 排序字段,根据返回参数指定升序或者降序, 例如返回结果按id进行升序, 可设置多个字段进行升序或者降序
            // 使用分页则必须指定排序字段,并且要使用排序稳定的字段(例如主键、联合主键)保证每次排序结果相同,避免分页不准确
            ArrayList<OrderBy> orderList = Lists.newArrayList();
            //OrderBy.Order asc = OrderBy.Order.ASC;
            //OrderBy orderByColumn1 = new OrderBy("your order column", asc);
            //OrderBy orderByColumn2 = new OrderBy("your order column", asc);
            //orderList.add(orderByColumn1);
            //orderList.add(orderByColumn2);
            queryParamRequest.setOrderBys(orderList);
    
            //指定返回有权限的参数
            List<String> returnFiles = Lists.newArrayList(Splitter.on(",").split(apiReturnFields));
            queryParamRequest.setReturnFields(returnFiles);
    
            //进行分页(可选).不设置,默认取1~1000条数据
            queryParamRequest.setPageStart(1);
            queryParamRequest.setPageSize(10);
    
            // 是否缓存查询结果,开启则会缓存同一个API相同条件、想通返回字段的查询结果
            // 适用于数据不变化的查询
            // 缓存时长默认30分钟, 3.5.6 版本后,在开发API时可设置缓存时长
            queryParamRequest.setUseResultCache(true);
            queryParamRequest.setKeepColumnCase(true);
            //结束创建请求参数 ---------------------------------------
    
            ApiClient apiClient = createHttpClient(appKey, appSecret);
            try {
                ApiResponse response = listType.equalsIgnoreCase(apiType) ? apiClient.listSync(apiId, queryParamRequest)
                        : apiClient.getSync(apiId, queryParamRequest);
    
                String result = new String(response.getBody());
                String code = JSONObject.parseObject(result).get("code").toString();
                System.out.println(getResultString(response));
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
    
        private static ApiClient createHttpClient(String appKey, String appSecret) {
            ApiClientBuilderParams params = new ApiClientBuilderParams();
            params.setAppKey(appKey);
            params.setAppSecret(appSecret);
            params.setHost(HOST);
            //默认为http协议, 如果API 支持 HTTPS, 这里也可以设置HTTPS
            params.setScheme(Scheme.HTTP);
            params.setStage("RELEASE");
            params.setEnv("PROD");
            return new ApiClient(params);
        }
    
        private static String getResultString(ApiResponse response) {
            StringBuilder result = new StringBuilder();
            result.append("ResultCode:").append(CLOUDAPI_LF).append(response.getCode()).append(CLOUDAPI_LF);
            result.append("RequestId:").append(response.getHeaders().get("x-ca-request-id")).append(CLOUDAPI_LF);
            result.append("ErrorCode:").append(response.getHeaders().get("x-ca-error-code")).append(CLOUDAPI_LF);
            if(CODE != response.getCode()) {
                result.append("Error:").append(response.getHeaders().get("x-ca-error-message")).append(CLOUDAPI_LF);
            }
    
            result.append("ResultBody:").append(CLOUDAPI_LF).append(
                    new String(response.getBody(), SdkConstant.CLOUDAPI_ENCODING));
            return result.toString();
        }
    }

步骤三:准备您的AppKey,AppSecret进行填充

  1. 替换CallApiDemo里面对应的值。

  2. 执行main方法。

Python SDK调用流程

步骤一:环境准备

  1. Python SDK适用于Python3.9及以上版本。

    Python SDK获取方式如下:

    1. 在Dataphin首页选择服务 > 服务管理

    2. 在左侧导航栏单击调用示例

    3. 单击API调用示例页签,单击页面右上方的python调用示例下载image按钮,获取Python SDK core包。

  2. 您需要准备一对授权密钥供SDK生成鉴权和签名信息,即AppKey和AppSecret。

    重要

    AppKey和AppSecret是Dataphin服务认证用户请求的密钥,这两个配置如果保存在客户端,请妥善加密。

  3. 你需要准备一个JSON文件,格式如下:

     {
      "host": "e5c0fa75fdd74fea8e******.apigateway.res.aliyun.gdhchina.com", // 调用API的域名
      "port": 80,// 默认端口 80
      "impalaConfig": { // 调用impala需要配置值
          "pollingTimeout": 300, // impala轮询最长时间,5分钟,单位秒,可以不配置,默认5分钟
          "pollingInterval": 800 // impala轮询间隔,单位毫秒,可以不配置,默认800毫秒
      },
      "applicationConfig": { // 应用信息
          "appKey": "169683815******", // appKey 
          "appSecret": "0dbcd4b659d7489fbe44b7******" // app secret 
      },
      "apiConfig": { // api信息
          "apiNo": 10005,  // APIID
          "scheme": "HTTP", // API请求协议 HTTP 或 HTTPS
          "stage": "RELEASE", / / 固定值
          "env": "PROD", //固定值
          "method": "GET", // API的请求方式 GET 或 LIST
          "queryParamRequest": {
              "conditions":{"id":"1"} // api 请求参数和值
              "returnFields": [ // API返回参数集合
                  "real_qty" // 返回参数名称
              ],
              "pageStart": 0, // 分页码
              "pageSize": 10, // 每页数量
              "orderBys": [   // 排序参数设置
                  {"field":"字段名名称","order":"DESC"}
              ],
              "useModelCache": "false", // 查询参数是否缓存
              "useResultCache": "false", // 结果是否缓存 
              "keepColumnCase": "true" // 返回字段是小写,默认true
          }
      }
    }

步骤二:部署Python SDK

  1. 安装Python开发工具pycharm。

  2. 打开Python项目。

  3. 在Demo类的启动参数上配置JSON文件路径。

  4. 具体调用请参照demo.py。

    # -*- coding: utf-8 -*-
    import dataapi
    import sys
    
    print('参数列表:', str(sys.argv))
    
    with open(str(sys.argv[1]), encoding="utf-8") as f:
        json_obj = eval(f.read().replace('\n\u200b', ''))
    # 这里是读取上下文的json文件,假如不需要json文件的话,直接填写对应值的就好了
    
    # 网关调用地址
    host = json_obj["host"]
    # 网关调用端口
    port = json_obj["port"]
    # 可不配置。只对impala类型的API有效,轮询超时时间
    pollingTimeout = json_obj["impalaConfig"]["pollingTimeout"]
    # 可不配置。只对impala类型的API有效,轮询间隔
    pollingInterval = json_obj["impalaConfig"]["pollingInterval"]
    # app的信息,你用哪个APP来调用这个API
    appKey = json_obj["applicationConfig"]["appKey"]
    appSecret = json_obj["applicationConfig"]["appSecret"]
    # api的信息
    apiId = json_obj["apiConfig"]["apiNo"]
    # 用什么方式调用API? 值是:HTTP 或 HTTPS。注意私有网关只支持HTTP   【区分大小写】
    scheme = json_obj["apiConfig"]["scheme"]
    # 写死RELEASE即可
    stage = json_obj["apiConfig"]["stage"]
    # 有 PROD 和 PRE 两种值 (如果是basic模式,传死PROD; 如果是Dev-Prod模式,PROD表示查生产库,PRE表示查开发库   【区分大小写】
    env = json_obj["apiConfig"]["env"]
    # 请求参数,必填
    queryParam = json_obj["apiConfig"]["queryParamRequest"]
    
    # API是 GET 还是 LIST?  【区分大小写】
    method = json_obj["apiConfig"]["method"]
    
    if (host == None or host == ""):
        raise Exception("host信息缺失")
    
    if (appKey == None or appKey == ""):
        raise Exception("appKey信息缺失")
    
    if (appSecret == None or appSecret == ""):
        raise Exception("appSecret信息缺失")
    
    if (method == None or method == ""):
        raise Exception("method信息缺失")
    
    if (method == None or method == ""):
        raise Exception("method信息缺失")
    
    if (apiId == None or apiId == ""):
        raise Exception("apiNo信息缺失")
    
    # 配置impalat
    impalaConfig = dataapi.ImpalaConfig(pollingTimeout=pollingTimeout, pollingInterval=pollingInterval)
    # 配置app
    appConfig = dataapi.AppConfig(appKey=appKey, appSecret=appSecret)
    apiConfig = dataapi.ApiConfig(apiId, scheme, stage, env, queryParam, method)
    myConfig = dataapi.MyConfig(host, port, impalaConfig, appConfig, apiConfig)
    
    apiClient = dataapi.ApiClient(myConfig)
    apiClient.callApi(queryParam)

步骤三:调用API

  1. 在JSON文件中配置调用参数信息。

  2. Python SDK通过读取JSON文件来组装API调用的基础参数。

  3. 调用datapi.callApi方法,具体参照demo.py。

TOKEN调用方式

API签名的方法对报文进行签名,目前只支持已经发布到生产环境的API进行调用。

总体流程:生成签名->封装请求->发起请求->接口响应。

1.API协议须知

支持的协议有HTTP、HTTPS(如果需要使用HTTPS协议需要完成独立域名的绑定并上传SSL证书)。

调用地址(host)

server-host:用于调用Dataphin服务端接口,host分为二级域名和独立域名,二级域名为Dataphin配置,用户不可更改;独立域名为用户自行绑定(独立域名必须先在阿里云上备案),二级域名和独立域名都可用于API的调用,域名查看位置如下所示:Dataphin数据服务->服务->平台管理->网络配置

请求类型

POST

只支持POST提交的请求,BODY一律使用JSON字符串。

公共入参

参数名

位置

是否必填

示例

说明

x-ca-timestamp

Header

1575363974058

API调用者传递时间戳(与date相对应,15分钟内有效,取当前调用API的时间)。

x-ca-nonce

Header

1f4e0103-08de-4b8a-bf47-46d6d5460722

API每次请求的唯一标识符(15分钟不可重复,使用UUID生成即可,每次调用API生成一个新的nonce)。

date

Header

Tue Dec 03 17:06:14 CST 2019

时间戳对应的日期(15分钟内有效,取当前调用API的时间)。

content-md5

Header

IbabPuoaJ//QVeI62Hc3Tg==

Body的MD5值。

x-ca-signature

Header

cUh2QxTNb4s/zmGMDzmbfMSi8kd8W/caLXXyUhDv88g=

通过签名计算规则计算的请求签名串。

accept

Header

application/json; charset=utf-8

响应格式。

x-ca-key

Header

2037**895

appkey,调用API的身份标识。

host

Header

7229fc4974**-cn-shanghai.alicloudapi.com

访问域名。

x-ca-stage

Header

RELEASE

生产环境标识。

x-ca-signature-headers

Header

x-ca-nonce,x-ca-timestamp,x-ca-key,x-ca-signature-method,x-ca-stage

指定哪些Header参与签名(目前固定这些参数)。

Content-Type

Header

application/octet-stream; charset=utf-8

请求格式。

x-ca-signature-method

Header

HmacSHA256

签名算法。

user-agent

Header

ALIYUN-ANDROID-DEMO

请求标识(预留参数,目前不参数签名)。

ca_version

Header

1

版本(预留参数,目前不参数签名)。

请求格式

  • 请求格式:POST [host]/请求方式/API_ID?appKey=应用的AppKey&env=PROD。

  • 请求方式取值:get或者list,API_ID为API的唯一标识,请求方式和API_ID可在调用->服务调用->已授权API服务->API调试页面获取。appKey为该API绑定的应用的唯一标识,可在调用->应用管理页面获取,env=PROD表示生产环境上的API。请求URL格式为:host/list/10209?appKey=203763395&env=PROD

2.生成签名

请求签名,是基于请求内容计算的数字签名,用于API识别用户身份。客户端调用API时,需要在请求中添加计算的签名(X-Ca-Signature)。

步骤一:构造待签名字符串stringToSign签名。

Headers为1.2.2公共入参中x-ca-signature-headers指定的参数。

HTTPMethod固定为POST,API只支持POST请求。格式如下:

String stringToSign=
HTTPMethod + "\n" +
Accept + "\n" +
Content-MD5 + "\n"
Content-Type + "\n" +
Date + "\n" +
Headers + "\n" +
Url

stringToSign中的每个值都还需要加换行符, 示例如下:

String stringToSign=
POST
application/json; charset=utf-8
v+x4pvIfqCrltJOluXqJTQ==
application/octet-stream; charset=utf-8
Wed, 15 Apr 2020 11:09:01 GMT
x-ca-key:222
x-ca-nonce:aaa2b0c7-527a-4963-b36e-a187b62b6fad
x-ca-signature-method:HmacSHA256
x-ca-stage:RELEASE
x-ca-timestamp:1586948941999
/list/10870?appKey=222&env=PROD

Content-MD5是指Body的MD5值

计算方式为:String content_MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));

说明
  • bodyStream为字节数组。

  • 正常情况下,base64的结果为24位,因与服务器有约定,在超过24位的情况下,截取前24位。

以Java代码为示例计算Content-MD5:

 // bodyJsonString为请求body的json字符串
  String bodyJsonString = "{\"accountCode\":\"111111\"}";
  byte[] bytes = bodyJsonString.getBytes();
  final MessageDigest md = MessageDigest.getInstance("MD5");
  md.reset();
  md.update(bytes);
  byte[]md5Result = md.digest();
  String base64Result = Base64.encodeBase64String(md5Result);
  /* * 正常情况下, base64的结果为24位,因与服务器有约定,在超过24位的情况下,截取前24位 */
  return base64Result.length() > 24 ? base64Result.substring(0, 23) : base64Result;

Headers

  • Headers是指参与Headers签名计算的Header的Key、Value拼接的字符串,建议对X-Ca开头以及自定义Header计算签名。

    说明

    参数X-Ca-Signature、X-Ca-Signature-Headers、Accept、Content-MD5、Content-Type、Date不参与Headers签名计算。

  • Headers组织方法:对参与Headers签名计算的Header的Key按照字典排序后使用如下方式拼接,如果某个Header的Value为空,则使用HeaderKey+ “:” + “\n”参与签名,需要保留 Key 和英文冒号。示例如下:

    String headers =
    HeaderKey1 + ":" + HeaderValue1 + "\n"\+
    HeaderKey2 + ":" + HeaderValue2 + "\n"\+
    ...
    HeaderKeyN + ":" + HeaderValueN + "\n"
  • 将Headers签名中Header的Key使用英文逗号分割放到Request的Header中,Key为:X-Ca-Signature-Headers

Url

Url格式为:/请求方式(get或list)/API_ID?appKey=应用的AppKey&env=PROD。

步骤二:使用appSecret计算签名获得x-ca-signature。

说明

AppSecret为APP的密钥,请在应用中获取。

脚本格式如下:

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] keyBytes = appSecret.getBytes("UTF-8");
hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
String sign = new String(Base64.encodeBase64(Sha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));

Java代码示例如下:

Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] keyBytes = secretKey.getBytes(SdkConstant.CLOUDAPI_ENCODING);
hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
byte[] md5Result = hmacSha256.doFinal(strToSign.getBytes(SdkConstant.CLOUDAPI_ENCODING));
return String x_ca_signature = Base64.encodeBase64String(md5Result);
return  x_ca_signature;

使用PostMan调用示例

步骤一:请求地址

POST请求地址为:host/list/100236?appKey=203760895&env=PROD。您可参考来编辑地址。

步骤二:填入签名计算值到Header中

Header示例如下,您可参考填写。

x-ca-nonce:1f4e0103-08de-4b8a-bf47-46d6d5460722
date:TueDec0317:06:14CST2019
content-md5:IbabPuoaJ//QVeI62Hc3Tg==
x-ca-signature:cUh2QxTNb4s/zmGMDzmbfMSi8kd8W/caLXXyUhDv88g=
accept:application/json;charset=utf-8
x-ca-key:203760895
host:7229fc49743a4654b62de0756d7554ac-cn-shanghai.alicloudapi.com
x-ca-stage:RELEASE
x-ca-signature-headers:x-ca-nonce,x-ca-timestamp,x-ca-key,x-ca-signature-method,x-ca-stage
Content-Type:application/octet-stream;charset=utf-8
x-ca-signature-method:HmacSHA256
//user-agent:ALIYUN-ANDROID-DEMO
//ca_version:1

步骤三:填入body

说明
  • Content-Type使用application/octet-stream; charset=utf-8。

  • 在PostMan请求示例中Header和body参数可根据已经提供Java语言的SDK直接生成并填入后发起API请求,如果使用的不是Java语言调用API,开发者可参照Java语言的SDK生成签名和Body方式或者TOKEN的方式生成自己需要的开发语言的签名,并填入Header和Body中完成API的调用。

body示例如下:

{"conditions":{"id":1},"orderBys":[],"returnFields":["name"],"useModelCache":false,"useResultCa
che":false}

白名单调用方式(仅私有化部署时支持)

通过配置白名单免密方式访问API的安全策略,可简化API调用流程。IP白名单策略为应用级别策略,目前仅私有云支持此方式调用。

开发流程

步骤一:后台配置

进入Dataphin后台,创建API->创建应用->创建应用白名单->应用和API绑定

步骤二:发起请求

  1. 请求类型:POST

    只支持POST提交的请求,BODY一律使用JSON字符串,并且Content-Type设置为application/octet-stream; charset=utf-8。

  2. 设置公共入参

    参数名

    位置

    是否必填

    示例

    说明

    accept

    Header

    application/json; charset=utf-8

    响应格式。

    x-ca-key

    Header

    2037**895

    appkey,调用API的身份标识。

    host

    Header

    7229fc4974**

    -cn-shanghai.alicloudapi.com。

    x-ca-stage

    Header

    RELEASE

    环境标识,RELEASE访问生产环境、PRE访问开发环境。

    Content-Type

    Header

    application/octet-stream; charset=utf-8

    请求格式。

    user-agent

    Header

    ALIYUN-ANDROID-DEMO

    请求标识(预留参数)。

    ca_version

    Header

    1

    版本(预留参数)。

    whitelist-flag

    Header

    1

    白名单标识(非空)。

    conditions

    Body

    {"id":1}

    API请求入参。

    orderBys

    Body

    [{"field":"id", "order":"DESC"}, {"field":"name", "order":"ASC"}]

    排序规则。不需要排序的时候传[]。

    returnFields

    Body

    ["id","name"]

    返回字段。

    useModelCache

    Body

    false

    是否缓存API的查询条件参数生成的查询模型。

    useResultCache

    Body

    false

    是否缓存API的查询返回的结果。

    pageStart

    Body

    0

    开始下标。可选,只有LIST类型的API才用。

    pageSize

    Body

    10

    取多少条。可选,只有LIST类型的API才用。

  3. 请求格式

    • 请求格式为:POST [host]/请求方式/APIID?appKey=应用的AppKey&env=PROD

    • 请求方式取值:get或者list,APIID为API的唯一标识,请求方式和API_ID可在调用->服务调用->已授权API服务->API调试页面获取。appKey为该API绑定的应用的唯一标识,可在调用->服务调用->已授权API服务->API调试页面获取,env=PROD表示生产环境上的API,env=PRE表示开发环境的API。

      请求URL格式如下:host/list/10209?appKey=203763395&env=PROD

  4. 使用PostMan调用示例

    1. 步骤一:请求地址

      请求POST地址host/list/100236?appKey=203760895&env=PROD

    2. 步骤二:填入Header

      填入Header,可参考填写。

      Header示例如下:

      accept:application/json;charset=utf-8
      x-ca-key:203760895
      host:7229fc49743a4654b62de0756d7554ac-cn-shanghai.alicloudapi.com
      x-ca-stage:RELEASE
      Content-Type:application/octet-stream;charset=utf-8
      whitelist-flag:1
      ApiId:10209
      //user-agent:ALIYUN-ANDROID-DEMO
      //ca_version:1
    3. 步骤三:填入body

      说明

      Content-Type使用application/octet-stream; charset=utf-8。

      body示例:

      {"conditions":{"id":1},"orderBys":[],"returnFields":["name"],"useModelCache":false,"useResultCa
      che":false}

错误排查和错误码表

如何获取公共错误

所有的API请求只要请求参数和URL无误,就会返回请求结果信息。

  • 用户需要查看返回结果的头部,即Header部分。返回参数如示例:

    X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF
  • 请求唯一ID,请求一旦进入Dataphin服务应用后,Dataphin服务就会生成请求ID并通过响应头返回给客户端,建议客户端与后端服务都记录此请求ID,可用于问题排查与跟踪。

  • Dataphin服务返回的错误消息,当请求出现错误时Dataphin服务会通过响应头将错误消息返回给客户端。

    X-Ca-Error-Message: Invalid Url
  • 当打开Debug模式后会返回Debug信息,此信息后期可能会有变更,仅用做联调阶段参考。

    X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}

    在Header中获得X-Ca-Error-Message可以基本明确报错原因,而X-Ca-Request-Id可以用于提供给这边的支持人员,供支持人员搜索日志。

公共错误码

客户端错误

错误代码

HTTP状态码

语义

解决方案

Throttled by APP Flow Control

403

因APP流控被限制

调用频率过高导致被流控,可以联系服务提供方放宽限制。

Throttled by API Flow Control

403

因API流控被限制

调用频率过高导致被流控,可以联系服务提供方放宽限制。

Throttled by DOMAIN Flow Control

403

因二级域名流控被限制

直接访问二级域名调用API,每天被访问次数上限1000次。

TThrottled by GROUP Flow Control

403

因分组流控被限制

调用频率过高导致被流控,可以联系服务提供方放宽限制。

Empty Request Body

400

body为空

请检查请求Body内容。

Invalid Request Body

400

body无效

请检查请求Body。

Invalid Param Location

400

参数位置错误

请求参数位置错误。

Invalid Url

400

Url无效

请求的 Method、Path或者环境不对。请参照错误说明Invalid Url。

Invalid Domain

400

域名无效

请求域名无效,根据域名找不到 API。请联系 Dataphin服务。

Invalid HttpMethod

400

HttpMethod无效

输入的Method不合法。

Invalid AppKey

400

AppKey无效或不存在

请检查传入的AppKey。注意左右空格的影响。

Invalid AppSecret

400

APP 的Secret错误

检查传入的AppSecret。注意左右空格的影响。

Timestamp Expired

400

时间戳过时

请核对请求系统时间是否为标准时间。

Invalid Timestamp

400

时间戳不合法

请参照请求签名说明文档。

Empty Signature

404

签名为空

请传入签名字符串,请参照请求签名说明文档。

Invalid Signature, Server StringToSign:%s

400

签名无效

签名无效,参照Invalid Signature错误说明

Invalid Content-MD5

400

Content-MD5值不合法

请求Body为空,但传入了MD5值,或MD5值计算错误。请参照请求签名说明文档。

Unauthorized

403

未被授权

APP未获得要调用的API的授权。请参照错误说明Unauthorized。

Nonce Used

400

SignatureNonce已被使用

x-ca-nonce不能被重复使用,从新生成x-ca-nonce

API Not Found

400

找不到API

传入的API请求地址或HttpMethod不正确,或已下线。

服务器端错误(调用 API)

以下为API服务端错误。

错误代码

HTTP状态码

语义

解决方案

Internal Error

500

内部错误

建议重试

Failed To Invoke Backend Service

500

底层服务错误

API底层服务错误,建议重试

Service Unavailable

503

服务不可用

建议重试

Async Service

504

服务超时

建议重试

服务器端错误(执行SQL语句)

代码

OS状态码

语义

DPN-OLTP-COMMON-000

Success

成功

DPN-OLTP-COMMON-001

Internal Error:{0}

系统发生未知异常

DPN-OLTP-COMMON-002

Parameter error

参数异常

DPN-OLTP-COMMON-003

Not support: {0}

系统发生未知异常

DPN-OLTP-COMMON-004

Sql AST Parser Exception:{0}

SQL解析异常

DPN-OLTP-ENGINE-001

Param Error : {0}.

参数错误

DPN-OLTP-ENGINE-002

{0} Not Found.

对象找不到

DPN-OLTP-ENGINE-003

{0} Not Support.

不支持

DPN-OLTP-ENGINE-004

Communication Table Error : {0}.

通信表错误

DPN-OLTP-ENGINE-005

Sql Parser Error: {0}.

SQL解析失败

DPN-OLTP-ENGINE-006

Meta Error: {0}.

元数据错误

DPN-OLTP-ENGINE-007

Param Handling Error: {0}.

参数处理错误

DPN-OLTP-ENGINE-008

Build Execute Model Error: {0}.

构建执行模型错误

DPN-OLTP-ENGINE-009

Execute Error: {0}.

执行失败

DPN-OLTP-ENGINE-010

DataSource Error: {0}.

数据源错误

DPN-OLTP-ENGINE-011

HBase DataSource Not Support: {0}.

HBase引擎不支持

DPN-OLTP-ENGINE-012

Object Serialize Error:{0}

对象序列化失败

DPN-OLTP-ENGINE-013

Columns Auth Check Failed: {0}

权限校验失败

DPN-OLTP-ENGINE-014

ElasticSearch DataSource Not Support: {0}.

ES引擎不支持

DPN-OLTP-ENGINE-015

MongoDB DataSource Not Support: {0}.

MongoDB引擎不支持

DPN-OLTP-ENGINE-016

Column {0} Codec Error : {1}

字段类型错误

DPN-OLTP-ENGINE-017

Redis Cache Failed : {0}

Redis缓存异常

DPN-OLTP-ENGINE-018

Multiple Physical Tables Not Support: {0}.

跨数据源不支持

DPN-OLTP-ENGINE-019

Data Value {0} Codec Error : {1}

数据类型编码或者转换失败

DPN-OLTP-ENGINE-20

Circuit breaker error: {0}.

熔断

DPN-OLTP-ENGINE-21

Rate Limit error: {0}.

限流

DPN-OLTP-ENGINE-018-01

Not support group by

跨数据源不支持group by

DPN-OLTP-ENGINE-018-02

Not support order by

跨数据源不支持order by

DPN-OLTP-ENGINE-018-03

Not support without where condition

跨数据源不支持没有 where条件

DPN-OLTP-ENGINE-018-04

Not support page start not 0

跨数据源不支持page start不等于0

DPN-OLTP-ENGINE-018-05

Not support 'or' operation in where

跨数据源不支持在where条件中存在or操作

DPN-OLTP-ENGINE-018-06

Not support a select item

跨数据源不支持在一个 select item中有来自多个物理表的字段

DPN-OLTP-ENGINE-018-07

All primary key must in where

跨数据源查询必须所有的主键都在

DPN-OLTP-JDBC-001

Session missing in request header.

Request Head miss session

DPN-OLTP-JDBC-002

Session id and account id not match, accountId:{0}, sessionId:{1}.

Session id和account id not match

DPN-OLTP-JDBC-003

Database forbidden, accountId:{0}, database:{1}.

用户无权访问数据库

DPN-OLTP-JDBC-004

Table forbidden, accountId:{0}, sql:{1}.

用户无权访问数据表

DPN-OLTP-JDBC-005

AccountId not found, accountId:{0}

account id出错

DPN-OLTP-OLAP-001

Olap client error : {0}.

Olap客户端失败

DPN-OLTP-JDBC-002

Olap task run error : {0}.

Olap客户端运行失败

常见问题

问题:调用API报404 回答

  • 如果绑定了独立域名,请检查是HTTP协议还是HTTPS协议。

  • 检查调用的API创建的类型是list还是get,因为list/get会作为URL的一部分。

  • 检查API是否发布到对应的环境。

问题:调用API报400 回答

  • 请检查x-ca-timestamp是否在15分钟的有效期内,x-ca-nonce在15分钟内是否被重复使用,建议每次请求API,x-ca-timestamp取当前时间,x-ca-nonce新生成可以用UUID生成,唯一标识,没有格式要求。

  • 检查使用AppKey、AppSecret是否前后有空格。

  • 注意检查自己客户端的签名值是否多加了空格,传给服务端的没有加(Invalid Signature),检查stringToSign中的值是否有空格,如客户端签名Content-Type:application/octet-stream; charset=utf-8有空格,但是传给服务端的没有空格Content-Type:application/octet-stream;charset=utf-8,就会报错Invalid Signature