附录：API调用示例

SDK调用

Java SDK简介

Dataphin数据服务Java SDK为您提供了快速调用数据服务API的基础SDK及示例调用代码。这里向您介绍如何使用Dataphin服务Java SDK。

Java SDK的代码文件层级结构如下：

Java SDK文件夹

• demo/

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

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

• lib/

  • dataphin-sdk-core-java-v5.0.0.jar本SDK的核心依赖包。

  • dataphin-sdk-core-java-v5.0.0-javadoc.jar上述依赖包的Javadoc。

  • dataphin-sdk-core-java-v5.0.0-jar-with-dependencies.jar上述依赖包的全依赖包。

• ApiDocument_v5.0.0.mdAPI接口文档。

• LICENSE许可证。

Java SDK获取方式如下：

1. 在Dataphin首页的顶部菜单栏，选择服务 > 调用。

2. 在左侧导航栏单击调用说明。

3. 单击API调用说明页签，在页面右上方选择Java SDK下载，将下载SDK的Jar包添加至pom.xml中。

Java SDK调用同步API流程

步骤一：环境准备

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

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

   AppKey和AppSecret可在服务 > 调用 > 应用管理列表中获取。

   重要

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

3. 在pom.xml中添加如下依赖，如果添加dataphin-sdk-core-java报错请手动添加该jar文件，路径JAVA_SDK/lib/dataphin-sdk-core-java-v5.0.0.jar（即所获取Java SDK中的Jar包）。

   说明

   dataphin-sdk-core-java并不存在于中央Maven仓库，因此下载该SDK后还需要您上传至贵公司的Maven仓库，或者在IDEA、Eclipse中手动引入。

   <dependency>
       <groupId>com.alibaba.dt</groupId>
       <artifactId>dataphin-sdk-core-java</artifactId>
       <version>v5.0.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();
       }
   }

步骤三：初始化通信通道类

要调用API，首先要初始化客户端。您可以参考ClientDemo.java中的示例代码，使用对应的ApiClientBuilderParams类来进行初始化。其中，需把域名、AccessKey和AccessSecret三个变量替换为用户的真实数据。

//初始化客户端
ApiClientBuilderParams params = new ApiClientBuilderParams();
params.setAppKey(APP_KEY);
params.setAppSecret(APP_SECRET);
//访问服务的域名
params.setHost(HOST);
// 默认使用HTTP协议,可自行设置HTTPS协议
// params.setScheme(Scheme.HTTPS);
this.apiClient = new ApiClient(params);

步骤四：API接口说明

• API接口类型

  API接口类型分为LIST和GET，LIST支持分页查询而GET不支持，请参考ClientDemo.java中的示例，设置QueryParamRequest中pageStart和pageSize的参数进行分页查询。

• 调用API接口

  • SDK中的LIST和GET方法为Dataphin数据服务的通用方法，SDK中提供同步调用方法。在调用API之前，您需要根据您在Dataphin数据服务中定义的API填入相关的请求参数。

  • 调试用例中condition为业务请求参数，returnFiles为API的返回参数，具体参数请参考服务 > 调用 > 已授权API服务页面，单击目标API操作列下调试，进入调试页面。

  • 请求参数中的API_ID，请参考服务 > 调用 > 已授权API服务页面API列下的API_ID。

以下为LIST类型API的调用示例：

//异步调用示例
     public void listAsyn(String apiId,  QueryParamRequest queryParamRequest){
        //填充请求参数
        packRequestParam(queryParamRequest);
        //进行分页
        queryParamRequest.setPageStart(1);
        queryParamRequest.setPageSize(10);
        apiClient.listAsync(apiId, queryParamRequest , new ApiCallback() {
            @Override
            public void onFailure(ApiRequest request, Exception e) {
                e.printStackTrace();
            }

            @Override
            public void onResponse(ApiRequest request, ApiResponse response) {
                try {
                    System.out.println(getResultString(response));
                }catch (Exception ex){
                    ex.printStackTrace();
                }
            }
        });
    }

//同步调用示例
    public void listSync(String apiId, QueryParamRequest queryParamRequest){
        //填充请求参数
        packRequestParam(queryParamRequest);
        //进行分页
        queryParamRequest.setPageStart(1);
        queryParamRequest.setPageSize(10);
        ApiResponse response = apiClient.listSync(apiId, queryParamRequest);
        try {
            System.out.println(getResultString(response));
        }catch (Exception ex){
            ex.printStackTrace();
        }
    }

//填充请求参数
    private static void packRequestParam(QueryParamRequest queryParamRequest){
        //添加查询条件,其中key为对应的查询字段,value为查询字段对应的值, 例如这里的id为请求字段名,1为id对应的值,可以设置多个查询参数
        HashMap<String, Object> condition = Maps.newHashMap();
        condition.put("id",1);
        queryParamRequest.setConditions(condition);
        //排序字段,根据返回参数指定升序或者降序, 例如返回结果按id进行升序, 可设置多个字段进行升序或者降序
        ArrayList<OrderBy> orderList = Lists.newArrayList();
        OrderBy.Order asc = OrderBy.Order.ASC;
        OrderBy orderBy = new OrderBy("id", asc);
        orderList.add(orderBy);
        queryParamRequest.setOrderBys(orderList);
        //指定返回参数, 例如指定返回id和name
        ArrayList<String> returnFiles = Lists.newArrayList("id", "name");
        queryParamRequest.setReturnFields(returnFiles);
        //是否使用缓存,建议设置为true使用缓存, 提高查询效率
        queryParamRequest.setUseModelCache(Boolean.getBoolean("false"));
        queryParamRequest.setUseResultCache(Boolean.getBoolean("true"));

    }

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":"dataphin-os-gateway.dev01.aliyun.com",
     "port":80,
     "impalaConfig": {
         "pollingTimeout": 300,
         "pollingInterval":800,
     },
     "applicationConfig": {
         "appKey": "200000005",
         "appSecret": "846792709c2c4dfc85d166537dbdb492"
     },
     "apiConfig": {
         "apiNo": 10013,
         "scheme": "HTTP",
         "stage": "RELEASE",
         "env": "PROD",
         "method":"GET",
         "queryParamRequest": {
             "returnFields": ["retailer_code","qty_order","cig_bar_code","org_code","sale_reg_code","order_date"],
             "pageStart": 0, 
             "pageSize":10,
             "orderBys": [],
             "useModelCache": "false",
             "useResultCache": "false" 
         }
     }
   }

