Test
第45行: | 第45行: | ||
===切换时需要完成的工作=== | ===切换时需要完成的工作=== | ||
*1、授权方式的切换,OAuth1.0升级到OAuth2.0; | *1、授权方式的切换,OAuth1.0升级到OAuth2.0; | ||
− | * | + | *2、切换注意事项及常见问题解决建议; |
*3、新旧接口的切换,接口调用地址、调用方式、参数、返回值、错误信息处理的代码改造; | *3、新旧接口的切换,接口调用地址、调用方式、参数、返回值、错误信息处理的代码改造; | ||
第105行: | 第105行: | ||
**{"access_token":"SlAV32hkKG","remind_in":"3600","expires_in":3600,"uid":"1902538057"} | **{"access_token":"SlAV32hkKG","remind_in":"3600","expires_in":3600,"uid":"1902538057"} | ||
**注意:OAuth2.0的access_token较OAuth1.0具有一定的有效期,当access_token过期时需要引导用户重新授权。应用的授权有效期可以访问[[Rate-limiting |接口访问权限说明]]或在[http://open.weibo.com/apps 应用控制台]查看。 | **注意:OAuth2.0的access_token较OAuth1.0具有一定的有效期,当access_token过期时需要引导用户重新授权。应用的授权有效期可以访问[[Rate-limiting |接口访问权限说明]]或在[http://open.weibo.com/apps 应用控制台]查看。 | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
第128行: | 第115行: | ||
**写入接口必须使用POST方式提交,如: | **写入接口必须使用POST方式提交,如: | ||
+ | |||
+ | |||
+ | ===切换中常见问题=== | ||
+ | *1,怎么申请客户端的验证授权(Resource Owner Password Credentials)方式? | ||
+ | **因为OAuth2.0的客户端验证授权会获得用户明文密码,所以实行有限开放。 | ||
+ | **申请条件: | ||
+ | ***1)应用分类属于桌面客户端、手机客户端。 | ||
+ | ***2)应用本身已经通过开放平台文案、广场审核,并在广场上展示超过15天。 | ||
+ | ***3)应用使用人数在30000以上。 | ||
+ | ***4)应用本身功能与新浪微博关联紧密。 | ||
+ | **满足条件后在应用控制台的“接口管理”-->“授权机制”中申请。 | ||
+ | |||
+ | |||
+ | *2,手机客户端、PC客户端应用是否需要设置回调页? | ||
+ | **需要,使用Web应用的验证授权(Authorization Code)方式的客户端也需要设置授权回调页或绑定域名,在程序中以webview的方式进行调用授权页面返回code,具体实现参考相应的客户端SDK:http://open.weibo.com/wiki/SDK。 | ||
+ | |||
+ | |||
+ | *3,如何查询应用的access_token有效期是多少? | ||
+ | **1)桌面客户端、手机客户端类应用,测试:1天、尽审核:7天、审核后并上广场展示后:90天。 | ||
+ | **2)非客户端类应用,测试1天、普通7天、中级15天、高级30天、合作90天。 | ||
+ | |||
+ | |||
+ | *4,如何申请延长应用的access_token有效期? | ||
+ | **1)桌面客户端、手机客户端类应用,未审核应用在应用控制台申请审核通过后7天,如需要达到90天有效期,审核通过后在申请广场审核。 | ||
+ | **2)非客户端类应用,未审核应用在应用控制台申请审核通过后为普通级别7天, 如需申请更高级别,在应用控制台“接口管理”-->“调用频次”中进行申请。 | ||
+ | |||
+ | |||
+ | *5,如何计算某个用户的access_token过期时间? | ||
+ | **1)用户授权时,oauth2/access_token接口返回的expires_in(单位:秒)值就是access_token的生命周期。 | ||
+ | **2)从上述对应表中,找到应用所对应的授权有效期,过期时间 = 用户授权时间 + 授权有效期。 | ||
+ | **应用的授权有效期可以访问接口访问权限说明或在应用控制台查看。 | ||
+ | |||
+ | |||
+ | *6,access_token过期后怎么处理? | ||
+ | **access_token过期调用接口时,平台会返回错误码为21332的错误,此时需要引导用户重新进行授权。建议在每次获得用户授权时保存过期时间,再每次调用接口前判断用户access_token是否过期。 | ||
+ | **引导已授权用户再次授权时,如果此用户为已登录新浪微博状态,则授权页面为“一闪而过”无需用户再点击“授权”按钮,如果想让用户重新登录授权,则在调用authorize接口是传入参数:forcelogin=true,默认不填(授权页一闪而过)此参数相当于forcelogin=false。 | ||
+ | |||
+ | |||
+ | *7,已上线应用如何进行本地测试? | ||
+ | **1)应用不含高级权限或高级接口,建议申请一个普通的Appkey进行本地测试; | ||
+ | **2)应用含高级接口或高级权限,可以考虑绑定hosts指向本地测试代码进行测试。 | ||
+ | ***例如:应用redirect_uri为:[http://aa.abc.com/index.php http://aa.abc.com/index.php] ,而对应的本地地址为[http://127.0.0.1/index.php http://127.0.0.1/index.php],则您可以将测试机hosts绑定成:127.0.0.1 aa.abc.com 。 | ||
+ | |||
+ | |||
+ | *8,如何将已授权用户从OAuth1.0过度到OAuth2.0授权? | ||
+ | **应用授权方式从OAuth1.0切换到OAuth2.0时,应用的授权用户总数不变,以下是进行用户过度的两个建议: | ||
+ | ***a)直接上线OAuth2.0授权版本,OAuth2.0获取access_token时返回用户的uid,根据此uid判断该用户为老用户或新用户,新增或更新数据库中用户access_token等信息; | ||
+ | ***b)使用get_oauth2_token接口换取OAuth2.0的access_token,此方法可以免去用户对OAuth2.0第一次授权,适当延长过度OAuth2.0的时间以完成a)的实现(对于授权有效期较长或客户端类应用可以考虑此方法)。 | ||
+ | ***注意:做批量换取是需谨慎,同一个OAuth1.0的Access Token只能换取一次(多次调用将返回同一个token),过期时间从第一次换取的时候计算。 | ||
+ | |||
+ | |||
+ | *9,切换时是否需要添加测试帐号? | ||
+ | **1)测试帐号仅对未审核应用限制,如果您的应用在V1时已经审核通过,则无需添加测试用户。 | ||
+ | **2)如果您使用了未审核的Appkey进行测试,需要您在应用或网站控制台“应用信息”或“网站信息”-->“测试帐号”中添加测试帐号,未审核应用只有应用创建者与测试帐号才能调用接口。 | ||
+ | |||
+ | |||
+ | *10,阅读完切换指南后仍有问题怎么办? | ||
+ | **将问题通过评论的方式发送到@微博API 与切换相关的微博下,我们将一一解答。 | ||
+ | |||
+ | |||
+ | |||
+ | *其他问题详见:[[ 接口问题|接口问题FAQ]]。 | ||
+ | |||
+ | |||
===V1接口切换到V2接口=== | ===V1接口切换到V2接口=== | ||
− | + | 在实现OAuth2.0授权后,接下来需要将应用使用的V1版接口对应迁移到V2版接口。此时需要根据新接口的调用地址、调用方式、参 | |
+ | 数、返回值、错误信息处理来进行代码的改造。 | ||
+ | |||
+ | |||
+ | 以下是V2版接口与V1版接口的对应列表,部分旧版接口由于用户投诉或性能等原因已不再提供,同时新版接口提供丰富的高级接口开放优质应用申请,您可以直接在应用控制台中提交高级接口申请。 | ||
+ | |||
+ | |||
+ | 如果现有接口未能满足您的需求,欢迎@微博API 进行反馈,我们将根据开发者需求强度及微博用户利益权衡适度开放。 | ||
+ | |||
<div class="wiki_kit"> | <div class="wiki_kit"> |
2012年8月14日 (二) 17:34的版本
新接口切换概述
随着开放平台地进一步开放,V1版接口(旧版接口)无论性能、功能都已经无法满足广大开发者的需求,因此微博开放平台对V1版接口进行了全面地升级得到全新的V2版接口(新版接口)。
而原有的V1版接口将在近期全面下线,本文将为所有仍使用V1版接口的已审核上线应用提供切换引导,帮助您更快地完成切换。
为什么要升级到V2版接口
V2版较V1版接口的优势
- 1、更多功能
- a)V2较V1新增约200个接口,增强的关系接口、推荐接口、搜索话题接口、短链接口、热门微博接口、位置服务接口、通知接口、通用服务接口、社交电视接口;
- b)另外,SCOPE授权功能、好友分组接口、邀请接口、社交化接口也即将开放。
- 2、更高效
- a)微博、评论、用户等返回值增加trim开关;
- b)微博评论、转发数可以随微博返回值直接返回;
- c)用户返回值增加互粉好友数、是否关注我、是否被我关注等信息;
- d)timeline类接口未来将全部增加筛选过滤功能(feature)和应用隔离功能(base_app)。
- 3、更规范
- a)统一参数、返回值字段,全部小写字母,单词和单词之间用“_”链接;
- b)核心字段:微博、评论、用户、关系全部标准化;
- c)统一的新错误返回值格式及错误码,V2错误码地址:http://open.weibo.com/wiki/Error_code。
- 4、更可控
- a)放弃rest风格的接口URI,全部采用:域+版本号+资源类+接口名+返回值格式+参数,如图:
- b)将接口分为两级权限:普通、高级,使得优质应用得以使用更高级接口;
- c)添加了接口授权管理系统:接口可以分组打包,并对应用开放权限申请及授权管理;
V1禁止调用时间
- 1、2012年7月24日,禁止所有“未审核应用”调用V1接口;
- 2、2012年8月25日,禁止所有用户量在1000以下的“已审核应用”调用V1接口;
- 3、2012年9月前后,禁止所有应用调用V1接口;
V1到V2怎么切换
简述
V1切换到V2主要需要完成OAuth1.0到OAuth2.0的过度及完成V1原有接口与V2中新接口的对应替换。
切换时需要完成的工作
- 1、授权方式的切换,OAuth1.0升级到OAuth2.0;
- 2、切换注意事项及常见问题解决建议;
- 3、新旧接口的切换,接口调用地址、调用方式、参数、返回值、错误信息处理的代码改造;
OAuth1.0升级到OAuth2.0
- 1、OAuth2.0简述
- OAuth2.0是较OAuth1.0更简单更安全的授权方式,同时支持Web,桌面和移动应用。是未来新浪微博开放平台最主要的用户身份验证和授权方式。
- 2、切换前准备
- 请先阅读OAuth2.0开发指南。
- OAuth2.0授权方式与OAuth1.0相比,引入授权回调页与绑定域名,简化了授权流程,同时也提升了授权的安全性。
- 在实现OAuth2.0授权方式前,针对不同的应用我们需要设置应用的授权回调页或进行域名的绑定,用于获得授权成功后返回的code,再通过code获取access_token。
- 使用开发者帐号登录http://open.weibo.com,进入“我的应用”控制台需要切换的应用进行设置:
- 1)网站接入类
- 点击控制台导航“网站信息”,在网站基本信息中查看网站域名。如果您的网站应用还未验证所有权,会提示您进行所有权验证,点击进入验证页面完成所有权验证。
- 注意:验证时填写的网站域名即为您的应用的绑定域名
- 2)站内应用
- 站内应用已经是OAuth2.0授权方式,无需做改动。
- 2)站内应用
- 3)客户端应用 & 其他应用
- 点击控制台导航“应用信息”—> “高级信息”,进行授权回调页或域名的绑定。设置回调页不需要二审,方便您进行测试开发。绑定域名需要进行二审,二审时线上应用不受影响,绑定域名增加应用的安全性,同时该域名下的所有页面都可作为授权回调页。
- 注意:客户端也需要设置授权回调页或绑定域名,在程序中以webview的方式进行调用授权页面返回code,具体实现参考相应的客户端SDK:http://open.weibo.com/wiki/SDK 。
- 3)客户端应用 & 其他应用
- 3、OAuth2.0授权实现
- 主要流程(请先阅读OAuth2.0开发指南):
- 1)引导需要授权的用户访问如下地址:
https://api.weibo.com/oauth2/authorize?client_id=YOUR_APP_KEY&response_type=code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
- 注意:redirect_uri必须为绑定域名下网页或设置的回调地址。
- 本地测试技巧:可以通过绑定hosts指向本地测试代码。例如,您应用的redirect_uri为:http://aa.abc.com/index.php ,而您对应的本地地址为http://127.0.0.1/index.php,则您可以将hosts绑定成:127.0.0.1 aa.abc.com 。
- 2)如果用户同意授权,页面跳转至 YOUR_REGISTERED_REDIRECT_URI/?code=CODE
- 注意:每次返回的code值都是不一样的且在换取access_token后失效。
- 3)使用code换取access_token
https://api.weibo.com/oauth2/access_token?client_id=YOUR_ APP_KEY &client_secret=YOUR_APP_SECRET&grant_type=authorization_code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&code=CODE
- 注意:必须使用POST方式提交,其中client_id=YOUR_APP_KEY&client_secret=YOUR_APP_SECRET可以使用basic方式加入header中。
- 4)使用获得的OAuth2.0 Access Token调用API
- 读取接口一般使用GET方式提交,如:
https://api.weibo.com/2/statuses/home_timeline.json?access_token=SlAV32hkKG&count=20
- 写入接口必须使用POST方式提交,如:
切换中常见问题
- 1,怎么申请客户端的验证授权(Resource Owner Password Credentials)方式?
- 因为OAuth2.0的客户端验证授权会获得用户明文密码,所以实行有限开放。
- 申请条件:
- 1)应用分类属于桌面客户端、手机客户端。
- 2)应用本身已经通过开放平台文案、广场审核,并在广场上展示超过15天。
- 3)应用使用人数在30000以上。
- 4)应用本身功能与新浪微博关联紧密。
- 满足条件后在应用控制台的“接口管理”-->“授权机制”中申请。
- 2,手机客户端、PC客户端应用是否需要设置回调页?
- 需要,使用Web应用的验证授权(Authorization Code)方式的客户端也需要设置授权回调页或绑定域名,在程序中以webview的方式进行调用授权页面返回code,具体实现参考相应的客户端SDK:http://open.weibo.com/wiki/SDK。
- 3,如何查询应用的access_token有效期是多少?
- 1)桌面客户端、手机客户端类应用,测试:1天、尽审核:7天、审核后并上广场展示后:90天。
- 2)非客户端类应用,测试1天、普通7天、中级15天、高级30天、合作90天。
- 4,如何申请延长应用的access_token有效期?
- 1)桌面客户端、手机客户端类应用,未审核应用在应用控制台申请审核通过后7天,如需要达到90天有效期,审核通过后在申请广场审核。
- 2)非客户端类应用,未审核应用在应用控制台申请审核通过后为普通级别7天, 如需申请更高级别,在应用控制台“接口管理”-->“调用频次”中进行申请。
- 5,如何计算某个用户的access_token过期时间?
- 1)用户授权时,oauth2/access_token接口返回的expires_in(单位:秒)值就是access_token的生命周期。
- 2)从上述对应表中,找到应用所对应的授权有效期,过期时间 = 用户授权时间 + 授权有效期。
- 应用的授权有效期可以访问接口访问权限说明或在应用控制台查看。
- 6,access_token过期后怎么处理?
- access_token过期调用接口时,平台会返回错误码为21332的错误,此时需要引导用户重新进行授权。建议在每次获得用户授权时保存过期时间,再每次调用接口前判断用户access_token是否过期。
- 引导已授权用户再次授权时,如果此用户为已登录新浪微博状态,则授权页面为“一闪而过”无需用户再点击“授权”按钮,如果想让用户重新登录授权,则在调用authorize接口是传入参数:forcelogin=true,默认不填(授权页一闪而过)此参数相当于forcelogin=false。
- 7,已上线应用如何进行本地测试?
- 1)应用不含高级权限或高级接口,建议申请一个普通的Appkey进行本地测试;
- 2)应用含高级接口或高级权限,可以考虑绑定hosts指向本地测试代码进行测试。
- 例如:应用redirect_uri为:http://aa.abc.com/index.php ,而对应的本地地址为http://127.0.0.1/index.php,则您可以将测试机hosts绑定成:127.0.0.1 aa.abc.com 。
- 8,如何将已授权用户从OAuth1.0过度到OAuth2.0授权?
- 应用授权方式从OAuth1.0切换到OAuth2.0时,应用的授权用户总数不变,以下是进行用户过度的两个建议:
- a)直接上线OAuth2.0授权版本,OAuth2.0获取access_token时返回用户的uid,根据此uid判断该用户为老用户或新用户,新增或更新数据库中用户access_token等信息;
- b)使用get_oauth2_token接口换取OAuth2.0的access_token,此方法可以免去用户对OAuth2.0第一次授权,适当延长过度OAuth2.0的时间以完成a)的实现(对于授权有效期较长或客户端类应用可以考虑此方法)。
- 注意:做批量换取是需谨慎,同一个OAuth1.0的Access Token只能换取一次(多次调用将返回同一个token),过期时间从第一次换取的时候计算。
- 应用授权方式从OAuth1.0切换到OAuth2.0时,应用的授权用户总数不变,以下是进行用户过度的两个建议:
- 9,切换时是否需要添加测试帐号?
- 1)测试帐号仅对未审核应用限制,如果您的应用在V1时已经审核通过,则无需添加测试用户。
- 2)如果您使用了未审核的Appkey进行测试,需要您在应用或网站控制台“应用信息”或“网站信息”-->“测试帐号”中添加测试帐号,未审核应用只有应用创建者与测试帐号才能调用接口。
- 10,阅读完切换指南后仍有问题怎么办?
- 将问题通过评论的方式发送到@微博API 与切换相关的微博下,我们将一一解答。
- 其他问题详见:接口问题FAQ。
V1接口切换到V2接口
在实现OAuth2.0授权后,接下来需要将应用使用的V1版接口对应迁移到V2版接口。此时需要根据新接口的调用地址、调用方式、参 数、返回值、错误信息处理来进行代码的改造。
以下是V2版接口与V1版接口的对应列表,部分旧版接口由于用户投诉或性能等原因已不再提供,同时新版接口提供丰富的高级接口开放优质应用申请,您可以直接在应用控制台中提交高级接口申请。
如果现有接口未能满足您的需求,欢迎@微博API 进行反馈,我们将根据开发者需求强度及微博用户利益权衡适度开放。
OAuth2(开发指南) | ||
---|---|---|
oauth2/authorize | 请求用户授权Token | |
oauth2/access_token | 获取授权过的Access Token | |
oauth2/get_oauth2_token | OAuth1.0的Access Token更换至OAuth2.0的Access Token |
V2中已废弃或暂未支持的V1接口 | ||
---|---|---|
user/statuses/id | 根据微博ID和用户ID跳转到单条微博页面 | |
account/update_privacy | 设置隐私信息 | |
blocks/create | 将某用户加入黑名单 | |
account/update_privacy | 设置隐私信息 | |
blocks/exists | 检测某用户是否是黑名单用户 | |
blocks/blocking | 列出黑名单用户(输出用户详细信息) | |
blocks/blocking/ids | 列出分页黑名单用户(只输出id) | |
account/update_profile_image | 更改头像 | |
account/update_profile | 更改资料 |