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.jar
SDK的core包,为本SDK的核心依赖包。sdk-core-java-1.1.0-sources.jar
上述依赖包的源码。dataphin-sdk-core-java-v1.0.0.jar
SDK的param包,为本SDK的构造请求参数的依赖包。Java SDK获取方式如下:
在Dataphin首页选择服务 > 服务管理。
在左侧导航栏单击调用示例。
单击API调用示例页签,单击页面右上方的Java SDK下载按钮,将下载SDK的param包添加至pom.xml中。
dataphin-sdk-core-java-v1.0.0-sources.jar
上述依赖包的源码。fastjson-1.2.80_noneautotype.jar
格式化JSON包。
ApiDocument.md
API接口文档。Readme.md
本SDK使用指南。LICENSE
版权许可。
Java SDK调用流程
您首先需要初始化客户端方可调用API。
CallApiDemo使用异步调用,同步参考ApiClient#getSync。
您可以实例QueryParamRequest对象,并且设置请求参数满足不同的查询需要,详情请参考调用实例中的packRequestParam(QueryParamRequest queryParamRequest)方法。
API文档。API请求和返回结果信息请查看APIDocument.md。
人工帮助。如果在使用中遇到棘手的问题,请加入我们官方用户支持群来找我们。
步骤一:环境准备
Dataphin服务Java SDK适用于JDK 1.6及以上版本。
您需要准备一对授权密钥供SDK生成鉴权和签名信息,即 [AppKey和AppSecret]。
重要AppKey和AppSecret是Dataphin服务认证用户请求的密钥,这两个配置如果保存在客户端,请妥善加密。
在pom.xml中添加如下依赖, 如果添加
dataphin-sdk-core-java
报错请手动添加该jar文件,路径sdk/lib/dataphin-sdk-core-java-v1.0.0.jar
(即单击页面右上方的Java SDK下载按钮,下载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接口调用类
在API市场下载对应的API文档。
导入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进行填充
替换CallApiDemo里面对应的值。
执行main方法。
Python SDK调用流程
步骤一:环境准备
Python SDK适用于Python3.9及以上版本。
Python SDK获取方式如下:
在Dataphin首页选择服务 > 服务管理。
在左侧导航栏单击调用示例。
单击API调用示例页签,单击页面右上方的python调用示例下载按钮,获取Python SDK core包。
您需要准备一对授权密钥供SDK生成鉴权和签名信息,即AppKey和AppSecret。
重要AppKey和AppSecret是Dataphin服务认证用户请求的密钥,这两个配置如果保存在客户端,请妥善加密。
你需要准备一个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
安装Python开发工具pycharm。
打开Python项目。
在Demo类的启动参数上配置JSON文件路径。
具体调用请参照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
在JSON文件中配置调用参数信息。
Python SDK通过读取JSON文件来组装API调用的基础参数。
调用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绑定。
步骤二:发起请求
请求类型:POST
只支持POST提交的请求,BODY一律使用JSON字符串,并且Content-Type设置为application/octet-stream; charset=utf-8。
设置公共入参
参数名
位置
是否必填
示例
说明
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才用。
请求格式
请求格式为: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
。
使用PostMan调用示例
步骤一:请求地址
请求POST地址
host/list/100236?appKey=203760895&env=PROD
。步骤二:填入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
步骤三:填入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
。