OpenAPI调用相关问题

目录

公共参数相关

1. 什么是OpenID, OpenKey?

OpenID:用户的唯一标识,根据APPID以及QQ号码生成,同样的QQ号在不同应用中OpenID也不一样。详见:概念和术语#OpenID

OpenKey:用户的会话密钥(session key),同一个用户如果在不同时间打开多个应用页面,页面返回的OpenKey是不一样的,这些openkey在各自的页面都可用。详见:概念和术语#OpenID

2. OpenID是否唯一?

OpenID根据APPID以及QQ号码生成,在每个应用中都是唯一,作为用户的唯一标识。

3. 是否能通过OpenAPI直接获取用户QQ号?

不能。用户在应用中的唯一标识是OpenID,腾讯开放平台不提供用户的QQ号。

4. 如何获取OpenID和Openkey等参数?

Step1: 了解什么是CanvasURL
CanvasURL也称之为应用开发地址。(你可能需要了解什么是CanvasURL。)
CanvasURL在2种场景下被引用:
-对于开发中的应用,从“开发者”应用中跳转到应用时,需要引用CanvasURL才能进入到应用。
-对于符合接入规范的应用,通过应用平台地址跳转到应用时,需要引用CanvasURL才能进入应用。

Step2: 了解如何获取CanvasURL:
-对于开发中的应用,您需要解析从“开发者”应用中跳转到应用时引用的URL。(你可能需要了解如何进入“开发者”应用?)。
-对于符合接入规范的应用,您需要解析通过应用平台地址跳转到应用时引用的URL。(你可能需要了解如何获取应用平台地址?)。

Step3: 了解如何获取OpenID和Openkey等参数:
跳转到应用后,CanvasURL后会带上OpenID和Openkey等参数。开发者可以通过解析CanvasURL来获取这些参数(例如PHP中可以通过$_GET方法获取参数)。

PHP获取OpenID和Openkey的示例代码:

<?php 
$openid = $_GET['openid'];
$openkey = $_GET['openkey'];
?>


JAVA获取OpenID和Openkey的示例代码:

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
public class NewClass extends HttpServlet  {     
    /**
     * 获取通过GET方式传递过来的openid和openkey
     * @param request
     * @param response
     * @throws ServletException
     */
    public void doGet(HttpServletRequest request,HttpServletResponse response) 
            throws ServletException { 
        String openid = request.getParameter("openid"); 
        String openkey = request.getParameter("openkey");
    }
}


跳转到应用后,CanvasURL后一定会带的参数包括:openid,openkey,pf,pfkey。
根据场景不同可能会带的参数有:invkey,iopenid,itime,source,app_custom。
:Openkey长度为不固定的字符串,不能为空。建议开发者不要检查openkey的长度,也不要在后台存储openkey,否则可能会导致用户无法登录。

Step4: 了解可能获取不到参数的情况:
详见下面的问题:OpenAPI调用相关问题#5. 为何获取不到OpenID和Openkey等参数?

另外,您也可以通过OpenAPI调试工具获取协作者openid和openkey,具体方式如下图:
OpenAPIdiaoyongxiangguanwenti-1.jpg

5. 为何获取不到OpenID和Openkey等参数?

原因分析:
当登录用户从腾讯平台(朋友/QQ空间/微博等)进入应用时,平台会调用应用的CanvasURL并在CanvasURL后带上OpenID及OpenKey等参数。开发者需要解析CanvasURL,以获取OpenID和Openkey的值并保存起来,用于后续调用OpenAPI时使用。
在V6版QQ空间中,为了对静态页面缓存优化,对应用的canvarurl是.htm或者.html后缀的url传参数是通过hash传递,即#后面传参数,这个参数不会发送到web server,通过抓包是看不到,只能前台页面获取。
因此如果non-hosting应用其应用开发地址是以htm,html结尾,则如果用"?"来解析跳转URL,就会获取不到参数。
对于hosting应用来说,其应用开发地址由腾讯提供,不会存在以htm,html结尾,则不会出现获取不到参数的情况。

