使用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的請求出錯，具體緣由參考上面列出的錯誤碼