腾讯云API使用指南

腾讯云OpenApi服务,是一组腾讯云产品的API 集合,用户可以通过腾讯云的OpenAPI,实现对腾讯云资源的查询、操作与管理。腾讯云OpenAPI统一以http接口的形式对外提供服务,用户可以使用不同编程语言进行二次开发,实现对腾讯云OpenAPI服务的使用。本文介绍了用户基于API URL发起HTTP/HTTPS请求腾讯云服务的流程,接口调用成功会返回相应的内容,调用失败则显示响应的报错,您可以根据公共错误码和具体API 错误码进行分析排查。
 
使用指南
使用腾讯云OpenApi服务,您需要一个腾讯云账号和腾讯云访问密钥(Accesskey)
在腾讯云控制台页面中创建和管理您的AccessKey,或联系您的账号管理员获取AccessKey
使用腾讯云某个产品的API前,请确保您已经开通了对应的产品
 
腾讯云提供OpenAPI服务的统一入口目前,腾讯云OpenApi存在两种接口风格:分别为action风格接口与restful风格接口,其中:
 
Action风格接口所有请求参数由一系列键值对组成,由名为action的键值对指定操作名称,其他键值对指定业务相关的参数,支持GET和POST方式请求。Action风格接口路由入口为/api/v1,即https://api.yun.com/api/v1
Restful风格接口的支持路径参数、URL参数以及Body参数,依据接口类型,对资源的请求类型由http的GET(表示获取)、POST(表示新增或修改)、PUT(表示更新)、DELETE(表示删除)方法完成,路由入口为/rest/v1,既https://api.yun.com/rest/v1

请求结构
 
腾讯云支持基于URL发起HTTP/HTTPS GET或POST请求,请求参数需要包含在URL中。以获取当前用户信息API GetUser为例,未经编码的的URL请求示例如下:
 
https://api.yun.com/api/v1?Action=GetUser&<公共请求参数>
 
https指定了请求通信协议
api.yun.com指定了服务接入地址
/api/v1指定了api类型
Action=GetUser指定了要调用的API
<公共请求参数>是系统中规定的公共参数,具体描述见腾讯云openapi服务公共请求参数

字符编码
 
请求参加以及响应结果均使用UTF-8字符集编码
 
身份凭证
 
腾讯云OpenAPI服务采用AccessKey的方式进行身份认证。AccessKey相当于用户密码,AccessKey用于调用API,而用户密码用于用户登录控制台。AccessKey由AccessKeyId与AccessKeySecret组成,具有全局唯一性。其中AccessKeyId是访问者身份,用于唯一标识一个用户,AccessKeySecret是密钥,在客户端用于对请求数据进行电子签名,在服务端用于验证客户端的签名,来判断请求的合法性。AccessKeySecret属于用户敏感信息,用户需严格保密AccessKeySecret的信息不被泄露,否则可能会被恶意利用,对用户在腾讯云购买的资源进行非法的操作。
 
签名机制
 
腾讯云OpenAPI服务通过验证签名的方式来保证到达服务端的请求是没有被篡改过的原始请求,只有原始请求才会被服务端接受并执行,否则服务端将拒绝服务,以保护用户的资源安全。目前腾讯云推荐使用的签名算法为HMAC-SHA256,签名时使用用户AccessKey中的AccessKeySecret作为签名密钥,签名密钥具有唯一性,在签名密钥没有被泄露的前提下,只有用户自己和腾讯云知晓该密钥,因此通过比对服务端和客户端用相同的密钥对相同的数据的签名结果,就可以判断出请求是否是合法且未经过篡改的。
 
签名过程
客户端在发送请求前,需要对请求内容进行签名并将和客户端的签名结果一起发送给服务端,由服务端以同样的方式对用户数据进行签名和比对,因此客户端与服务端的签名过程与与参与签名运算的数据必须一致。在签名过程中,需要考虑签名有效性、签名时效性、防重放攻击、签名算法版本演进、API版本差异等。因此在访问腾讯云API服务时,需要依赖以下公共请求参数:
 
腾讯云openapi服务公共请求参数

参数名称

参数类型

参数描述

备注

AccessKeyId

String

AccessKeyId,唯一标识一个用户

AccessKey中的AccessKeyId,该AccessKeyId唯一标识一个平安云用户

SignatureMethod

String

签名算法

腾讯云推荐使用HMAC-SHA256,签名时固定取值HMAC-SHA256

SignatureNonce

String

请求随机数

每次请求必须跟随一个足够复杂的随机值,该随机值用于标识一个唯一的请求,并且防止请求重放

SignatureVersion

String

签名版本

腾讯云目前支持的签名方法版本为1.0,签名时该参数固定传值1.0

Timestamp

String

签名时间戳

对请求进行签名的时间戳,签名时需获取当前时间戳字符串

Version

String

Api版本

目前腾讯云支持的API版本为2017-01-01,签名时固定传值2017-01-01

Signature

String

请求内容签名

请求内容的签名值,由前面的特殊参数和业务参数共同计算得到

 
请求参数编码
 
使用HTTP/HTTPS请求URL时,需要按照RFC3986规则,对请求参数名称和参数取值进行编码,编码规则如下:
 
字符a-z、A-Z、0-9以及字符-、_、.、~不编码
其他字符扩展成%XY的格式,其中XY是字符对应的ASCII码的16进制
单个空格编码为%20,而不是+。如果用户通过Java代码进行签名,使用Java标准库java.net.URLEncoder进行编码,或使用的其他Java组件编码内部实现使用了java.net.URLEncoder,需要对编码结果进行一些特殊处理,包括将编码后的字符中的+替换为%20,*替换为%2A,%7E替换为~

标签