use oauth2.0 access douban APIs

1. 使用OAuth2.0访问豆瓣API
Contents
1. 使用OAuth2.0访问豆瓣API
2. 授权流程
1. user-agent flow
2. server-side flow 与 native-application flow
3. access_token有效期 与 refresh_token
4. 基于密码的高级授权方式
5. 访问速度控制
6. 错误代码
豆瓣支持OAuth2.0协议的授权访问。关于OAuth2.0协议规范，请参考这里。
使用OAuth2.0的流程可以简单概括为：
1. 应用向豆瓣请求授权
2. 豆瓣为用户显示一个授权页面，用户在此页面确认是否同意应用的请求
3. 如果用户同意授权，应用会获取到一个访问令牌(access_token)，通过此令
牌，应用可以访问授权用户的数据。
豆瓣支持三种OAuth2.0的授权流程：
直接在浏览器中运行的Javascript应用的授权流程（user-agent flow）
有服务器的WEB应用的授权流程（server-side flow）
桌面客户端应用、移动客户端应用的授权流程（native-application flow）
授权流程
user-agent flow
获取access_token
通过在浏览器中访问下面的地址，来引导用户授权，并获得access_token
https://www.douban.com/service/auth2/auth
参数：
参数名称 参数说明
client_id 必选参数，应用的唯一标识，对应于APIKey

2. 必选参数，用户授权完成后的回调地址，应用需要通过此
redirect_uri 回调地址获得用户的授权结果。此地址必须与在应用注册
时填写的回调地址一致。
必选参数，此值可以为 code 或者 token 。在本流程中，此
response_type
值为 token
可选参数，申请权限的范围，如果不填，则使用缺省的
scope
scope。如果申请多个scope，使用逗号分隔。
可选参数，用来维护请求和回调状态的附加字符串，在授
state 权完成回调时会附加此参数，应用可以根据此字符串来判
断上下文关系。
注意：此请求必须是HTTP GET方式，此流程不会生成refresh_token
例如：
https://www.douban.com/service/auth2/auth?
client_id=0b5405e19c58e4cc21fc11a4d50aae64&
redirect_uri=https://www.example.com/back&
response_type=token&
scope=shuo_basic_r,shuo_basic_w
返回结果：
当用户拒绝授权时，浏览器会重定向到redirect_uri，并附加错误信息
https://www.example.com/back?error=access_denied
当用户同意授权时，浏览器会重定向到redirect_uri，并附加access_token
https://www.example.com/back#access_token=a14afef0f66fcffce3e0fcd2e34f6ff4&expires_in=3
600
使用access_token
curl "https://api.douban.com/people/@me"
-H "Authorization: Bearer a14afef0f66fcffce3e0fcd2e34f6ff4"
server-side flow 与 native-application flow
这两种授权流程基本相同，需要通过两步来获取access_token。
获取authorization_code
通过在浏览器中访问下面的地址，来引导用户授权，并获得authorization_code
https://www.douban.com/service/auth2/auth

3. 参数：
参数名称 参数说明
client_id 必选参数，应用的唯一标识，对应于APIKey
必选参数，用户授权完成后的回调地址，应用需要通过此
redirect_uri 回调地址获得用户的授权结果。此地址必须与在应用注册
时填写的回调地址一致。
必选参数，此值可以为 code 或者 token 。在本流程中，此
response_type
值为 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
返回结果：
当用户拒绝授权时，浏览器会重定向到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 必选参数，应用的唯一标识，对应于APIKey
必选参数，用户授权完成后的回调地址，应用需要通过此回
调地址获得用户的授权结果。此地址必须与在应用注册时填

4. redirect_uri 写的回调地址一致
必选参数，此值可以为 authorization_code 或者
grant_type refresh_token 或者 password 。在本流程中，此值为
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
返回结果：
Toggle line numbers
1{
2 "access_token":"a14afef0f66fcffce3e0fcd2e34f6ff4",
3 "expires_in":3920,
4 "refresh_token":"5d633d136b6d56a41829b73a424803ec",
5 "douban_user_id":"1221"
6}
使用access_token
curl "https://api.douban.com/people/@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，需要单独申请，缺省情况下，应用没有
refresh_token使用权限。
通过refresh_token换取access_token的处理过程如下：

5. https://www.douban.com/service/auth2/token
参数名称 参数说明
client_id 必选参数，应用的唯一标识，对应于APIKey
client_secret 必选参数，应用的唯一标识，对应于APIKey
必选参数，用户授权完成后的回调地址，应用需要通过此回
redirect_uri 调地址获得用户的授权结果。此地址必须与在应用注册时填
写的回调地址一致
必选参数，此值可以为 authorization_code 或者
grant_type refresh_token 或者 password 。在本流程中，此值为
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
返回结果：
Toggle line numbers
1{
2 "access_token":"0e63c03dfb66c4172b2b40b9f2344c45",
3 "expires_in":3920,
4 "refresh_token":"84406d40cc58e0ae8cc147c2650aa20a",
5 "douban_user_id":"1000"
6}
级别 access_token有效期 refresh_token有效期 说明
L1 1天 无refresh_token
L2 30天 无refresh_token
L3 30天 60天
基于密码的高级授权方式
https://api.douban.com/auth2/token

6. 参数名称 参数说明
client_id 必选参数，应用的唯一标识，对应于APIKey
client_secret 必选参数，应用的唯一标识，对应于APIKey
必选参数，用户授权完成后的回调地址，应用需要通过此回
redirect_uri 调地址获得用户的授权结果。此地址必须与在应用注册时填
写的回调地址一致
必选参数，此值可以为 authorization_code 或者
grant_type refresh_token 或者 password 。在本流程中，此值为
password
username 必选参数，用户名
password 必选参数，密码
注意：此请求必须是HTTP POST方式
例如：
https://www.douban.com/service/auth2/token?
client_id=2342hljkhafh323&
client_secret=2342hljkhafh323&
redirect_uri=https://www.example.com/back&
grant_type=password&
username=test@douban.com&
password=mypassword
返回结果：
Toggle line numbers
1{
2 "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
3 "expires_in":3920,
4 "refresh_token":"1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ",
5 "douban_user_id":"1000"
6}
访问速度控制
在用户、应用、服务器IP、scope等维度对接口的访问速度进行限制。
针对服务器IP:
级别 限制
L1 5000次/小时
L2 10000次/小时
L3 20000次/小时

7. 针对单用户每应用每scope：
级别 限制
L1 60次/小时
L2 150次/小时
L3 300次/小时
错误代码
如果在API使用过程中，有错误，则返回结果为：
Toggle line numbers
1{
2 "code":113,
3 "msg":"required_parameter_is_missing: client_id",
4 "request":"GET /shuo/statuses/232323"
5}
错误
错误说明
代码
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不匹配

8. 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 用户已被屏蔽
access_token_has_expired_since_password_changed 因用户修改密
123
码而导致access_token过期
124 access_token_has_not_expired access_token未过期
999 unknown 未知错误