附录：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下载按钮，将下载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调用流程

步骤一：环境准备

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下载按钮，下载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及以上版本。

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字符串。

公共入参

请求格式

• 请求格式：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")));

以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。

脚本格式如下：

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

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可以用于提供给这边的支持人员，供支持人员搜索日志。

公共错误码

客户端错误

服务器端错误（调用 API）

以下为API服务端错误。

服务器端错误（执行SQL语句）

常见问题

问题：调用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。