Cloud Storage 適用的 App Engine 用戶端程式庫中的函式

Cloud Storage 適用的 App Engine 用戶端程式庫提供下列函式：

函式

  • cloudstorage.copy2()：將指定檔案複製到相同 Cloud Storage 值區中新指定的檔案名稱。
  • cloudstorage.delete()：從 Cloud Storage 值區刪除指定物件。
  • cloudstorage.listbucket() 列出 Cloud Storage 值區中的物件。
  • cloudstorage.open()：根據指定模式，在 Cloud Storage 值區開啟現有物件以進行讀取或覆寫，或建立新的物件
  • cloudstorage.stat()：提供檔案的中繼資料資訊，例如內容類型、大小、時間戳記、MD5 摘要，以及 Cloud Storage 標頭。

一旦叫用 cloudstorage.open() 以傳回代表指定 Cloud Storage 物件的檔案類物件，您就可以使用標準 Python 檔案函式 (例如 write() 和 close()) 將物件寫入 Cloud Storage 值區，或使用 read() 從 Cloud Storage 值區讀取物件。

課程

函式

cloudstorage.copy2 (src, dst, metadata=None, retry_params=None)

將指定檔案複製到新指定的檔案名稱，根據預設會連同中繼資料一併複製。另外，您也可以提供選用的 metadata 參數來覆寫副本中的中繼資料。

如果指定的 Cloud Storage 物件不存在，則會引發 cloudstorage.NotFoundError；如果授權失敗，則會引發 cloudstorage.AuthorizationError。

引數

src (必要)
物件的完整 Cloud Storage 檔案名稱，格式為 /bucket/object_name。必須是完整檔案名稱，且可包含分隔符號 `/`。
dst (必要)
物件「副本」的完整 Cloud Storage 檔案名稱，格式為 /bucket/object_name。必須是完整檔案名稱，且可包含分隔符號 `/`。
metadata= None (選用)
這個副本的中繼資料字典，例如 {'x-goog-meta-foo': 'bar'}。如果您提供中繼資料參數，系統就不會將任何原始中繼資料複製到新檔案。如果未提供中繼資料 (None)，系統會複製所有來源檔案中繼資料。
retry_params= None (選用)
RetryParams 物件：您可以在此物件中提供對此呼叫的預設逾時和重試設定所做的任何變更。

範例

如要複製檔案但要加入新的中繼資料，並且在來源檔案不存在時忽略錯誤：
import cloudstorage

try:
  cloudstorage.copy2('/my_bucket/README', '/my_bucket/README2', metadata={'x-goog-meta-zzzzz': 'zzzzz'})
except cloudstorage.NotFoundError:
  pass

返回頁首


cloudstorage.delete (filename, retry_params=None)

從 Cloud Storage 值區刪除指定檔案。

如果指定的 Cloud Storage 物件不存在，則會引發 cloudstorage.NotFoundError。

引數

filename (必要)
物件的完整 Cloud Storage 檔案名稱，格式為 /bucket/object_name。必須是完整檔案名稱，且可包含分隔符號 `/`。
retry_params= None (選用)
RetryParams 物件：您可以在此物件中提供對此呼叫的預設逾時和重試設定所做的任何變更。

範例

如要刪除檔案但在檔案不存在時忽略錯誤：
import cloudstorage

try:
  cloudstorage.delete(filename)
except cloudstorage.NotFoundError:
  pass

返回頁首


cloudstorage.listbucket (path_prefix, marker=None, max_keys=None, delimiter=None, retry_params=None)
傳回桶值疊代器物件。這個疊代器會傳回符合所有篩選器的物件排序清單。請注意，這個函式為非同步。除非在迭代器取得結果前呼叫迭代器，否則不會阻斷。

這個函式會在兩種不同模式下運作，這取決於您是否使用 delimiter 引數：

  • 一般模式 (預設)：在沒有任何階層概念下列出值區中的所有檔案 (Cloud Storage 沒有真正的目錄階層)。
  • 目錄模擬模式：如果您指定 delimiter 引數，系統會將其用作路徑分隔符，模擬目錄階層。

引數

