Google Data API 團隊 Eric Bidelman
2008 年 9 月
簡介
對開發人員來說，這真是太棒了！我們開始看到許多網路標準採用於網路，Google 一直以來都擁有龐大的標準和培養開放原始碼社群。
最近，所有 Google Data API 都支援 OAuth，這是一種開放式通訊協定，旨在標準化電腦版和網路應用程式存取使用者私人資料的方式。OAuth 可讓您以標準安全的方式執行 API 驗證。身為程式設計師，我們教導了盡可能重複使用程式碼。OAuth 可協助開發人員減少編寫的重複程式碼數量，並更輕鬆地建立適用於多種不同服務供應商的多項服務的工具。
目標對象
本文假設您已熟悉一或多個 Google Data API，但不一定是 OAuth 背後的概念。如果您才剛開始使用 Chrome，或只是想要瞭解 OAuth，請再接再厲。本文將提供概念的基礎。我也會討論 Google OAuth 的實作詳細資訊。
本文的適用對象為熟悉 AuthSub 的開發人員，特別是已註冊進階安全性模式的開發人員。 在此同時，我會盡量凸顯這兩種通訊協定的相似度和差異。如果您的應用程式使用 AuthSub，您可以利用此資訊來遷移至 OAuth，這是一個新的開放式通訊協定。
有點術語
瞭解 OAuth 的重點在於理解其術語。 OAuth 規格和 Google 的網路應用程式 OAuth 驗證說明文件非常依賴特定定義，因此讓我們能詳細瞭解 Google 的 OAuth 實作方式。
- 「OAuth 舞蹈」
我用於說明完整的 OAuth 驗證/授權程序的非官方用語。
- (OAuth) 要求憑證
這個初始符記可讓 Google 瞭解您的應用程式要求存取其中一個 Google Data API。OAuth 舞的第二個步驟是讓使用者手動授予資料的存取權。如果這個步驟成功，要求權杖就會獲得授權。
- (OAuth) 存取憑證
最後一步是將授權要求憑證轉換為存取憑證。應用程式取得這個憑證後，除非撤銷憑證，否則使用者不必再次執行 OAuth 舞蹈。
與 AuthSub 相似：
OAuth 存取憑證與安全 AuthSub 工作階段憑證相同。 - (OAuth) 端點
這些是驗證應用程式並取得存取權杖所需的 URI。共有三個步驟，每個步驟都是 OAuth 程序的每個步驟。 Google 的 OAuth 端點如下：
取得要求憑證： https://www.google.com/accounts/OAuthGetRequestToken授權要求憑證： https://www.google.com/accounts/OAuthAuthorizeToken升級為存取憑證： https://www.google.com/accounts/OAuthGetAccessToken與 AuthSub 相似：
變更存取權杖的授權要求權杖與將一次性使用 AuthSub 憑證分別升級至https://www.google.com/accounts/AuthSubRequestToken和https://www.google.com/accounts/AuthSubSessionToken的長效工作階段符記相似。差別在於 AuthSub 沒有初始要求憑證的概念。而是從AuthSubRequestToken授權頁面啟動憑證程序。 - (OAuth) 服務供應商
在 Google Data API 中，該供應商為 Google。服務供應商通常會用來提供提供 OAuth 端點的網站或網站服務。 OAuth 服務供應商的另一個例子是 MySpace。
- (OAuth) 消費者
要求存取使用者資料 (即您的應用程式) 的程式。OAuth 通訊協定有彈性，因為它支援多種不同類型的用戶端 (網頁、已安裝、桌上型電腦、行動裝置)。
注意：雖然 OAuth 通訊協定支援桌面版/安裝版應用程式，但 Google 僅支援網路應用程式的 OAuth。
開始使用
註冊
您必須進行一些設定，才能開始透過 Google Data API 使用 OAuth。由於「所有」OAuth 要求都必須進行數位簽署，因此您必須先註冊網域，然後將公開憑證上傳到 Google。如要進一步瞭解相關做法，請參閱網頁式應用程式的註冊和產生已註冊註冊模式的金鑰和憑證一節。
簽署要求
當您註冊網域後，就可以開始簽署要求。OAuth 的最棘手概念之一，就是如何正確建構 oauth_signature 以及簽名基礎字串的概念。基礎字串是您使用私密金鑰 (使用 RSA_SHA1) 簽署的資料。結果是您為 oauth_signature 設定的值。
要求範例
GET 使用者在 http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 擁有的 Google 日曆清單
| 基本字串格式 | base_string = http-method&base-http-request-url&normalized-string-of-oauth_parameters |
|---|---|
| 基本字串範例 | GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime |
| HTTP 要求範例 |
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1 Host: http://www.google.com Content-Type: application/atom+xml Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9AvZbTSMK%2FPY%3D...", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d", oauth_version="1.0" |
注意：這僅供參考，您的oauth_signature將大幅增加。
基本字串的注意事項：
orderby=starttime查詢參數會和提出其他的oauth_*參數，並按字母順序值排序。- 此字串不包含「?」字元。
base-http-request-url部分僅包含經過網址編碼的基礎網址：http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull。oauth_token採用雙重網址編碼。
「Authorization」標頭的附註：
oauth_*參數的排序在Authorization標頭中並沒有影響。- 標頭中的
orderby=starttime不會與基礎字串一樣。這個查詢參數會成為請求網址的一部分。
如要進一步瞭解如何使用 OAuth 簽署要求，請參閱簽署 OAuth 要求。
與 AuthSub 的差異：
以下舉例說明使用安全 AuthSub 的相同範例：
| 基本字串格式 | base_string = http-method http-request-URL timestamp nonce |
|---|---|
| 基本字串範例 |
GET http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull%3Forderby%3Dstarttime 137131200 4572616e48616d6d |
| HTTP 要求範例 |
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1 Host: http://www.google.com Content-Type: application/atom+xml Authorization: AuthSub token="GD32CMCL25aZ-v____8B" data="GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime 137131200 4572616e48616d6d" sig="MCwCFrV93K4agg==..." sigalg="rsa-sha1" |
如要進一步瞭解如何使用 AuthSub 簽署要求，請參閱簽署 AuthSub 要求。
OAuth Playground 工具
目的
部分使用者建議 OAuth 有很大的學習曲線。相較於 Google 的其他驗證 API，我同意。當您擴充應用程式以使用其他 (非 Google 服務) 服務時，OAuth 的優勢會顯而易見。您只要編寫一段適用於不同服務供應商及其 API 的驗證碼，就很適合使用。 我們稍後會說明您如何學習通訊協定。
我建立的是 OAuth Playground 工具，可協助開發人員破解 OAuth 設定。 您可以使用 Playground 協助偵錯、檢查自己的實作項目，或利用 Google Data API 進行實驗。
這個選項的功能
- 說明 OAuth 驗證流程：擷取要求憑證、授權憑證，並將其升級為存取權杖。
- 顯示每個要求的正確簽名基本字串。
- 顯示每個要求的正確
Authorization標頭。 - 示範如何使用
oauth_token與通過驗證的 Google 資料動態饋給互動。 您可以GET/POST/PUT/DELETE資料。 - 直接在瀏覽器中查看已驗證的資訊提供。
- 可讓您測試自己的
oauth_consumer_key(已註冊網域) 和私密金鑰。 - 瞭解您的
oauth_token可用的 Google 資料動態饋給服務。
示範執行
步驟 1：選擇範圍首先，請選擇一或多個範圍，決定要使用的 API。在這個示範中，我申請的是可和 Blogger 和 Google 聯絡人搭配使用的權杖。 與 AuthSub 相似： |
|
步驟 2：修改 OAuth 參數和設定目前，請勿修改 [修改 OAuth 參數] 方塊中的任何設定。之後，您只要將 注意： 除了 與 AuthSub 的差異： |
 |
