跳转至

接口调用

浏览服务基本信息

用户所申请的接口在通过审核授权后,回到该接口的描述页面,在 参数说明 一栏介绍了该接口的 请求参数返回参数 。此时只显示该接口的公共请求参数,用户可先查看公共请求参数的名称和规则:包括数据类型,是否为必填字段,参数描述。

参数说明 的上方,还提供了 调用说明 以及 功能说明 等API的基本服务信息,供用户浏览查看。

公共请求参数

其中,接口地址为该API接口的 URL 地址。公共请求参数PAGENUM表示接口调用后返回的连续数据样本数量,参数START代表返回的第一个数据样本的索引。

在线调用接口

点击 在线接口调用 按钮,进入在线接口调用页面。在上面的接口参数文本框中输入公共请求参数,点击 接口调用 按钮,用户可在下方的接口参数窗口中得到 JSON格式的返回参数 。如下图:

在线调用接口

在该示例的返回内容中,冒号前面的内容为字段,并按照层级进行了缩进。

  • 其中“code”为操作码:如响应值为200,则代表成功响应,有具体数据返回;响应值为300代表操作失败,无数据返回。
  • "msg"代表操作信息提示。成功响应时,则“msg”返回值为空;若出现错误时,“msg”会返回相应的错误内容。
  • “data”中是用户真正所需的返回数据。返回数据的样本量由请求参数PAGENUM决定,用户在这里可以查看部分数据具体值。

用户返回接口的描述界面,在下方 参数说明 中这时就会出现该接口返回参数。该示例接口的请求参数与返回参数详细信息如下图所示:

请求参数与返回参数

代码调用接口

公共数据开放网站服务调用支持三种方式:

  • 基于签名认证的调用 ,需要使用签名认证令牌,且在代码调用接口时要遵循一定的HTTP协议的传输格式,安全性高,推荐开发应用时使用该方式调用接口;
  • 基于简单认证的调用 ,安全性低,默认在开放网站的在线接口调用中使用,有调用次数限制,每天调用100次;
  • 兼容原开放平台的调用方式 ,在URL中传入client_idclient_secret,此方式只是为了确保基于旧开放网站开发的应用可以正常调用。

基于签名认证的调用

用户点击 个人中心我的令牌 选项中可以查看令牌,令牌分为签名认证令牌、简单认证令牌。

网站支持重新生成令牌,以备在令牌泄露后禁用原有令牌,并重新生成新的令牌。

其中签名认证令牌由Client IDClient Secret两部分组成:

  • Client ID是令牌的标识,在调用服务时需要传递,用于标识服务调用方。
  • Client Secret是令牌的密钥,相当于用户密码,需要妥善保存,在调用服务时需要基于此密钥生成签名。

我的令牌 页面如下图所示:

我的令牌

用户要查看Client Secret需点击后面的 查看 链接,系统会向账号绑定的手机号发送验证码,在下方出现的文本框中输入验证码后,即可查看Client Secret的具体值。

调用过程

  1. 返回该接口的描述页面,在 调用说明 一栏中,找到 接口地址 一行中的 URL 地址,并在使用时在URL地址后用' ? '和' & '拼接请求参数名与对应的参数值。用户按格式调用接口的 URL 地址,才能获取相应内容。

  2. 接口调用最常见的请求方式为 GETPOST 两种方式,即读接口和写接口,通过这两种方式,实现对数据的增删查改,其中增删改本质都是写的动作。 GET 请求会将数据放在 URL 地址中, POST 请求会将数据放在消息体Body中。

  3. 实际的代码调用接口服务必须遵循以下HTTP协议的传输方式的格式:

请求参数名 描述
X-Client-Id 令牌标识, 前后端约定
X-Timestamp 调用时间戳
X-Nonce 调用方生成的随机数,推荐用UUID
X-Signature 调用方生成的签名值
  • 调用时间戳的值为当前时间的毫秒数,也就是从1970年1月1日起至今的时间转换为毫秒,时间戳有效时间为10分钟。时间戳用于判断请求与当前时间差,超过有效时间请求失效,既防止请求长期有效又允许客户端和服务端之间存在10分钟时间差;

  • 随机数有调用方生成,时间戳和随机数组合防止服务重放攻击。

  • 调用签名的生成方式为使用HmacSHA256算法对 X-Client-Id + X-Timestamp + X-Nonce 组合字符计算后,再经过Base64编码得到的加密字符串,密钥为签名认证令牌密钥Client Secret

  • 根据以上要求,在调用请求发送前需对请求参数执行如下的代码片段来实现API网关的签名认证:

