2012年12月17日 星期一

Authentication

這篇說明如何用 Python SDK 去跟 Dropbox 進行認證。Dropbox 用的認證通訊協定是 OAuth 1.0 (Open Authentication Protocol)。網路上有很多的資料和 libraries 可以讓你用 OAuth 去跟 Dropbox 認證,但我們不必從零開始,因為 Dropbox 提供的 Python SDK 很簡單,只要三個步驟就可以搞定。

註: 本文內容大部份取自 Dropbox developers 網站

在開始之前,我們必須先做兩件準備工作:

第 1 件: 準備 App key 和 App secret

首先,你必須準備好 app key 和 app secret 以及 app 所用的 access type:

# Get your app key and secret from the Dropbox developer website
APP_KEY = 'INSERT_APP_KEY_HERE'
APP_SECRET = 'INSERT_SECRET_HERE'

# ACCESS_TYPE should be 'dropbox' or 'app_folder' as configured for your app
ACCESS_TYPE = 'INSERT_ACCESS_TYPE_HERE'
有關如何取得 App key 與 App secret,請參考「建立 app 取得 App key 與 App Secret」一文。
第 2 件: 建立認證用的 session 物件

接著我們必須建立一個 session 物件。session 物件主要是負責認證的工作。在建立 session 物件時,記得把 App key, App secret 和 access type 一併傳入,同時引用 Dropbox SDK 的 libraries:

# Include the Dropbox SDK libraries
from dropbox import client, rest, session

# Create a session object for holding OAuth authentication info
sess = session.DropboxSession(APP_KEY, APP_SECRET, ACCESS_TYPE)
前面提到,認證只要三個步驟,這三個步驟是:
1. 取得 request token
2. 使用者授權給 reqeust token
3. 用 request token 來交換 access token
底下說明分別說明:
Step 1: 取得 request token

取得 request token 的方法很簡單,只要呼叫 obtain_request_token 這個 SDK method 即可:

request_token = sess.obtain_request_token()
Step 2: 使用者授權給 reqeust token

取得 request token 後,接著就要請使用者授權給 app。方法是導引使用者到 Dropbox 網站取得他的同意,request token 要傳到 build_authorize_url 建立一個授權用的 URL,像這樣:

url = sess.build_authorize_url(request_token)
print "url:", url
print "Please visit this website and press the 'Allow' button, then hit 'Enter' here."
raw_input()

上面只是印出 URL 然後請使用者在授權完畢後按個 Enter 鍵,這是為了方便說明,在實際的應用中,通常我們會直接顯示 Dropbox 的認證網頁,而且可能會順便傳入一個 callback URL,以便在使用者同意授權之後就直接跳轉回到你的應用程式。

當使用者瀏覽 build_authorize_url 產生的 URL 時,Dropbox 會確認使用者以他的帳戶登入,並且呈現一個像底下這樣徵詢同意的畫面:

image

為了避免有心人士非法取得授權,Dropbox 提供的 requst token 使用壽命只有 5 分鐘,所以如果使用者沒有在 5 分鐘之內授權,request token 就會失效,必須重新取得。

Step 3: 用 request token 來交換 access token

一旦取得使用者的授權,我們就可以拿 request token 來交換 access token,方法是透過 obtain_access_token 這個 SDK method:

# This will fail if the user didn't visit the above URL and hit 'Allow'
access_token = sess.obtain_access_token(request_token)

access token 就是 app 之後用來向 Dropbox 發任何 API requests 所需的,必須妥善保存。如果把 access token 保存起來的話,你就不需要再重覆前面這些步驟,除非使用者重新安裝你的 app。

好了,認證工作完成後,接下來就簡單了,當你要存取使用者的 Dropbox 資源時,只要把 session 物件傳給 DropboxClient 就可以了。例如,當我們呼叫 account_info 時,這個 method 就會回傳一個以 dictionary 保存的使用者的帳戶資訊:

client = client.DropboxClient(sess)
print "linked account:", client.account_info()

底下是用 pprint 印出帳戶資訊的一個例子:

image

總結

當你看到這邊,你就已經學會 Dropbox API 的認證,這是使用 Dropbox API 最基本而且也是最重要的一堂課。底下是完整的範例:

參考資料

0 意見: