API3.0文档

目录

OpenAPI是腾讯开放平台对外开放的后台接口的统称,可支持多平台(包括腾讯朋友,空间,微博,腾讯Q+以及其它多平台)。
OpenAPI V3.0是OpenAPI的升级版,相比老版本OpenAPI,OpenAPI V3.0具有接入更快捷,更安全,访问速度更快等优点。

从老版OpenAPI切换到OpenAPI V3.0前必读

老版本的OpenAPI将继续提供技术支持直至2012年6月30日,并于2012年8月20日下线停止对外服务。
如果您的程序中调用了老版本的OpenAPI,则需要在2012年6月30日前切换到OpenAPI V3.0。


切换时需要做如下工作:
1. 进行代码改造,调用OpenAPI V3.0接口。
注意OpenAPI V3.0的域名、接口名称、参数、返回码等都与老版OpenAPI不同,详见:API3.0文档#请求URL说明
2. 开发者可以下载OpenAPI V3.0 SDK。
注意由于接口协议的不同,该SDK不兼容老版本OpenAPI,详见:SDK下载#OpenAPI V3.0 SDK下载


您也可以了解更多关于OpenAPI V3.0的新特性,以及兼容性等方面的信息。
详见:OpenAPI调用相关问题#1. OpenAPI V3.0相比老版OpenAPI,在接口调用上有什么不同?

OpenAPI V3.0调用说明

请求URL说明

http://[域名]/[api_name]

域名和IP的说明:
正式环境下使用域名:openapi.tencentyun.com。测试环境下使用测试域名:openapi.sparta.html5.qq.com。
使用CEE进行程序部署的应用,测试环境请使用虚拟IP:1.254.254.22。

注意:
1. 原先已经接入的应用如果使用的是正式环境IP,建议改为域名访问方式,因为:
(1)域名访问方式在调用用户信息以及关系链接口时平均访问速度更快,主要接口不受公网波动的影响。
(2)域名访问方式扩展性更强。后续CEE支持域名访问后,则无论哪种部署方式,都可以使用域名访问,且无需再关注IP变更。
2. 使用CEE进行程序部署的应用测试环境IP也与上述不同,请使用虚拟IP:1.254.254.22。正式环境域名与上面相同。
3. 应用部署前必须确保已经将程序中的测试域名换成了正式域名,才能将应用上线到正式环境。
4. 测试环境IP仅针对调试者QQ号有用,即只有调试者QQ号对应的OpenID会通过验证,非调试者QQ号将会返回-64的错误。调试者QQ号的设置详见这里

api_name的说明:
[api_name]:见API列表中带API_legend_3.png 标记的接口。例如接口名称为:v3/user/get_info。

请求URL的示例:
1. 正式环境下访问OpenAPI V3.0:
http://openapi.tencentyun.com/v3/user/get_info
2. 测试环境下访问OpenAPI V3.0:
http://openapi.sparta.html5.qq.com/v3/user/get_info

OpenAPI超时时间说明

OpenAPI一般会在50ms以内返回数据,OpenAPI接口机设置的最长超时时间为3s。
开发者可以根据上述说明自行设置OpenAPI调用的超时时间。

公共参数说明

注意:
1. 所有参数都需进行URL 编码,编码时请遵守 RFC 1738
2. 下列部分参数是由平台直接传给应用的,应用原样传给平台即可,即跳转到应用首页后的URL会带该参数,一定会带的参数有:openid,openkey,pf,pfkey,根据场景不同可能会传的参数有:invkey,iopenid,itime,source,app_custom。
以上参数已经被腾讯的统计后台占用,应用不能再用作自定义参数。

参数名称 是否必须 类型 描述
openid 必须 string 与APP通信的用户key。从平台跳转到应用时会调用应用的CanvasURL,平台会在CanvasURL后带上本参数。由平台直接传给应用,应用原样传给平台即可。

根据APPID以及QQ号码生成,即不同的appid下,同一个QQ号生成的OpenID是不一样的。
注:
(1)如果不知道如何解析CanvasURL以获取OpenID和Openkey,点击这里
(2)如果解析CanvasURL时获取不到OpenID和Openkey等参数,点击这里

openkey 必须 string session key。从平台跳转到应用时会调用应用的CanvasURL,平台会在CanvasURL后带上本参数。由平台直接传给应用,应用原样传给平台即可。

注:
(1)如果不知道如何解析CanvasURL以获取OpenID和Openkey,点击这里
(2)如果解析CanvasURL时获取不到OpenID和Openkey等参数,点击这里
(3)注意同一个用户如果在不同时间打开多个应用页面,页面返回的openkey是不一样的,这些openkey在各自的页面都可用。但是不要在当前页面使用另1个页面的openkey,否则会出错;
(4)Openkey长度为不固定的字符串,不能为空。建议开发者不要检查openkey的长度,也不要在后台存储openkey,否则可能会导致用户无法登录;
(5)openkey过期时间为两小时,需要用v3/user/is_login接口续期。

appid 必须 unsigned int 应用的唯一ID。可以通过appid查找APP基本信息。

sig 必须 string 请求串的签名,以appkey作为密钥,具体签名算法见腾讯开放平台第三方应用签名参数sig的说明

pf 必须 string 应用的来源平台。从平台跳转到应用时会调用应用的CanvasURL,平台会在CanvasURL后带上本参数。由平台直接传给应用,应用原样传给平台即可。

注:
(1)由平台直接传给应用,应用原样传给平台即可。请不要应用手动构造pf值,也不需要对平台传递的pf进行有效性校验,以避免应用上线多平台时需要付出额外的修改成本,导致调用某些接口时由于参数需要根据pf值生成导致传入参数不合法。
(2)如果不知道如何解析CanvasURL以获取pf,点击这里
(3)如果解析CanvasURL时获取不到pf,点击这里
(4)建议应用不要在程序中对pf进行转换(例如将字符型转换为int型),避免对于值不固定的pf(例如漫游或游戏联盟的pf)支持造成障碍。

format string 定义API返回的数据格式。

取值说明:为xml时表示返回的格式是xml;为json时表示返回的格式是json。
注意:json、xml为小写,否则将不识别。format不传或非xml,则返回json格式数据。

userip string 用户的IP。

应用服务器得到的remote_ip和x_forward_ip是10.x.x.x,由上一层腾讯路由转发。
http请求的头里有一个QVia(HTTP_QVIA值),是个40个字节的串,前8个字节是IP,后面的是校验,将字节串前8个字节,分成4段,分别由16进制转成10进制,即可得到用户最终IP。
如果应用(例如新接入的应用、已经接入TGW的应用、non-hosting应用)获取不到QVia的值,可以直接通过标准http协议获取用户IP。

公共返回参数说明

公共返回参数如下,其余返回参数由各个API自行定义,请参考各OpenAPI的说明。

参数名称 描述
ret 返回码。具体返回码含义详见下文。
msg 如果错误,返回错误信息。
is_lost 数据是否丢失,如果应用不考虑cache可以完全不关心。

0或者不返回:完全没有丢失,可以缓存。
1:有一部分数据错误,不要缓存


公共返回码说明

详见:公共返回码说明#OpenAPI V3.0 返回码

OpenAPI V3.0 SDK下载

详见:SDK下载#OpenAPI V3.0 SDK下载

以上信息是否解决您的问题?

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部