關於開原始碼的學習,主要就只接觸過XMPP服務端實現Openfire和現在的Swift了。想想這段時間對swift學習的停滯感,越來越覺得“如果想要學習一個東西的原理,首先要會使用它”,這會在一定程度上增加對功能處理流程的理解,並在源碼閱讀時產生共鳴。
對於swift API的學習,由於之前一直沒有找到比較系統的資料,官方文檔首頁上也沒有相關的連結,所以都是對照著swift-python-client的curl命令自己進行整理,這幾天突然發現swift官方文檔首頁上增加了Swift’s API docs連結!內容非常的全,以前真沒見到過哎,可能藏的太深,哈哈哈,PDF請點擊這裡下載。
在文檔的1.2小節document change history,中可以看到本文檔是《Rackspace Cloud Files Developer Guide》的分支。整體閱讀了一遍,發現很多細節內容是自己以前所不知的,比如分段返回資訊、超過5GB的大檔案上傳等,為了給後續自己開發實驗室的API做準備,所以決定試著翻譯一下,也可以作為小組內工作共用。
文檔中的內容主要分為4部分:
1. Overview2. General API Information3. API Operations for Storage Services4. Troubleshooting and Examples
第1部分主要是對swift進行了簡單的介紹,指明了本篇文檔的目標讀者、給出文檔更改記錄、其他資源連結;第4部分其實主要是介紹如何使用curl與swift進行互動的,以繞過代碼層面的互動,並返回請求/相應的詳細資料。其實看完前三個部分,對著命令列敲敲curl命令就可以理解了,很簡單。我這個人還是很懶的,所以第1和第4部分就不打算翻啦=D
現在,就讓我們愉快的開始吧!
=============================================================================
2. API基本資料
2.1. 認證
2.2. API操作概述
API操作參考摘要
Accounts儲存
Verb |
URI |
描述 |
GET |
/account |
擷取當前account下的containers列表 |
HEAD |
account |
擷取account中繼資料資訊 |
Container儲存
Verb |
URI |
描述 |
GET |
/account/container |
擷取當前container下的objects列表 |
PUT |
/account/container |
建立container |
DELETE |
/account/container |
刪除container |
HEAD |
/account/container |
擷取container中繼資料資訊 |
Object儲存
Verb |
URI |
描述 |
GET |
/account/container/object |
擷取object |
PUT |
/account/container/object |
建立/更新object |
PUT |
/account/container/object |
分塊傳輸編碼 |
DELETE |
/account/container/object |
刪除object(原文檔這裡有誤) |
HEAD |
/account/container/object |
擷取object中繼資料資訊 |
POST |
/account/container/object |
更新object中繼資料資訊 |
2.1. 認證(Authentication)
用戶端認證由ReST介面的GET方法提供,並使用 v1.0 作為路徑。此外,有兩個頭資訊必須提供:X-Auth-User 和 X-Auth-Key,它們的值分別為使用者名稱和API訪問Key。
每一個訪問OpenStackObject Storage Service系統的ReST請求都必須在HTTP頭中包含一個特定的頭資訊:X-Auth-Token,這個header的值即為使用者的訪問認證token。用戶端需要維護好這個token,同時也需要維護好其對應的雲端伺服器的API URI,這兩個值都是在用戶端第一次使用使用者名稱和API訪問Key進行認證服務的時候返回的。
請求
如果要進行認證,你必須提供你的使用者名稱和API訪問Key,並用這兩個值設定HTTP要求標頭的x-headers:
- 使用你的OpenStackObject Storage Service(Swfit)使用者名稱作為API訪問的使用者名稱。將使用者名稱儲存在要求標頭的 X-Auth-User 中。
- 從你安裝時所選擇的認證服務中擷取你的API訪問Key。關於認證,你可以有幾個選擇,包括tempauth(swift中內建的)、swauth(這是一種將swift的認證服務作為WSGI中介軟體的方式,它使用swift本身作為後端儲存,swauth可以通過Github進行下載)、OpenStack認證服務(KeyStone),或者你也可以使用自己的認證系統。將API訪問Key儲存在要求標頭的 X-Auth-Key 中。
例2.1. 認證請求
GET /v1.0 HTTP/1.1Host: auth.api.yourcloud.comX-Auth-User: jdoeX-Auth-Key: a86850deb2742ec3cb41518e26aa2d89
響應
當認證成功時,一個狀態代碼為204(沒有Content)且包含頭資訊 X-Storage-Url 和 X-Auth-Token 的HTTP響應會被返回。任何一個狀態代碼為2xx的響應都是一個好的響應。比如,一個202響應意味著請求已經被接受了。當然,一個額外的x-headers也有可能被返回。這些額外的頭資訊與其他的Rackspace服務相關也可以被忽略。當認證失敗時,會返回一個狀態代碼為401(未授權)的響應。所有子路徑為container/object的OpenStackObject Storage Service操作都應該使用 X-Storage-Url 中指定的URI作為訪問基路徑,且必須包含 X-Auth-Token 頭。
例2.2. 認證響應
HTTP/1.1 204 No ContentDate: Mon, 12 Nov 2010 15:32:21 GMTServer: ApacheX-Storage-Url: https://storage.swiftdrive.com/v1/CF_xer7_34X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbbContent-Length: 0Content-Type: text/plain; charset=UTF-8
X-Storage-Url 需要在後續的串連和所有Object Storage Service請求中作為基URI解析和使用。在例2.2中,使用者後續串連OpenStackObject Storage Service進行container/object請求時,大部分情況下都需要使用storage.swiftdrive.com作為主機頭、/v1/CF_xer7_34作為請求版本和賬戶。需要注意的是,在很多種認證配置中,認證token的有效期間只有24個小時。
2.2. API操作概述
OpenStackObject Storage Service的API被實現成一套ReSTful(Representational State Transfer) web services的集合,所有的認證和container/object操作都可以通過標準的HTTP調用實現。可以查看維基百科擷取更多關於ReST的資訊。
以下內容為ReST API HTTP請求中的一些限制:
- 每個請求的HTTP headers數目最多為90;
- 所有HTTP headers的長度最大為4096 bytes;
- 每個HTTP請求行(HTTP request line)的最大長度為8192 bytes;
- 每個HTTP請求的最大長度為5 GB;
- container名稱的最大長度為256 bytes;
- object名稱的最大長度為1024 bytes
Container和object的名字在與ReST介面進行互動前必須被進行適當的URL編碼,此外,container和object的名字也必須是UTF-8編碼的。應該在進行URL編碼後字串上進行長度約束的檢測。
每一個面向OpenStackObject Storage Service系統的ReST請求都需要包含一個指定的認證token的HTTP頭—— X-Auth-Token。用戶端在第一次使用使用者名稱和API訪問Key進行認證時擷取這個token,同時也擷取OpenStackObject Storage Service的URLs。
使用 X-Storage-Url 識別的ReST服務用語管理儲存在系統中的資料。例如建立container和上傳object的操作。
在下一節中,我們將介紹每個HTTP方法調用與服務的對應關係。比如,一個針對 X-Storage-Url 的PUT請求有可能是用於建立一個container或上傳一個對象的。
特定語言的APIs將程式員與系統實現細節隔離開。程式員只需要簡單的使用適當的ReST API就可以建立一個container、標記其為公用的,並處理調用將其分配到適當的後端服務。
注意:
所有認證請求和針對OpenStackObject Storage Service的操作都通過HTTP(HTTPS)的SSL執行,並使用TCP 443連接埠。
哎,翻的好爛,自己都受不了了T^T