步驟 3-5：取得存取憑證取得 OAuth 存取憑證需要三個步驟。第一步是擷取要求憑證。讓 Google 知道您的應用程式正在啟動 OAuth 舞蹈。 首先，按一下 [取得憑證] 方塊中的 [要求憑證] 按鈕。 某些欄位會填入資料。
|
|
|
接下來，按一下 [取得憑證] 方塊中的 [授權] 按鈕。 在這個授權頁面上，按一下 [授予存取權] 按鈕以授權要求權杖，並重新導向至 OAuth Playground。 與 AuthSub 相似： 與 AuthSub 的差異： 提示：如果您要編寫網路應用程式，建議指定 |
|
|
最後，按一下 [取得憑證] 方塊中的 [存取憑證] 按鈕。 這個動作會升級授權要求憑證 (如紅色的「存取權杖」標籤所示)。 如果您想要擷取新權杖，請按一下 [重新開始] 以重新執行 OAuth 舞蹈。 現在我們可以做點有趣的事情了！ |
|
使用存取權杖
您現在可以查詢、插入、更新或刪除資料了。使用實際資料時，請務必執行最後三種 HTTP 方法！
提示：如要尋找可存取的存取憑證，請按一下 [可用的動態消息] 按鈕。
以下是查詢範例：GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3
這個範例最多只能傳回 3 個特定網誌上的文章。您也可以直接在瀏覽器中查看傳回的動態饋給/項目，方法是按一下語法醒目顯示區域下方的 [在瀏覽器中查看] 連結。
範例：如何更新訊息
- 找出你要更新文章的 rel="edit"，然後找出含有
<link>的元素。如下所示：<link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>
在「輸入 Google 資料動態饋給」輸入內容中貼上 href 網址。
- 按一下語法醒目顯示面板頂端的 [檢視純文字]，複製現有項目的 XML。只複製回應內文，不要複製標頭。
- 將 HTTP 方法下拉式選單變更為
PUT。 - 點選下拉式選單下方的 [輸入訊息資料]，然後將
<entry>XML 貼到彈出式視窗中。 - 按一下 [執行] 按鈕。
伺服器會傳回 200 OK。
提示：請不要手動複製 edit 連結，而是取消勾選 [語法醒目顯示方式] 核取方塊。查詢完畢之後，您只要按一下 XML 回應主體中的連結即可。
結語
AtomPub/Atom 發布通訊協定 (Google Data API 的基本通訊協定) 和 OAuth 等技術有助於推動網路向前發展。隨著越來越多網站開始採用這些標準，開發人員也會成為贏家。要尋找殺手級應用程式，幾乎不容易下手。
如果您對 OAuth Playground 有任何疑問或意見，或者可以使用 OAuth 搭配 Google API，請造訪 G Suite API 和 Marketplace API 支援論壇。