快代理 api 会对每个访问请求进行身份验证,即每个请求都需要包含签名信息(signature参数)以验证请求者身份。 签名信息由安全凭证生成,安全凭证包括 订单号(orderid) 和 api key;每个订单都有,api key相当于调用api的密码,一定要严格保密谨防泄露。

开启接口验证

为了兼容之前的api链接,提取开放代理、提取私密代理、提取独享代理三个接口,默认不需要验证,生成的api链接可以直接使用。
其他接口必须验证签名才能调用

我们推荐在会员中心对三个代理提取接口也。
开启验证的好处是即使别人拿到订单号,也无法使用api,安全性大大增强。

建议使用https调用接口

我们强烈建议您使用https调用api,加密传输可让订单号、api key等私密信息不被第三方监听和截获,更加安全。
使用https只需将api链接开头的http://替换为https://即可。

签名验证机制

我们提供两种签名机制供您选择:

  1. 密钥明文验证(默认)
  2. 数字签名验证

您可以根据自己的业务需要选择任意一种进行签名验证。下面是对两种验证机制的详细说明。

密钥明文验证

参数设置:sign_type=simple

密钥明文验证非常简单,适合希望快速接入,对安全性没有非常高要求的开发者。

使用密钥明文验证,直接把api key放到signature参数里即可。在会员中心,比如您订单的api key是oeq1zxnmoxzlefzmjrqu2xufwndod7kz,api链接的签名参数即为signature=oeq1zxnmoxzlefzmjrqu2xufwndod7kz

数字签名验证

参数设置:sign_type=hmacsha1

数字签名验证机制更为复杂,适合对安全性有高要求的开发者。
我们采用hmac-sha1方式进行数字签名,步骤如下:

1. 生成签名串

以下是生成签名串的详细过程:

假设用户的orderidapikey分别是:

  • orderid: 934995977901561
  • apikey: u8n5a0f2hu39o80lpir3hq1kug37tb5i

注意: 这里只是示例,请根据用户实际的 orderidapikey 进行后续操作!

以获取订单到期时间请求为例,当用户调用这一接口时,其请求参数可能如下:

参数名称 中文 参数值
orderid 订单号 934995977901561
sign_type 鉴权方式 hmacsha1
timestamp 当前时间戳 1555064362

1.1 对参数排序

首先对所有请求参数按参数名的字典序( ascii 码)升序排序。注意:
1)只按参数名进行排序,参数值保持对应即可,不参与比大小;
2)按 ascii 码比大小,如 instanceids.2 要排在 instanceids.12 后面,不是按字母表,也不是按数值。用户可以借助编程语言中的相关排序函数来实现这一功能,如 php 中的 ksort 函数。
上述示例参数的排序结果如下:

{
    "orderid": "954763036233510",
    "sign_type": "hmacsha1",
    "timestamp": 1555064362,
}

使用其它程序设计语言开发时,可对上面示例中的参数进行排序,得到的结果一致即可。

1.2 拼接请求字符串

此步骤生成请求字符串。 将把上一步排序好的请求参数格式化成“参数名称”=“参数值”的形式,如对 orderid 参数,其参数名称为 "orderid" ,参数值为 "954763036233510" ,因此格式化后就为 orderid=954763036233510 。

注意: “参数值”为原始值而非url编码后的值。

然后将格式化后的各个参数用"&"拼接在一起,最终生成的请求字符串为:

orderid=954763036233510&sign_type=hmacsha1×tamp=1555069980

1.3 拼接签名原文字符串

此步骤生成签名原文字符串。 签名原文字符串由以下几个参数构成:

  1. 请求方法: 支持 post 和 get 方式,这里使用 get 请求,注意方法为全大写。
  2. 请求路径: 例如获取订单到期时间的请求路径为:/api/getorderexpiretime。实际的请求路径根据接口的不同而不同,详见各接口描述。
  3. 请求字符串: 即上一步生成的请求字符串。

签名原文串的拼接规则为: 请求方法 请求路径 ? 请求字符串

示例的拼接结果为:

get/api/getorderexpiretime?orderid=954763036233510&sign_type=hmacsha1×tamp=1555069980

1.4 生成签名串

此步骤生成签名串。首先使用 hmac-sha1 算法对上一步中获得的签名原文字符串进行签名,然后将生成的签名串使用 base64 进行编码,即可获得最终的签名串。

具体代码如下,以 php 语言为例:


$apikey = 'u8n5a0f2hu39o80lpir3hq1kug37tb5i';
$rawstr = 'get/api/getorderexpiretime?orderid=954763036233510&sign_type=hmacsha1×tamp=1555069980';
$signstr = base64_encode(hash_hmac('sha1', $rawstr, $apikey, true));
echo $signstr;

最终得到的签名串为:

 hlah7rlyoq3ssb2xubzgpyozn4=

使用其它程序设计语言开发时,可用上面示例中的原文进行签名验证,得到的签名串与例子中的一致即可。

2. 签名串编码

生成的签名串并不能直接作为请求参数,需要对其进行 url 编码。

如上一步生成的签名串为 hlah7rlyoq3ssb2xubzgpyozn4=,最终得到的签名串请求参数(signature)为 +hlah7rlyoq3ssb2xubzgpyozn4=, 它将用于生成最终的请求 url。

提示

  1. 如果用户的请求方法是 get,或者请求方法为 post 同时 content-type 为 application/x-www-form-urlencoded,则发送请求时所有请求参数的值均需要做 url 编码,参数键和=符号不需要编码。非 ascii 字符在 url 编码前需要先以 utf-8 进行编码。

  2. 有些编程语言的 http 库会自动为所有参数进行 urlencode,在这种情况下,就不需要对签名串进行 url 编码了,否则两次 url 编码会导致签名失败。

  3. 其他参数值也需要进行编码,编码采用 。使用 %xy 对特殊字符例如汉字进行百分比编码,其中“x”和“y”为十六进制字符(0-9 和大写字母 a-f),使用小写将引发错误。

3. 签名演示

在实际调用 api 时,推荐使用配套的sdk, sdk 封装了签名的过程,开发时只关注产品提供的具体接口即可。详细信息参见 。当前支持的编程语言有:

为了更清楚的解释签名过程,下面以实际编程语言为例,将上述的签名过程具体实现。请求的域名、调用的接口和参数的取值都以上述签名过程为准,代码只为解释签名过程,并不具备通用性,实际开发请尽量使用 sdk 。

最终输出的 url 可能为:https://dev.kdlapi.com/api/getorderexpiretime?sign_type=hmacsha1&orderid=954763036233510×tamp=1555080775&signature=+hlah7rlyoq3ssb2xubzgpyozn4=

注意

由于示例中的密钥是虚构的,时间戳也不是系统当前时间。为了得到一个可以正常返回的 url ,需要修改示例中的 orderid 和 apikey 为真实的订单号和密钥,并使用系统当前时间戳作为 timestamp 。

4. 代码示例

在下面的示例中,不同编程语言,甚至同一语言每次执行得到的 url 可能都有所不同,表现为参数的顺序不同,但这并不影响正确性。只要所有参数都在,且签名计算正确即可。

python示例
import base64
import hmac
import hashlib
import time
import uuid
import requests
# 生成签名原文字符串
def get_string_to_sign(method, endpoint, params):
    s = method  endpoint  '?'
    query_str = '&'.join("%s=%s" % (k, params[k]) for k in sorted(params))
    return s  query_str
# 生成签名串
def sign_str(key, s, method):
    hmac_str = hmac.new(key.encode('utf8'), s.encode('utf8'), method).digest()
    print('hmac_str: ', hmac_str)
    return base64.b64encode(hmac_str)
if __name__ == '__main__':
    api_key = 'vbeuiug3av1sivuplasr0qymd6bxmfe8'
    endpoint = '/api/getorderexpiretime'
    data = {
        "timestamp": int(time.time()),
        "nonce": uuid.uuid4().hex[:8],
        "sign_type": "hmacsha1"
    }
    s = get_string_to_sign("get", endpoint, data)
    data["signature"] = sign_str(api_key, s, hashlib.sha1)
    print(data['signature'])
    # 此处会实际调用, 成功后可能产生ip消耗
    r = requests.get("https://dev.kdlapi.com"  endpoint, params=data)
    print(r.url)

4. sdk下载

通过sdk封装了签名计算过程,让您免去了这部分的编程工作,配置好apikey即可调用。

联系尊龙人生就是搏
  • 售前在线咨询
    咨询享免费测试,专业工程师提供尊龙现金一下的技术支持
  • 客服热线
     周一至周六 9:00-18:00
  • 提交工单
    您的每一次反馈我们都认真对待
  • 客服微信 & qq
    客服微信:,客服qq:
  • 企业客户通道
    提交需求后专业的售前工程师为您提供服务