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下載按鈕，將下載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及以上版本。

   Python SDK獲取方式如下：

   1. 在Dataphin首頁選擇服務 > 服務管理。

   2. 在左側導航欄單擊調用示例。

   3. 單擊API調用示例頁簽，單擊頁面右上方的python調用示例下載按鈕，獲取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字符串。

公共入參

請求格式

• 請求格式：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。