非SDK方式调用说明(自行发起http请求)


对于API调用者,自行发起http请求调用API时,要明确以下几点:

请求地址

向API发布者获取;或者在有权限的API详情页查看和复制请求地址。

header设置

请求header里需要自行带上鉴权参数,鉴权类型分为AK/AS和apiToken鉴权,具体参数说明如下:

  • version:权限校验版本,必传,如果是AK/AS鉴权方式则传入v1,如果是apiToken鉴权方式则传入v2
  • appKey:应用key,必传,例如 07007bea09b34f3a8cf6dbf7e7b7e4b6
  • timestamp: 调用时间戳,单位为ms,当version=v1时需要传入,例如 1578364362000
  • signature:调用签名,当version=v1时需要,例如 dff822afc20047819039b0bd5c6169ff
  • apiToken:api的固定token秘钥,当version=v2时需要

timestamp过期时间为5min,即不在当前时间5min范围内的时间戳将不能通过校验。 signature需要在每次调用时动态生成,生成算法为md5(appSecret+timestamp),为小写32位。其中 appSecret为应用秘钥,只参与signature的计算,不需要传递。version,appKey,appSecret均可向API发布者获取,或者对于绑定的应用,有权限查看其详情时,也可在应用详情页查看appKey和appSecret。

除此之外,由于POST方式传递参数数据格式是JSON,所以当使用POST调用API时,header中还需要加入Content-Type="application/json"。

java md5工具类可参考如下:

//MD5工具类,可拷贝至项目中使用
import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;
import java.nio.charset.Charset;
import java.security.MessageDigest;

public class MD5MsgDigest {

    public static String digest(String rawString) {
        return digest(rawString, "utf-8");
    }

    public static String digest(String rawString, String charset) {
        Charset cs = Charset.forName(charset);
        try {
            return compute(rawString, cs);
        } catch (Exception e) {
            return "";
        }
    }

    private static String compute(String inStr, Charset charset) throws Exception {
        MessageDigest md5 = MessageDigest.getInstance("MD5");
        byte[] md5Bytes = md5.digest(inStr.getBytes(charset));
        return toHexString(md5Bytes);
    }


    public static String toHexString(byte[] bytes) {
        StringBuffer hexValue = new StringBuffer();
        for (int i = 0; i < bytes.length; i++) {
            int val = ((int) bytes[i]) & 0xff;
            if (val < 16) {
                hexValue.append("0");
            }
            hexValue.append(Integer.toHexString(val));
        }
        return hexValue.toString();
    }
}

//工具类使用方式
String signature = MD5MsgDigest.digest(appSecret + currentTimestamp))

请求参数设置

  1. GET请求时,请求参数放在URI
    将需要传递的参数按照uri参数请求规范拼接在请求地址后面,例如需要传递参数a、b和c,则请求地址为: http://eds.com/product/easy-data-api/edsSet/api?a=1&b=2&c=3。

  2. POST请求时,请求参数以json格式放在request body
    将需要传递的参数按照JSON格式放置在request body中, 例如需要传递参数a、b和c,则request body中增加内容为:

    {
     "a":1,
     "b":2,
     "c":3
    }

    调用的API具体是使用GET还是POST,请咨询API发布者,或在有权限的API详情页查看请求方式。

JAVA SDK方式调用说明


以maven工程为例,对于API调用者,使用数据服务提供的JAVA SDK的方式调用API时,需要将数据服务提供的java SDK jar包安装进本地maven仓库中,然后再执行下面的步骤。

引入SDK依赖

在maven项目的pom.xml文件中申明依赖。

<dependency>
    <groupId>com.netease.hz.bdms</groupId>
    <artifactId>eds-java-sdk</artifactId>
    <version>x.y.x.z</version>
</dependency>

最新版本version请咨询数据服务管理员。

使用SDK发起API调用

参考如下:

package com.netease.hz.bdms.eds.sdk;

import com.alibaba.fastjson.JSONObject;
import java.io.IOException;
import org.junit.Test;

/**
 * EdsClient演示demo.
 */
public class TestEdsClient {

  @Test
  public void Test() {

    // 请求入参,GET默认放在uri中,POST默认放在request body中
    JSONObject param = new JSONObject();
    param.put("id", 2);

    // V1 AKSK鉴权并发起GET请求
    EdsClient clientV1 = new EdsClient(
        "v1",
        "f8601690cfcb4c24843a08ecead7df1e",
        "792f804a196b4dc9a42b1cb65d8ef977",
        null,
        100);
    try {
      JSONObject result = clientV1.get(
          "http://easy-data-service-dev.service.163.org/easy-data-api/intern/qiuxiat/api2",
          param);
      System.out.println(result.toString());
    } catch (IOException ex) {
      ex.printStackTrace();
    }

    // V2 api token鉴权并发起POST请求
    EdsClient clientV2 = new EdsClient(
        "v2",
        "f8601690cfcb4c24843a08ecead7df1e",
        null,
        "792f804a196b4dc9a42b1cb65d8ef977",
        10000);
    try {
      JSONObject result = clientV2.post(
          "http://easy-data-service-dev.service.163.org/easy-data-api/intern/qiuxiat/api1",
          param);
      System.out.println(result.toString());
    } catch (IOException ex) {
      ex.printStackTrace();
    }
  }
}