path_prefix (必填)
Cloud Storage 路徑的格式為 /bucket 或 /bucket/prefix，例如 /bucket/foo/2001。系統只會傳回全路徑開頭為 path_prefix 的物件。
marker= None (選用)
字串。另一個路徑前置字串。只有完整路徑依照字母順序接在標記之後的物件才會傳回。用來做為「標記」的檔案不會傳回。舉例來說，如果您想要列出 superduperfoo3.txt 開始的所有檔案，請指定 superduperfoo3.txt 前方的檔案，例如：
stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')
使用這個參數的其中一種方式，就是搭配 max_keys 使用，以便「逐頁瀏覽」值區檔案名稱。
max_keys= None (選用)
整數。指定傳回物件數的上限。如果已知所要物件數，則可使用這個引數 (否則，Cloud Storage 用戶端程式庫會自動緩衝並逐頁切換所有結果)。可與 marker 搭配使用，以便逐頁瀏覽值區中的檔案名稱。
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimiter= None (選用)
字串。可開啟目錄模式。您可以指定一或多個字元做為目錄分隔符。
retry_params= None (選用)
RetryParams 物件：您可以在此物件中提供對此呼叫的預設逾時和重試設定所做的任何變更。

結果值

傳回相符檔案的 GCSFileStat 物件的疊代器，依檔案名稱排序。在一般模式中，傳回的 GCSFileStat 物件具有以下資料：

  • filename
  • etag (檔案內容的 MD5 雜湊十六進位表示法)
  • st_size (標頭內容長度)
  • st_ctime
  • is_dir

注意：如果 GCSFileStat 物件的 is_dir 屬性為 True，則物件中唯一的其他屬性為 filename。如果 is_dir 是 False，則 GCSFileStat 也會包含所有其他屬性。

返回頁首


cloudstorage.open(filename, mode='r', content_type=None, options=None, read_buffer_size=storage_api.ReadBuffer.DEFAULT_BUFFER_SIZE, retry_params=None)

在讀取模式 (r) 中，會開啟指定的 Cloud Storage 物件供讀取。在寫入模式 w 中，如果指定的檔案已存在，系統會開啟該檔案進行覆寫 (不支援附加)。如果檔案不存在，則會在指定值區中建立這個檔案。

寫入完成後，如果您想讀取檔案及/或將檔案儲存在 Cloud Storage 中，請使用 close 函式關閉檔案。即使您未呼叫 close，也不會發生錯誤，但檔案無法在 Cloud Storage 中讀取或儲存。

發出：

引數

filename (必要)
要開啟的檔案，格式為 /bucket/object。例如：/my_bucket/lyrics/southamerica/list5.txt。
mode (選用)
字串。指定 'r' 可開啟檔案供讀取 (預設)。指定 'w' 可開啟現有檔案進行覆寫，或建立新檔案。

content_type: (選填)
字串。僅可在寫入模式下使用。您應指定檔案的 MIME 類型 (可以指定任何有效的 MIME 類型)。如果您未提供這個值，Cloud Storage 會在提供物件時，預設為 binary/octet-stream 類型。
options: (選用)

字典，僅可在寫入模式下使用。支援的選項包括 x-goog-acl、x-goog-meta-、cache-control、content-disposition 和 content-encoding。

如果您未提供 x-goog-acl 選項，Cloud Storage 會使用值區的預設 ACL。Cloud Storage 說明文件的 x-goog-acl 部分列出了 x-goog-acl 的有效值。

您可以使用 x-goog-meta- 標頭指定自訂物件中繼資料。例如：

gcs_file = cloudstorage.open(filename, 'w', content_type='text/plain', options={'x-goog-acl': 'private','x-goog-meta-foo': 'foo', 'x-goog-meta-bar': 'bar'})
read_buffer_size: (選用)
整數。僅可在讀取模式下使用。如未設定這個值，則會使用預設緩衝大小 (建議)。讀取時，請使用 read_buffer_size 讀取，以便取得最佳預先擷取效能。
retry_params= None (選用)
RetryParams 物件：您可以在此物件中提供對此呼叫的預設逾時和重試設定所做的任何變更。

結果值

傳回讀取或寫入緩衝區，支援類似檔案的介面，可在該介面上叫用標準 Python read、write 和 close 函式。當您完成讀取或寫入後，這個緩衝區必須關閉。

返回頁首


cloudstorage.stat(filename, retry_params=None)

傳回包含檔案中繼資料的 GCSFileStat 物件。

如果指定的 Cloud Storage 物件不存在，則會引發 cloudstorage.NotFoundError。

引數

filename (必要)
要開啟的檔案，格式為 /bucket/object。例如：/my_bucket/lyrics/southamerica/list5.txt
retry_params= None (選用)
RetryParams 物件：您可以在此物件中提供對此呼叫的預設逾時和重試設定所做的任何變更。

結果值

傳回包含檔案中繼資料的 GCSFileStat 物件。

返回頁首