OpenStack Object Storage Developer Guide/Swift官方API文檔 — 翻譯 （二）

在上一篇中，翻譯介紹了Swift官方文檔的第2部分API基本資料，本篇來完成最主要的儲存服務的API操作部分。那麼，現在就讓我們開始吧=D

3. 儲存服務的API操作（API Operations for Storage Services）

3.1. Account儲存服務（Storage Account Services）    3.1.1. 擷取容器列表（List Containers）     3.1.2. 擷取帳號中繼資料（Retrieve Account Metadata）    3.1.3. 建立/更新帳號中繼資料（Create/Update Account Metadata)     3.1.4. 刪除帳號中繼資料（Delete Account Metadata）3.2. Container儲存服務（Storage Container Services）    3.2.1. 擷取對象列表（List Objects）     3.2.2. 建立容器（Create Container）    3.2.3. 刪除容器（Delete Container）     3.2.4. 擷取容器中繼資料（Retrieve Container Metadata）     3.2.5. 建立/更新容器中繼資料（Create/Update Container Metadata）     3.2.6. 刪除容器中繼資料（Delete Container Metadata） 3.3. 建立靜態網站（Create Static Website）    3.3.1. 通過Swift實現的靜態網頁中介軟體（Static Web Middleware via swift）    3.3.2. 為靜態網站設定出錯頁（Set Error Pages for Static Website）3.4. Object儲存服務（Storage Object Services）    3.4.1. 擷取對象（Retrieve Object）     3.4.2. 建立/更新對象（Create/Update Object）     3.4.3. 為請求分配CORS頭（Assigning CORS Headers to Requests）    3.4.4. 通過Content-Encoding頭啟用檔案壓縮（Enabling File Compression with the Content-Encoding Header）    3.4.5. 通過Content-Disposition都啟用瀏覽器旁路（Enabling Browser Bypass with the Content-Disposition Header）    3.4.6. 通過X-Delete-After和X-Delete-At頭使對象到期（Expiring Objects with the X-Delete-After and X-Delete-At Headers）    3.4.7. 對象版本管理（Object Versioning）    3.4.8. 複製對象（Copy Object）    3.4.9. 刪除對象（Delete Object）    3.4.10. 擷取對象中繼資料（Retrieve Object Metadata）    3.4.11. 更新對象中繼資料（Update Object Metadata）

本章描述了與OpenStackObject Storage Service中的儲存群組件進行互動的ReST API。所有的請求都通過在認證階段成功擷取的 X-Storage-Url 直接發送到主機。

以下內容為使用儲存服務需要滿足的幾點要求：

• Container的名稱不能超過256位元組，並且不能包含字元'/'；
• Object的名稱不能超過1024位元組，並且不能包含保留字元；
• Object和Container的名稱必須是URL編碼和UTF編碼的。

以下小節描述了儲存系統中可能被執行的動作，3.1節重點描述儲存系統中account層面的動作；3.2節重點描述儲存系統中container層面的動作；3.4節（原文這裡有誤）重點描述了儲存系統中object層面的動作。

 

3.1. Account儲存服務（Storage Account Services）

以下操作在URL的account層面執行。例如，以下請求的URL將會以一個OpenStackObject Storage Service的賬戶字串結束：

　　例3.1. Account儲存的HTTP請求：基本結構

METHOD /v1/<account> HTTP/1.1

3.1.1. 擷取容器列表

對一個帳號的 X-Storage-Url 執行 GET 操作將會擷取這個帳號下container列表，並以名稱排序。名字的順序由二進位比較決定，一個簡單的內建排序方法是用SQLite的memcmp()函數實現，且與編碼無關。以下列表內容描述了這個請求支援的選擇性參數。

查詢參數

limit	整數n，指明返回結果只包含n個值
marker	字串x，返回名稱比這個特定的字串x大的container列表
end_marker	字串x，返回名稱比這個特定字串小的container列表
format	設定響應的資料格式為json或xml

 

 

 

 

 

 

當前，在account層面不支援根據首碼（prefix）查詢。

　　例3.2. 擷取container列表的請求

GET /<api version>/<account> HTTP/1.1Host: storage.swiftdrive.comX-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

　　container列表包含在響應訊息體（response body）中，每行一個container名稱。當查詢賬戶中一個container都沒有時，將會返回一個沒有內容、狀態代碼為204的響應訊息。

　　例3.3. 擷取container列表的響應

HTTP/1.1 200 OkDate: Thu, 07 Jun 2010 18:57:07 GMTServer: ApacheContent-Type: text/plain; charset=UTF-8Content-Length: 32

imagesmoviesdocumentsbackups

3.1.1.1. 序列化列表輸出

如果在儲存帳號URL後添加一個 format=xml 或 format=json 參數對，則服務端會將container列表以指定的格式進行序列化再返回。以下的例子就是根據相應的格式進行返回的。

　　例3.4. container詳情請求：JSON

GET /<api version>/<account>?format=json HTTP/1.1Host: storage.swiftdrive.comContent-Length: 0X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4

　　例3.5. container詳情響應：JSON

HTTP/1.1 200 OKDate: Tue, 25 Nov 2008 19:39:13 GMTServer: ApacheContent-Type: application/json; charset=utf-8

[{"name":"test_container_1", "count":2, "bytes":78},{"name":"test_container_2", "count":1, "bytes":17}]

　　例3.6. container詳情請求：XML

GET /<api version>/<account>?format=xml HTTP/1.1Host: storage.swiftdrive.comContent-Length: 0X-Storage-Token: 182f9c0af0e828cfe3281767d29d19f4

　　例3.7. container詳情響應：XML