解决方案:
应用的CanvasURL如果是以.htm或.html结尾的,请在解析时兼容"?" "#"两种传参方式。
推荐前端可以使用这个方法获得参数:

   function getHttpParams(name)
   {
        var r = new RegExp("(\\?|#|&)"+name+"=([^&#]*)(&|#|$)");
        var m = location.href.match(r);
        return decodeURIComponent(!m?"":m[2]);
   }



6. 调用OpenAPI时需要传入userip,如何获取?

应用服务器得到的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。


7. QQ互联和腾讯开放平台的OpenID是否相同?

不同。OpenID是根据APPID和用户QQ号生成,QQ互联和腾讯开放平台应用的APPID不一样,所以无法使用相同的OpenID。

8. pf值有哪些?

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

pf值以及对应的平台的列表包括但不仅限于如下:
qzone:空间;pengyou:朋友;qplus:Q+;tapp:微博;qqgame:QQGame;3366:3366;kapp:开心;manyou$id(ID不固定,跳转到应用首页后,URL会带参数manyouid,表示这里的ID):漫游。union-$id-$id(ID不固定,跳转到应用首页后,URL会带union-$id-$id):腾讯游戏联盟。
后缀加上_m代表来自手机,如:pengyou_m:手机朋友。


注:
(1)由平台直接传给应用,应用原样传给平台即可。请不要应用手动构造pf值,也不需要对平台传递的pf进行有效性校验,以避免应用上线多平台时需要付出额外的修改成本,导致调用某些接口时由于参数需要根据pf值生成导致传入参数不合法。
(2)腾讯开放平台API列表注明了某个API支持哪些pf。没有注明的,则默认不支持,除非某个平台的接入流程里特别另外给出了关于API的支持说明。例如目前API列表里注明了某个接口是否支持空间,朋友,微博,但是没有注明是否支持3366,开发者需要去参看3366平台的API列表文档(该文档由3366平台提供,目前放在3366联调指引中,详见:3366平台应用联调指引#2.2 调试内容)。
(3)如果不知道如何解析CanvasURL以获取pf,点击这里
(4)如果解析CanvasURL时获取不到pf,点击这里
(5)建议应用不要在程序中对pf进行转换(例如将字符型转换为int型),避免对于值不固定的pf(例如漫游或游戏联盟的pf)支持造成障碍。

OpenAPI版本、权限、支持的平台相关

1. OpenAPI V3.0相比老版OpenAPI,在接口调用上有什么不同?

1. OpenAPI V3.0支持全平台统一接入,对于同一功能,第三方应用不再需要根据不同的平台调用不同的接口(例如对于“获取用户信息”,OpenAPI V3.0只提供1个接口 v3/user/get_info即可同时支持多个平台;而老版OpenAPI则每个平台提供了1个接口)。
2. 基于全新的OpenAPI V3.0接入协议,请求中必须包含签名值,更加安全。
3. 参数和返回值上尽量和老版本接口兼容,开发者升级到OpenAPI V3.0时,代码改造工作量较小。
4. 正式环境提供域名访问方式,平均访问速度更快,主要接口不受公网波动的影响。

2. 为什么API列表中的接口有的我没有权限访问?

这是由于您的应用还没有被授权访问该OpenAPI:
(1)有一些接口由于其特殊性,必须提出申请后才能获得授权。
(2)对于non-hosting的应用,由于不能调用好友关系链OpenAPI,因此不进行授权。

3. QQ空间和朋友平台调用的接口是否一致?

如果该接口对于QQ空间和朋友平台都开放,则无需区分QQ空间和朋友平台。

4. OpenAPI是否可以通过flash调用?

不能。OpenAPI是后台API,必须通过后台调用。

5. OpenAPI支持哪些平台?

腾讯开放平台API列表注明了某个OpenAPI支持哪些平台。
没有注明的,则默认不支持,除非某个平台的接入流程里特别另外给出了关于API的支持说明。
例如目前API列表里注明了某个接口是否支持空间,朋友,微博,但是没有注明是否支持3366,开发者需要去参看3366平台的API列表文档(该文档由3366平台提供,目前放在3366联调指引中,详见:3366平台应用联调指引#2.2 调试内容

OpenAPI调用出错相关

1. 一直返回1002?

返回1002的原因有两种:
(1)用户没有到该平台注册(没有注册QQ空间,朋友,微博等),导致获取不到对应平台的用户信息。
解决方案:提示用户到该平台注册即可。

(2)OpenKey过期。
用户登录平台后进入应用时,URL中会带有该用户的OpenID和OpenKey,该OpenKey具有2小时的有效期。
如果用户在应用中一直在操作,但是2小时内没有触发OpenAPI的调用,则会导致OpenKey过期。因此开发者应该检查应用的代码,优化设计,采用一些简单的机制刷新用户的OpenKey,预防上述情况的出现。
腾讯专门提供了v3/user/is_login接口,用于登录用户的OpenKey续期。虽然应用调用任何一个OpenAPI都可以刷新用户的OpenKey,但是如果仅仅为了出于自动续期的目的而去随意调用某一个OpenAPI,则会给后台服务造成很大的压力 。因此推荐使用v3/user/is_login接口专门用于OpenKey续期的处理。

解决方案:如果OpenKey已经过期,开发者可以调用接口fusion2.dialog.relogin让用户重新登录,获取新的有效的OpenKey。



2. 由于100-continue问题,导致调用OpenAPI出错?

问题分析:
在使用CURL做POST的时候,CURL并不会直接就发起POST请求,而是会分为2步:
(1)发送一个请求,请求头部包含一个“Expect:100-continue”,询问httpserver是否愿意接受数据;
(2)接收到Server返回的100-continue应答以后,把数据POST给httpserver。
(CURL的行为详见RFC2616中的相关描述:http://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.2.3

腾讯开放平台用来响应OpenAPI请求的httpserver出于性能上的考虑,不支持对100-continue的应答。需要在应用程序中进行处理,否则会导致请求发送失败,调用OpenAPI出错。

解决办法:
腾讯开放平台提供的官方SDK中已经增加了相关处理,因此不会出现该问题。
如果是开发者自己封装SDK,则需要在调用OpenAPI时增加对请求头部中“Expect:100-continue”的处理。以PHP为例:

curl_setopt($ch, CURLOPT_HTTPHEADER, array('Expect:'));



3. 敏感词过滤接口v3/csec/word_filter不起作用?

敏感词过滤接口(v3/csec/word_filter)不能屏蔽敏感词,一般是由于传入的"content"参数并不是UTF-8编码造成的。
请开发者检查文本是否采用的utf-8编码。以中文“测试敏感词”为例(测试时请换成实际的敏感词):
utf-8编码并urlencode后:%E6%B5%8B%E8%AF%95%E6%95%8F%E6%84%9F%E8%AF%8D ;
如果采用了gbk编码并urlencode后:%B2%E2%CA%D4%C3%F4%B8%D0%B4%CA),则不符合要求。

关于调用赠送礼物接口的详细信息请参见fusion2.dialog.sendRequest

4. 总是返回总是返回“-5:signature verification failed”?

签名校验失败。
详见:腾讯开放平台第三方应用签名参数sig的说明#常见错误排障


5. 获取用户头像时报策略文件安全问题

Flash应用中访问用户头像时报出策略文件没有*pengyou.com/*.qzone.com这些域的安全问题,这是由于只允许flash应用加载显示用户头像图片,不支持对头像内容进行操作。
详见:前端页面规范#7. 关于Flash应用中用户头像的加载和操作

6. Flash应用调OpenAPI报“Security sandbox violation”错误

问题描述:
Flash应用调用OpenAPI时报错“Security sandbox violation: http://s4.app*****.qqopenapp.com/bin_x/release/Fishing.swf cannot load data from http://openapi.tencentyun.com/v3/relation/get_app_friends.”

问题分析:
该错误是由于数据跨域导致的。开放平台不允许这种从前端Flash直接调用OpenAPI的方式。

解决方案:
应用不要直接从前端Flash调用OpenAPI,而应该后台调用OpenAPI,然后将数据返回给flash。

7. 测试环境下调用OpenAPI一直返回“-64”?

测试环境IP仅针对调试者QQ号有用,即只有调试者QQ号对应的OpenID会通过验证。非调试者QQ号将会返回-64的错误。
详见:应用测试环境说明#3.2 测试OpenAPI


8. 调用OpenAPI返回“is_lost,1”怎么办?

当OpenAPI返回值中is_lost值为1时,表示返回数据不准确(如果应用不考虑cache可以不关心)。
请先检查请求的URL及参数是否正确(比如pf等参数),然后通过企业QQ联系技术支持协助定位。

9. 为什么调用OpenAPI会偶尔出现-58,-60等错误?

OpenAPI的系统容错率为0.1%,如果应用后台调用OpenAPI报-65的频率占调用OpenAPI总次数的0.1%以下,是正常情况,请合理设置应用的容错与重试机制。
如果某个OpenAPI报错几率大于0.1%,请通过企业QQ联系技术支持,调查问题原因并获得解决方案。

10. 为什么调用OpenAPI提示“you are in the test environment...”的信息?

调用OpenAPI时提示“you are in the test environment, the QQ number you are using is not in your app's debug QQ number list”,有两种可能的情况:
(1)应用上线前,只有已设置为调试者的QQ号码才能进入应用,如果进入应用的QQ号码不在该应用的调试者列表中,就会出现这一提示。解决方法:把该QQ号码设为调试者。
(2)应用上线后,应该调用正式环境的OpenAPI,如果继续调用测试环境的OpenAPI,就会出现这一提示。解决方法:修改配置,调用正式环境的OpenAPI。

其它OpenAPI调用相关问题

1. 游戏类应用过滤关键字的标准是什么?

应用中不包含政治、色情等敏感词,不应包含广告等垃圾信息。
1. 对于敏感词,可调用安全OpenAPI v3/csec/word_filter 过滤敏感词。
2. 对于广告等垃圾信息,可调用安全OpenAPI v3/csec/check_spam 过滤垃圾消息。



2. 调用v3/user/get_info接口返回的用户头像尺寸是固定的?

可以通过修改URL后面的尺寸大小来获取不同尺寸的头像。
详见:前端页面规范#6. 关于用户头像的获取和尺寸说明

3. OpenAPI超时时间应该设置为多少比较合适?

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

4. 是否可以获得用户所有QQ好友?

不能。
只提供了v3/relation/get_app_friends接口,应用可通过该接口获取到用户全部好友中安装了该应用的好友。


5. 为什么v3/user/get_info拉取的黄钻信息不准确?

为了提高OpenAPI的效率,部分接口(例如v3/user/get_info)使用了短期缓存,有一定的延时,适用于不需要黄钻信息特别准确的场景(例如用户头像后的黄钻标识)。
如果应用需要实时的用户黄钻信息(例如黄钻每日礼包场景中,非黄钻用户开通黄钻后,返回应用应该立即可领取礼包),请调用专门的VIP实时信息获取接口。 目前为黄钻提供专门的黄钻实时信息获取接口:v3/user/is_vip,其它VIP实时信息获取接口为:v3/user/total_vip_info

6. 为什么v3/user/get_info拉取的昵称和用户的QQ昵称不一样?

OpenAPI拉取的用户信息是基于平台的,并非是用户的QQ资料信息。
例如:
当前用户的QQ昵称为user,空间昵称为qzone_user,朋友昵称为李磊。
则当pf=qzone时,返回的昵称为qzone_user,当pf=pengyou时,返回的昵称为李磊,并非QQ昵称。

7. 为什么拉取好友关系链不对称?

拉取好友关系链不对称指:通过接口v3/relation/get_app_friends拉取用户A的好友可以获取到B的相关信息,但是拉取用户B的好友却获取不到A的相关信息。
出现这种情况,很有可能是单向好友导致的,即B是A的好友,但A不是B的好友。开发者可以到http://id.qq.com/ 中的“好友”tab中选择“单向好友”查询。 如果确认是非单向好友,拉取好友关系链仍然不对称,请联系企业QQ进行处理。

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

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部