Google Cloud Storage 用戶端程式庫函式

Google Cloud Storage 用戶端程式庫提供下列函式:

函式

  • 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 物件之類似檔案的物件後,您可以使用 write()close() 等標準 Python 檔案函式來將物件寫入 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 (必要)
/bucket/bucket/prefix 格式的 Cloud Storage 路徑,例如 /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_dirFalse,則 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-aclx-goog-meta-cache-controlcontent-dispositioncontent-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 readwriteclose 函式。當您完成讀取或寫入後,這個緩衝區必須關閉。

返回頁首


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 物件。

返回頁首

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Python 2 適用的 App Engine 標準環境