接口访问权限说明

接口访问权限(Scope)

通过Access Token的获取方式(详见OAuth1.0aOAuth2.0),我们可以了解到:每一个Access Token代表“一个用户”授予开放平台“一个应用”的“一系列数据访问操作权限”。这“一系列数据访问操作权限”中包含默认访问权限,以及在获取Access Token过程中传递的“scope”参数所表示的扩展权限。

在调用API时,开心网API服务会检验请求中的Access Token是否包含本API需要的权限。只有包含所需要的权限,才能正常调用该API,否则就无法正常调用。

开心网接口权限包括两类:
第一类是基本权限:也是默认访问权限,权限名为basic,第三方应用在请求获取Access Token时,所传递的“scope”参数中可以不包含basic权限,一旦用户同意授权,则basic权限会自动授予。

第二类是扩展权限:如果第三方应用需要调用的API必需用户授予扩展权限,那么在获取Access Token时,您就需要在scope参数中设定这些权限。用户会根据您设置的权限,来决定是否授予这些权限,只有得到用户授权,您才能调用相应的API。

例如:您的应用需要调用/records/add接口发一条记录,您就需要设定scope=create_records,用户授权后,您才能调用该接口。

说明:
①目前开心网API2.0可以通过Access Token或Session Key两种方式来调用,接口访问权限是针对Access Token说的;如果您开发的是“站内组件”,通过Session Key的方式调用API,您可以调用所有的开放API。
②一些API某些字段的调用,也需要设置相应权限。如/user/me接口,要获取当前用户的“介绍”资料,必需要设置scope=user_intro,详见下面的权限列表。
用户需要授权的内容越多,就越有可能做出不授权的决定。请谨慎设置scope,确保仅包含应用所调用API的scope。

权限列表

1. 用户资料权限

有三个可以获取用户详细资料的API,分别是/users/me(获取当前用户资料)、/users/show(根据UID获取多个用户的资料)、/friends/me(获取当前用户好友的资料)。这三个接口如果没有设置扩展权限,只能取到用户的基本信息(下表注明basic的属性字段)。

如果你想获取用户基本信息之外的更多资料,就需要设置scope,用户授权后才可调用。获取当前用户的更多资料,与获取好友更多资料,需设置的权限是不同的;获取当前用户更多资料需设置user_类的权限,获取好友更多资料需设置friends_类的权限。例如:获取当前用户的“生日”,需设置scope=user_birthday;而要获取好友的“生日”,则需设置scope=friends_birthday。详细权限列表见下:

用户资料字段说明当前用户资料权限好友资料权限
uid用户IDbasicbasic
name用户名basicbasic
gender性别, 0/1 - 男/女basicbasic
hometown家乡basicbasic
city现居住地basicbasic
status状态 0/1/2 – 其他/学生/已工作basicbasic
logo120头像120 x 120basicbasic
logo50头像50 x 50basicbasic
birthday生日user_birthdayfriends_birthday
bodyform体型user_bodyformfriends_bodyform
blood血型user_bloodfriends_blood
marriage婚姻状态user_marriagefriends_marriage
trainwith希望结交user_introfriends_intro
interest兴趣爱好user_introfriends_intro
favbook喜欢的书籍user_introfriends_intro
favmovie喜欢的电影user_introfriends_intro
favtv喜欢的电视剧user_introfriends_intro
idol偶像user_introfriends_intro
motto座右铭user_introfriends_intro
wishlist愿望列表user_introfriends_intro
intro介绍user_introfriends_intro
education教育经历user_educationfriends_education
schooltype学校类型user_educationfriends_education
school学校user_educationfriends_education
class班级user_educationfriends_education
year入学年份user_educationfriends_education
career工作经历user_careerfriends_career
company公司名称user_careerfriends_career
dept所在部门user_careerfriends_career
beginyear当前工作开始年份user_careerfriends_career
beginmonth当前工作开始月份user_careerfriends_career
endyear当前工作结束年份user_careerfriends_career
endmonth当前工作结束月份user_careerfriends_career
isStar是否公共主页basicbasic