```java import org.apache.commons.codec.binary.Base64;

import org.apache.http.client.config.RequestConfig; import org.apache.http.client.entity.UrlEncodedFormEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClientBuilder; import org.apache.http.impl.client.HttpClients;

import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec;

import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.time.Instant; import java.util.UUID;

String serviceUrl = "SERVICE_URL"; // 具体服务的调用地址 int timeout = 500; // 服务调用延时 String clientId = "YOUR_CLIENT_ID"; // 替换为用户的client_id String timestamp = String.valueOf(Instant.now().toEpochMilli()); String nonce = UUID.randomUUID().toString(); String secret = "YOUR_CLIENT_SECRET"; // 替换为用户的client_secret String stringToSign = clientId + timestramp + nonce;

String sign = null; try { Mac hmacSha256 = Mac.getInstance("HmacSHA256"); byte[] keyBytes = secret.getBytes("UTF-8"); hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256")); sign = Base64.encodeBase64String(hmacSha256.doFinal(stringToSign.getBytes("UTF-8"))); } catch (NoSuchAlgorithmException e) { } catch (UnsupportedEncodingException e) { } catch (InvalidKeyException e) { }

HttpClientBuilder httpClientBuilder = HttpClients.custom().useSystemProperties(); CloseableHttpClient httpClient = httpClientBuilder.build();

HttpPost requestMethod = new HttpPost(); // 根据服务的具体请求方法构造合适的请求方法对象,此处以POST方法为例说明 requestMethod.setURI(serviceUrl); RequestConfig config = RequestConfig.custom().setConnectTimeout(timeout).build(); requestMethod.setConfig(config);

requestMethod.addHeader("X-Client-Id", clientId); requestMethod.addHeader("X-Timestamp", timestamp); requestMethod.addHeader("X-Nonce", nonce); requestMethod.addHeader("X-Signature", sign);

CloseableHttpResponse response = httpClient.execute(requestMethod);

// 处理返回结果 ```

```javascript var url = ""; var clientId = ""; var clientSecret = "";

var timestamp = new Date().getTime(); var nonce = createUuid();

var textToSign = appKey + timestamp + nonce; var hash = CryptoJS.HmacSHA256(textToSign, clientSecret); var signature = hash.toString(CryptoJS.enc.Base64);

$.ajax({ url: url, type: "POST", beforeSend: function(request) { request.setRequestHeader("X-Client-Id", clientId); request.setRequestHeader("X-Timestamp", timestamp); request.setRequestHeader("X-Nonce", nonce); request.setRequestHeader("X-Signature", signature); }, success: function(result) { console.log(result); } });

function createUuid() { return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function© { var r = Math.random()*16|0, v = c == 'x' ? r : (r&0x3|0x8); return v.toString(16); }); } ```

调用说明

以上调用接口的过程信息用户可以在该接口的描述页面中的 调用说明 一栏中查看,如下图:调用说明

基于简单认证的调用

用户点击 个人中心 后,在 我的令牌 选项中可以查看简单认证令牌, 如下图:

简单认证令牌

如页面中提示所说,简单认证令牌通过明文传递, 安全性较弱 ,只适合服务在线调用,不建议在开发的应用中使用。用户点击AppKey查看 链接后,即可显示简单认证令牌的具体值。基于简单认证的接口调用的URL地址格式以及调用方式与签名认证调用接口的一致,但在代码调用时不需要实现API网关的签名认证。

```java import org.apache.commons.codec.binary.Base64;

import org.apache.http.client.config.RequestConfig; import org.apache.http.client.entity.UrlEncodedFormEntity; import org.apache.http.client.methods.CloseableHttpResponse; import org.apache.http.client.methods.HttpPost; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClientBuilder; import org.apache.http.impl.client.HttpClients;

import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec;

import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import java.time.Instant; import java.util.UUID;

String serviceUrl = "SERVICE_URL"; // 具体服务的调用地址 int timeout = 500; // 服务调用延时 String appKey = "YOUR APP KEY"; // 替换为用户的AppKey

HttpClientBuilder httpClientBuilder = HttpClients.custom().useSystemProperties(); CloseableHttpClient httpClient = httpClientBuilder.build();

HttpPost requestMethod = new HttpPost(); // 根据服务的具体请求方法构造合适的请求方法对象,此处以POST方法为例说明 requestMethod.setURI(serviceUrl); RequestConfig config = RequestConfig.custom().setConnectTimeout(timeout).build(); requestMethod.setConfig(config);

requestMethod.addHeader("AppKey", appKey);

CloseableHttpResponse response = httpClient.execute(requestMethod);

// 处理返回结果 ```

兼容原开放平台的调用方式

用户点击 个人中心 后,在 我的令牌 选项中可以查看在老平台申请的所有令牌,如果没有则表示不存在这样的令牌。原有的服务调用令牌如下图所示:

原有服务调用令牌

如页面中的提示所说,平台在升级后,为确保原来的服务申请可以正常使用,保留了原来的服务调用令牌。平台将逐步禁用该令牌,并替换为最新的服务令牌。