使用OAuth2.0访问豆瓣API

如何计算某个用户的access_token过时时间？
开发者能够经过两种方式计算：
用户受权时，oauth2/access_token接口返回的expires_in值就是access_token的生命周期。
从上述对应表中，找到应用所对应的受权有效期，过时时间 = 用户受权时间 + 受权有效期

使用OAuth2.0访问豆瓣API

豆瓣支持OAuth2.0协议的受权访问。关于OAuth2.0协议规范，请参考这里。

使用OAuth2.0的流程能够简单归纳为：

1. 应用向豆瓣请求受权
2. 豆瓣为用户显示一个受权页面，用户在此页面确认是否赞成应用的请求
3. 若是用户赞成受权，应用会获取到一个访问令牌(access_token)，经过此令牌，应用能够访问受权用户的数据。
4. 若是访问须要受权的Api，请使用https协议，加上access_token的Header，具体见获取access_token

豆瓣支持三种OAuth2.0的受权流程：

• 服务器的WEB应用的受权流程（server-side flow）
• 桌面客户端应用、移动客户端应用的受权流程（native-application flow）
• 直接在浏览器中运行的Javascript应用的受权流程（user-agent flow）

flow 与 native-application flow

这两种受权流程基本相同，须要经过两步来获取access_token。

获取authorization_code

经过在浏览器中访问下面的地址，来引导用户受权，并得到authorization_code

https://www.douban.com/service/auth2/auth

参数：

参数名称	参数说明
client_id	必选参数，应用的惟一标识，对应于APIKey
redirect_uri	必选参数，用户受权完成后的回调地址，应用须要经过此回调地址得到用户的受权结果。此地址必须与在应用注册时填写的回调地址一致。
response_type	必选参数，此值能够为 code 或者 token 。在本流程中，此值为 code
scope	可选参数，申请权限的范围，若是不填，则使用缺省的scope。若是申请多个scope，使用逗号分隔。
state	可选参数，用来维护请求和回调状态的附加字符串，在受权完成回调时会附加此参数，应用能够根据此字符串来判断上下文关系。

注意：此请求必须是HTTP GET方式

例如：

https://www.douban.com/service/auth2/auth?
  client_id=0b5405e19c58e4cc21fc11a4d50aae64&
  redirect_uri=https://www.example.com/back&
  response_type=code&
  scope=shuo_basic_r,shuo_basic_w,douban_basic_common

返回结果：

• 当用户拒绝受权时，浏览器会重定向到redirect_uri，并附加错误信息

  https://www.example.com/back?error=access_denied

• 当用户赞成受权时，浏览器会重定向到redirect_uri，并附加autorization_code

  https://www.example.com/back?code=9b73a4248

获取access_token

https://www.douban.com/service/auth2/token

参数名称	参数说明
client_id	必选参数，应用的惟一标识，对应于APIKey
client_secret	必选参数，应用的惟一标识，对应于豆瓣secret
redirect_uri	必选参数，用户受权完成后的回调地址，应用须要经过此回调地址得到用户的受权结果。此地址必须与在应用注册时填写的回调地址一致
grant_type	必选参数，此值能够为 authorization_code 或者 refresh_token 。在本流程中，此值为 authorization_code
code	必选参数，上一步中得到的authorization_code

注意：此请求必须是HTTP POST方式

例如：

https://www.douban.com/service/auth2/token?
  client_id=0b5405e19c58e4cc21fc11a4d50aae64&
  client_secret=edfc4e395ef93375&
  redirect_uri=https://www.example.com/back&
  grant_type=authorization_code&
  code=9b73a4248

返回结果：

{
  "access_token":"a14afef0f66fcffce3e0fcd2e34f6ff4",
  "expires_in":3920,
  "refresh_token":"5d633d136b6d56a41829b73a424803ec",
  "douban_user_id":"1221"
}

使用access_token

curl "https://api.douban.com/v2/user/~me"
     -H "Authorization: Bearer a14afef0f66fcffce3e0fcd2e34f6ff4"

access_token有效期 与 refresh_token

在OAuth2.0中，access_token再也不长期有效。在受权获取access_token时会一并返回其有效期，也就是返回值中的expires_in参数。