2. 其他API权限

API权限
/friends/relationshipbasic
/friends/mutual basic
/app/statusbasic
/app/friendsbasic
/app/invitedbasic
/app/rate_limit_statusbasic
/comment/createbasic
/comment/replybasic
/comment/listbasic
/comment/deletebasic
/like/createbasic
/like/cancelbasic
/like/checkbasic
/like/showbasic
/msg/summarybasic
/msg/clearbasic
/film/searchbasic
/film/watchedbasic
/film/wishbasic
/records/addcreate_records
/records/meuser_records
/records/friendsfriends_records
/records/publicbasic
/records/userfriends_records
/records/topicbasic
/records/searchbasic
/records/detailbasic
/album/createcreate_album
/album/showuser_photo friends_photo
/photo/uploadupload_photo
/photo/showuser_photo friends_photo
/message/sendsend_message
/message/inboxuser_messagebox
/message/outboxuser_messagebox
/message/replysend_message
/rgroup/group_create create_rgroup
/rgroup/talk_create create_talk
/rgroup/groups user_rgroup
/rgroup/talks user_rgroup
/rgroup/members user_rgroup
/rgroup/notices user_rgroup
/rgroup/notice_detail user_rgroup
/rgroup/photos user_rgroup
/rgroup/photo_detail user_rgroup
/repaste/createcreate_repaste
/repaste/meuser_repaste
/repaste/friendsfriends_repaste
/repaste/publicbasic
/repaste/userfriends_repaste
/repaste/showuser_repaste friends_repaste
/msg/summarybasic
/msg/clearbasic
/diary/createcreate_diary
/diary/meuser_diary
/diary/friendsfriends_diary
/diary/taguser_diary
/diary/userfriends_diary
/diary/showuser_diary friends_diary
/page/add_fanbasic
/board/createbasic
/board/mebasic
/board/userbasic
/board/reply_listbasic
/board/deletebasic
/user/mfriendsbasic
/user/page_listbasic
/user/visitorsbasic
/forward/createbasic
/forward/reforwardbasic
/forward/listbasic
/forward/meuser_forward
/lbs/checkinplaces_checkin
/lbs/meuser_places
/lbs/friendfriends_places
/lbs/near_friendsfriends_places
/lbs/near_usersbasic
/lbs/photobasic
/lbs/createplaces_checkin
/film/searchbasic
/film/watchedbasic
/film/wishbasic
/gamenotice/setbasic
/gamenotice/updatebasic
/vote/replybasic
/vote/postbasic
/vote/feedbasic
/vote/friendbasic
/vote/mypostbasic
/vote/mebasic
/vote/detailbasic
/vote/newlistbasic
/vote/hotbasic
/gift/listbasic
/gift/sendbasic
/gift/recivedbasic
/gift/deliveredbasic

说明:
①类似/album/show获取用户照片专辑列表的接口,既可以获取当前用户照片专辑列表,又可以获取好友照片专辑列表,因此您在调用类似接口时,需要根据您的应用功能情况,选择设置一个或两个权限。
②如需设置多个权限,请用半角空格分隔。如scope=user_photo friends_photo。
③每个接口的说明文档中都有关于权限的说明,请在开发时特别注意。

请求示例

1. OAuth1.0a如何设置scope:

  http://api.kaixin001.com/oauth/request_token
  ?oauth_consumer_key=69938658024667b0f57dc661d91a707e
  &oauth_nonce=8a6bf95de0b306a4456dfa7855f514ee
  &oauth_signature=gtzVil5%2BWZJmKYydm%2F9anzxaqhs%3D
  &oauth_signature_method=HMAC-SHA1
  &oauth_timestamp=1310108207
  &oauth_token=419e5493e1dcd7920cec1df39a868a
  &oauth_version=1.0
  &scope=basic create_records

2. OAuth2.0如何设置scope:

  http://api.kaixin001.com/oauth2/authorize?response_type=code
  &client_id=Va5yQRHlA4Fq4eR3LT0vuXV4
  &redirect_uri=http%3A%2F%2Fwww.example.com%2Foauth_redirect
  &scope=basic create_records
  &display=popup