HTTP/1.1 200 OKDate: Tue, 25 Nov 2008 19:39:13 GMTServer: ApacheContent-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?><account name="MichaelBarton">    <container>        <name>test_container_1</name>        <count>2</count>        <bytes>78</bytes>    </container>    <container>        <name>test_container_2</name>        <count>1</count>        <bytes>17</bytes>    </container></account>

3.1.1.2. Container大列表的控制

OpenStackObject Storage Service系統每個請求最多可以返回10,000個容器的名字。為了擷取container名稱列表的子序列，另一個請求必須使用 marker 參數。這個參數表明了列表從哪裡結束，系統將會返回所有名稱大於這個marker的container名稱，同時，最多也只能有10,000個。注意，marker的值通過HTTP請求發送時應當是URL-encoded的。

如果我們不需要10,000個那麼多的container，我們可以使用 limit 參數。

如果返回的container名稱列表的長度剛好等於limit的值（或當沒有使用limit時，等於10,000），則表明可能還有滿足條件的container名稱沒有返回。

　　例3.8. 列出很長的container列表

　　例如，我們使用一個長度為5的容器名稱列表。

applesbananaskiwisorangespears

　　我們將使用limit值為2來表明這是如何工作的：

GET /<api version>/<account>?limit=2Host: storage.swiftdrive.comX-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

applesbananas

　　由於我們收到兩個容器名稱（與limit的值相同），因此我們猜測還有更多的container名稱需要被列出。因此，我們使用marker參數建立另一個請求，marker的值為上一次請求返回的container列表中的最後一個：

GET /<api version>/<account>?limit=2&marker=bananasHost: storage.swiftdrive.comX-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

kiwisoranges

　　由於又收到了長度為2的container列表，同理，我們繼續請求：

GET /<api version>/<account>?limit=2&marker=orangesHost: storage.swiftdrive.comX-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

pears

　　這次，我們只收到了長度為1的container列表，小於請求的limit值，因此表明沒有更多的container名稱需要被列出了，即已經到達了列表的結尾。

通過使用 end_marker 參數，我們可以限制返回的結果中的container名稱小於給定的值。

GET /<api version><account>?end_marker=orangesHost: storage.swiftdrive.comX-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

applesbananaskiwis

3.1.2. 擷取帳號中繼資料

在一個帳號上使用HEAD操作可以擷取這個帳號下的container數量以及總儲存位元組。這個資訊通過兩個自訂的頭資訊返回：X-Account-Container-Count 和 X-Account-Bytes-Used。由於swift是為儲存海量資料而設計的，因此在使用integer類型儲存帳號總使用位元組時應當格外小心，如果你的平台支援的話，可以將其轉換為64位的無符號整型。

　　例3.9. 擷取帳號中繼資料的請求

HEAD /<api version>/<account> HTTP/1.1Host: storage.swiftdrive.comX-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

　　如果請求成功，將會返回狀態代碼為204（沒有內容）的響應。如果請求的是一個無效的帳號或訪問key錯誤的話，將會返回狀態代碼為401（未授權）的響應。

　　例3.10. 擷取帳號中繼資料的響應

HTTP/1.1 204 No ContentDate: Thu, 07 Jun 2010 18:57:07 GMTServer: ApacheX-Account-Container-Count: 3X-Account-Bytes-Used: 323479

3.1.3. 建立/更新帳號中繼資料

你可以在account層級的URI上使用自訂的中繼資料頭資訊，這些頭必須以 X-Account-Meta-* 的格式定義。

如果你想建立或更新一個帳號的中繼資料頭資訊，則需要使用POST查詢。後續請求中的相同可以的key/value對將會覆蓋之前的值。

　　例3.11. 更新帳號中繼資料的請求

POST /<api version>/<account> HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbbX-Account-Meta-Book: MobyDickX-Account-Meta-Subject: Whaling

　　這個請求將不會有包含訊息體的響應返回，一個狀態代碼為204的無內容響應表明更新成功。

　　例3.12. 更新帳號中繼資料的響應

HTTP/1.1 204 No ContentContent-Length: 0Content-Type: text/html; charset=UTF-8Date: Sat, 09 Jun 2012 19:16:29 GMT

　　為了確認你的中繼資料確實已經被更改了，則需要對account執行一個HEAD請求。注意，請不要在你的HEAD請求中包含任何中繼資料資訊。

　　例3.13. 查看Account中繼資料的請求

HEAD /<api version>/<account> HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb

　　例3.14. 查看Account中繼資料的響應

HTTP/1.1 204 No ContentX-Account-Meta-Book: MobyDickX-Account-Meta-Subject: WhalingX-Account-Object-Count: 5X-Timestamp: 1323466696.21566X-Account-Container-Count: 5X-Account-Bytes-Used: 46988Accept-Ranges: bytesContent-Length: 0Date: Sat, 09 Jun 2012 19:16:59 GMT

3.1.4. 刪除帳號中繼資料

為了刪除帳號的一個中繼資料，我們需要使用那個特定的頭資訊發送一個值為空白的POST請求，例如X-Account-Meta-Book: 。

如果你所使用的與swift進行互動的工具不支援發送包含headers值為空白的請求（例如較老版本的curl），則你可以發送頭為“X-Remove-Account-Meta-name: 任意值”的請求，例如：X-Remove-Account-Meta-Book: x。這個值將會被忽略。

　　例3.15. 刪除Account中繼資料的請求

POST /<api version>/<account> HTTP/1.1Host: storage.clouddrive.comX-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbbX-Remove-Account-Meta-Book: x

　　這個請求將不會有包含訊息體的響應返回，一個狀態代碼為204的無內容響應表明刪除成功。

 

 

暫時到這裡吧，好累T^T，後續完成後再把3.2.節合并到後面（已合并完畢），這樣一篇一小節^_^