步骤二：部署Python SDK

1. 安装Python开发工具PyCharm。

2. 打开Python项目。

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

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

步骤三：调用API

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

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

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

   # -*- coding: utf-8 -*-
   import json
   
   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)
   
   # 同步API请求
   resp = apiClient.callApi(queryParam)
   print(resp)
   
   # 异步API请求
   asyncResp = apiClient.asyncCallApi(queryParam)
   print(asyncResp)

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

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

开发流程

步骤一：后台配置

您需要在数据服务中创建API、应用、应用白名单以及将应用和API进行绑定，才能通过白名单方式访问API。

• 创建API：您可在服务 > 开发 > API页面，选择通过直连数据源模式、逻辑表API-SQL模式、逻辑表API-向导模式、注册API和组合API五种方式创建API，如何创建，请参见创建API。

• 创建应用及应用白名单：应用可用于调用生产环境的API，并可为API设置白名单，如何创建应用及白名单，请参见新建及管理服务应用。

• 应用和API绑定：需申请该API的所属应用权限才能使用该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	白名单标识（非空）。

3. 请求格式

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

   • 请求方式取值：get或者list，API_ID为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,
        "useResultCache":false
      }

错误码

客户端错误

服务器端错误（调用 API）

以下为API服务端错误。

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

常见问题

问题：调用API报404 回答：

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

• 检查调用的API创建的类型是LIST还是GET，因为LIST/GET会作为URL的一部分。

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

   public static ApiClient getClient() {
        if (apiClient == null) {
            synchronized (ClientDemo.class) {
                if (apiClient == null) {
                    ...
                    params.setStage("RELEASE");
                    params.setEnv("PROD");
                    apiClient = new ApiClient(params);
                    return apiClient;
                }
            }
   }

问题：调用API报400 回答：

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

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

• 检查调用的API是否已授权，并且授权的APPSecret和AppKey是否和下面参数private static final String APP_KEY和private static final String APP_SECRET一致，不一致情况下出现400错误。

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

问题：调用API报403

回答：可能的原因：①调用协议与实际配置不匹配，②AppKey和AppSecret不正确。

• 检查API配置的调用协议是HTTP还是HTTPS，在代码中设置为对应的参数。

   public static ApiClient getClient() {
        if (apiClient == null) {
            synchronized (ClientDemo.class) {
                if (apiClient == null) {
                    ... 
                    //默认为http协议, 可设置https协议(os网关不支持https!!，非os网关可以支持https，具体决定于所调用的API）
                    // 这里
                    params.setScheme(Scheme.HTTP);
                      // 或
                    params.setScheme(Scheme.HTTPS);
                    ...
                }
            }
        }
        return apiClient;
    }

• 检查AppKey和AppSecret是否正确。

问题：调用API报错：return fields missing in param

回答：在packRequestParamListSync或packRequestParamGetSync（根据API的GET或LIST类型）方法中，按照下方脚本设置参数。

ArrayList<String> returnFiles = Lists.newArrayList("api的返回字段1","api的返回字段2",..."api的返回字段n");
queryParamRequest.setReturnFields(returnFiles);

问题：如何使用operator为IN的参数

回答：在SDK调用时，IN类型的参数需要使用LIST传递参数值，例如：

• 假设参数名为p1，参数类型为String或Date，参数值为a、b、c，则应按下面方式设置参数：

HashMap<String, Object> condition = Maps.newHashMap();
condition.put("p1",Lists.newArrayList("a", "b", "c"));

• 如果是数值类型，参数值为1、2、3，则应按下面方式设置参数：

HashMap<String, Object> condition = Maps.newHashMap();
condition.put("p1",Lists.newArrayList(1,2,3));

问题：使用SDK调用API，LIKE参数过滤条件不生效

回答：operator为LIKE的参数时，参数值需要填写左右模糊匹配还是全模糊匹配，例如：

用户期望条件是：

• where p like '%a%'，参数值就传%a%。

• where p like 'a%'，参数值就传a%。

• where p like '%a'，参数值就传%a。

问题：使用SDK分页获取数据时，数据总数正确，但存在重复数据

原因：API代码中未使用排序字段使每次的排序结果唯一，或数据库本身不支持排序，导致每次分页获取数据时的查询结果的排序不一致，导致重复获取数据或丢失数据。

回答：确保返回结果排序的稳定性。若有主键，可增加主键字段排序，如果没有主键，可使用多个字段组成联合主键排序，确保每次排序的结果是稳定的。