注意:basic可有可无,是默认权限;多个scope权限之间用一个半角空格分隔。


接口访问频次(Ratelimit)

开心API接口限制用户每个小时只能请求一定的次数。限制分APP维度、用户维度,详细说明如下:

一个APP全部用户访问次数限制

普通授权(供开发者完成应用开发与调试):
1000次请求/小时

中级授权:
10,000次请求/小时

高级授权:
500,000次请求/小时

开心网合作方授权:
10,000,000次请求/小时

注意:未审核通过的APP均为普通授权,审核通过后更新为中级授权;高级和合作授权需要跟开放平台联系开通,  详细方法见下。

查询剩余请求数

针对一个用户在使用一个应用一小时的请求次数限制

API权限普通 高级 合作
/friends/add basic 5 10 20 100
/records/add create_records 50* 10 20 100
/album/create create_album 5 10 20 100
/photo/upload upload_photo 50 100 200 300
/game_friends/request basic 5 10 20 100
/message/send send_message 5 10 20 100
/message/reply send_message 5 10 20 100
/rgroup/talk_create create_talk 5 10 20 100
/comment/create basic 50 100 200 300
/comment/reply basic 50 100 200 300
/like/create basic 50 100 200 300
/like/cancel basic 50 100 200300
/repaste/create create_repaste 5 10 20 100
/repaste/addtag create_repaste 5 10 20 100
/repaste/interact create_repaste 5 10 20 100
/diary/create create_diary 5 10 20 100
/board/create basic 5 10 20 100
/feed/send send_feed 5 10 20 50
/sysnews/invitation send_invitation 5 10 2050
/sysnews/send send_sysnews 1 1 110
/forward/create basic 5 10 20 50
/dialog/feed /5 10 2050
/dialog/invitation/1002005001000
/dialog/sysnews/1002005001000
/dialog/pay/50 100 120150
/lbs/checkin places_checkin 5 10 20 50
/lbs/create places_checkin 5 10 20 50
/film/watched basic5 10 2050
/film/wish basic 5 10 20 50

备注:
① 发记录/records/add接口,为了方便调试,将普通等级的限制调高为50次
② 当频次权限达到本级别的上限时,可以提出更高级别授权的申请(仅限于普通至高级授权)。申请时,请将应用名称、App ID / API Key、应用介绍、功能策略等一起发送邮件到app@corp.kaixin001.com
提交申请的时候,应包含如下内容:
企业:
1. 营业执照副本复印件
2. 税务登记副本复印件
3. 应用说明文档:包括产品介绍、运营/推广策略、改进目标及方案等
个人:
1. 开发者身份证复印件
2. 应用说明文档:包括产品介绍、运营/推广策略、改进目标及方案等

未通过审核应用的测试账号限制

针对未通过审核的、开发中的应用,我们除了以上的频次限制外,将还有测试账号的额外请求限制。每个未通过审核应用只能授权10个测试账号来请求接口。除此之外的账号通过该应用,都无法请求接口。当应用通过审核,该限制自动取消。

测试账号可以在 开心网开放平台首页-我的应用 里找到,可以通过“修改组件信息”修改测试UID。

开发者如何正确面对频次限制

开心网API技术原理上是一个HTTP轮询(POLLING)协议,不是即时推送(realtime push)协议。因此即使增大刷新频率也无法完全达到即时获得最新信息效果。根据经验,更新频率我们建议2-3分钟/次为宜,API客户端也可提供一个手工刷新按钮,用户可以手工获取最新数据。

API客户端可以智能控制请求频率,比如最近几次更新都没获取到数据情况下可以适当将间隔时间延长。当一小时内剩余次数多时候可以适当将更新加快。当剩余请求数偏小时,客户端通过延长自己的更新频率控制不超过上限。另外要适当留一些空余指标,防止用户手工执行一些操作产生的调用导致超出上限。

客户端可以通过以下接口查询当前剩余请求数/app/rate_limit_status