Google Data API 團隊 Eric Bidelman
2008 年 9 月
簡介
對開發人員來說，這是令人振奮的時代。我們發現網路上開始採用許多開放標準，而如您所知，Google 一向非常支持標準，並致力於促進開放原始碼社群發展。
最近，所有 Google Data API 都採用了 OAuth，這項開放式通訊協定旨在標準化桌上型電腦和網路應用程式存取使用者私人資料的方式。OAuth 提供標準且安全的方式來執行 API 驗證。程式設計師的職責是盡可能重複使用程式碼。OAuth 可協助開發人員減少重複編寫的程式碼量，並輕鬆建立可與多個服務搭配使用的工具，這些服務來自各種不同的供應商。
觀眾
本文假設您已熟悉一或多個 Google Data API，但不一定瞭解 OAuth 背後的概念。 如果您是新手，或是對 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 相似：
將授權要求權杖換成存取權杖，分別類似於在https://www.google.com/accounts/AuthSubRequestToken和https://www.google.com/accounts/AuthSubSessionToken將單次使用的 AuthSub 權杖升級為長期有效的會期權杖。 不同之處在於 AuthSub 沒有初始要求權杖的概念。使用者會改為從AuthSubRequestToken授權頁面啟動權杖程序。 - (OAuth) 服務供應商
如果是 Google Data API，這個供應商就是 Google。一般而言，服務供應商是指提供 OAuth 端點的網站或網路服務。 MySpace 也是 OAuth 服務供應商的例子。
- (OAuth) 消費者
要求存取使用者資料的程式 (即您的應用程式)。OAuth 通訊協定十分靈活，可支援各種不同類型的用戶端 (網頁、已安裝、桌機、行動裝置)。
注意：雖然 OAuth 通訊協定支援桌面/已安裝的應用程式使用案例，但 Google 僅支援網頁應用程式的 OAuth。
開始使用
註冊
開始使用 Google Data API 的 OAuth 之前，請先完成少量設定。由於所有 OAuth 要求都必須經過數位簽署，因此您必須先向 Google 註冊網域並上傳公開憑證。如要進一步瞭解如何執行這項操作，請參閱「註冊網頁式應用程式」和「產生金鑰和憑證以搭配註冊模式使用」。
簽署要求
網域註冊完成後，即可開始簽署要求。OAuth 最難的概念之一，就是如何正確建構 oauth_signature 和簽章基底字串的概念。基礎字串是您使用私密金鑰簽署的資料 (使用 RSA_SHA1)。結果是您為 oauth_signature 設定的值。
要求範例
GET 使用者的 Google 日曆清單 http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime
| 基本字串格式 | 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 方法時，請務必謹慎操作，因為您要處理的是實際資料！
提示：如要查看存取權杖可用的動態消息，請按一下「available feeds」(可用動態消息) 按鈕。
以下是範例查詢：GET http://www.blogger.com/feeds/1982051675575479214/posts/default?max-results=3
這個範例會傳回特定網誌最多三則貼文。您也可以點選語法醒目顯示區域下方的「在瀏覽器中查看」連結，直接在瀏覽器中查看傳回的動態消息/項目。
範例：如何更新貼文
- 在要更新的貼文中找出含有 rel="edit" 的
<link>元素。如下所示：<link rel="edit" href="http://www.blogger.com/feeds/1982051675575479214/posts/default/8138973184593279875"/>
將 href 網址貼到「輸入 Google 資料動態饋給」輸入欄位。
- 按一下語法醒目顯示面板頂端的「查看純文字」，複製現有項目的 XML。請只複製回應內文，不要複製標頭。
- 將 HTTP 方法下拉式選單變更為
PUT。 - 按一下該下拉式選單下方的「輸入貼文資料」，然後將
<entry>XML 貼到彈出式視窗中。 - 按一下「執行」按鈕。
伺服器會傳回 200 OK。
提示：與其手動複製 edit 連結，不如取消勾選「語法醒目顯示？」核取方塊。查詢後，您就能點選 XML 回應主體中的連結。
結論
AtomPub/Atom 發布通訊協定 (Google Data API 的基礎通訊協定) 和 OAuth 等技術有助於推動網路發展。越來越多網站開始採用這些標準，開發人員將是贏家。建立殺手級應用程式不再是難事。
如果您對 OAuth Playground 或搭配 Google API 使用 OAuth 有任何疑問或意見，請前往 G Suite API 和 Marketplace API 支援論壇。