在access_token使用过程当中，若是服务器返回106错误：“access_token_has_expired ”，此时，说明access_token已通过期，除了经过再次引导用户进行受权来获取access_token外，还能够经过refresh_token的方式来换取新的access_token和refresh_token。

经过refresh_token换取access_token的处理过程以下：

https://www.douban.com/service/auth2/token

参数名称	参数说明
client_id	必选参数，应用的惟一标识，对应于APIKey
client_secret	必选参数，应用的惟一标识，对应于豆瓣secret
redirect_uri	必选参数，用户受权完成后的回调地址，应用须要经过此回调地址得到用户的受权结果。此地址必须与在应用注册时填写的回调地址一致
grant_type	必选参数，此值能够为 authorization_code 或者 refresh_token。在本流程中，此值为 refresh_token
refresh_token	必选参数，刷新令牌

注意：此请求必须是HTTP POST方式，refresh_token只有在access_token过时时才能使用，而且只能使用一次。当换取到的access_token再次过时时，使用新的refresh_token来换取access_token

例如：

https://www.douban.com/service/auth2/token?
  client_id=0b5405e19c58e4cc21fc11a4d50aae64&
  client_secret=edfc4e395ef93375&
  redirect_uri=https://www.example.com/back&
  grant_type=refresh_token&
  refresh_token=5d633d136b6d56a41829b73a424803ec

返回结果：

{
  "access_token":"0e63c03dfb66c4172b2b40b9f2344c45",
  "expires_in":3920,
  "refresh_token":"84406d40cc58e0ae8cc147c2650aa20a",
  "douban_user_id":"1000"
}

级别	access_token有效期	refresh_token有效期	说明
L1	7天	14天
L2	30天	60天
L3	90天	180天

须要受权的Api访问速度控制

在用户、应用、服务器IP、scope等维度对接口的访问速度进行限制。

针对服务器IP:

级别	限制
L1	5000次/小时
L2	10000次/小时
L3	20000次/小时

针对单用户每应用每scope：

级别	限制
L1	500次/小时
L2	1000次/小时
L3	2000次/小时

返回结果的header里会有当前访问限制信息：

Header名称	含义
X-Ratelimit-Limit	单用户每小时次数
X-RateLimit-Remaining	单用户每小时剩余次数
X-Ratelimit-Limit2	单ip每小时次数
X-RateLimit-Remaining2	单ip每小时剩余次数

错误代码

若是在API使用过程当中，有错误，则返回结果为：

{
  "code":113,
  "msg":"required_parameter_is_missing: client_id",
  "request":"GET /shuo/statuses/232323"
}

错误代码	错误说明
100	invalid_request_scheme 错误的请求协议
101	invalid_request_method 错误的请求方法
102	access_token_is_missing 未找到access_token
103	invalid_access_token access_token不存在或已被用户删除，或者用户修改了密码
104	invalid_apikey apikey不存在或已删除
105	apikey_is_blocked apikey已被禁用
106	access_token_has_expired access_token已过时
107	invalid_request_uri 请求地址未注册
108	invalid_credencial1 用户未受权访问此数据
109	invalid_credencial2 apikey未申请此权限
110	not_trial_user 未注册的测试用户
111	rate_limit_exceeded1 用户访问速度限制
112	rate_limit_exceeded2 IP访问速度限制
113	required_parameter_is_missing 缺乏参数
114	unsupported_grant_type 错误的grant_type
115	unsupported_response_type 错误的response_type
116	client_secret_mismatch client_secret不匹配
117	redirect_uri_mismatch redirect_uri不匹配
118	invalid_authorization_code authorization_code不存在或已过时
119	invalid_refresh_token refresh_token不存在或已过时
120	username_password_mismatch 用户名密码不匹配
121	invalid_user 用户不存在或已删除
122	user_has_blocked 用户已被屏蔽
123	access_token_has_expired_since_password_changed 因用户修改密码而致使access_token过时
124	access_token_has_not_expired access_token未过时
125	invalid_request_scope 访问的scope不合法，开发者不用太关注，通常不会出现该错误
999	unknown 未知错误

HTTP状态码	说明
200	代表api的请求正常
400	代表api的请求出错，具体缘由参考上面列出的错误码