舊版套裝組合服務的 Blobstore API 總覽

Blobstore API 可讓您的應用程式提供名為 blob 的資料物件,這類物件會比 Datastore 服務允許的物件大小大上許多。Blob 不僅可用於提供影片或圖片檔等大型檔案外,還可讓使用者上傳大型資料檔案。Blob 的建立方式是透過 HTTP 要求上傳檔案。一般而言,應用程式會向使用者提供具備檔案上傳欄位的表單,藉此執行此操作。提交表單後,Blobstore 會從檔案內容建立 blob 並傳回 blob 的不透明參照,即「blob 鍵」,供您稍後用於提供該 blob。應用程式可根據使用者要求提供完整的 blob 值,或透過類似串流檔案的介面來直接讀取該值。

Blobstore 簡介

App Engine 包含 Blobstore 服務,可讓應用程式提供資料物件,並且只會受到單一 HTTP 連線可上傳或下載資料量的限制。這些物件稱為「Blobstore 值」或「blob」。Blobstore 值會以要求處理常式所傳回的回應提供,並且透過網路表單的上傳作業建立而成。應用程式不會直接建立 blob 資料;相反地,blob 是透過提交網路表單或其他 HTTP POST 要求的方式間接建立。Blobstore 值可提供給使用者,或由應用程式透過 Blobstore API 在類似檔案的串流中存取。

應用程式會提供具備檔案上傳欄位的網路表單,藉此提示使用者上傳 Blobstore 值。應用程式會呼叫 Blobstore API 來產生表單的動作網址。使用者的瀏覽器會透過產生的網址,將檔案直接上傳至 Blobstore。接著 Blobstore 會儲存 blob 並修改要求,讓要求內容包含 blob 金鑰,並且將它傳送至應用程式中的特定路徑。在應用程式中,位於該路徑的要求處理常式可執行額外的表單處理。

為了提供 blob,應用程式會在外送回應中設定標頭,並且由 App Engine 將該回應取代為 blob 值。

Blob 一旦建立後便無法修改,但可予以刪除。每個 blob 在資料儲存庫中都有儲存對應的「blob 資訊記錄」,用以提供有關該 blob 的建立時間與內容類型等詳細資訊。您可以使用 blob 鍵來擷取 blob 資訊記錄並查詢其屬性。

使用 Blobstore

應用程式可使用 Blobstore 接受使用者上傳的大型檔案,同時還可以提供這些檔案。檔案上傳之後,就稱為 blob。應用程式不會直接依檔案名稱存取 Blob,而是透過資料儲存庫中的「blob 資訊實體」 (以 類別表示) 使用 blob。

使用者提交含有一或多個檔案輸入欄位的 HTML 表單就能建立 blob。應用程式會設定 做為這個表單的目的地 (動作),並將應用程式中處理常式的網址路徑傳送給函式。 使用者提交表單時,使用者的瀏覽器會將指定檔案直接上傳至 Blobstore。Blobstore 會修改使用者要求並儲存上傳的檔案資料,將上傳的檔案資料取代為一或多個對應的 blob 金鑰,接著將修改過的要求傳送至您提供給 的網址路徑所在的處理常式。

這個處理常式可根據 blob 鍵執行額外的處理工作。

應用程式可以透過類似檔案的串流介面讀取一部分的 Blobstore 值,

上傳 blob

如要建立並上傳 blob,請依照下列程序執行:

1. 建立上傳網址

呼叫 以建立使用者所填寫表單的上傳網址,在表單的 POST 完成時傳送要載入的應用程式路徑。

upload_url = blobstore.create_upload_url("/upload_photo")

非同步版本為 create_upload_url_async()。此版本可讓應用程式的程式碼在 Blobstore 產生上傳網址時繼續執行。

2. 建立上傳表單

表單必須包含檔案上傳欄位,且表單的 enctype 必須設為 multipart/form-data。使用者提交表單時,POST 將由建立 blob 的 Blobstore API 來處理。這個 API 另外也會建立 blob 的資訊記錄並儲存在 Datastore 中,然後將修改過的要求以 blob 金鑰的形式傳送至應用程式中的指定路徑。

您無法使用全域外部應用程式負載平衡器搭配無伺服器 NEG,處理傳送至 blobstore.create_upload_url 呼叫傳回的 /_ah/upload/ URL 的上傳要求。您必須改為將這些上傳要求直接轉送至 App Engine 服務。您可以透過 appspot.com 網域或直接對應至 App Engine 服務的自訂網域,執行這項操作。

3. 實作上傳處理常式

在這個處理常式中,您可以將 blob 鍵與應用程式資料模型的其他部分儲存在一起。blob 鍵本身仍可從 Datastore 中的 blob 資訊實體存取。請注意,在使用者提交表單並呼叫處理常式後,blob 就已經儲存,而 blob 資訊也已新增至 Datastore。如果應用程式不想保留 blob,您應立即刪除 blob,以防止 blob 成為孤立檔案。

對於所有 Flask 應用程式,對 BlobstoreUploadHandler 類別中方法的所有呼叫,都需要 request.environ dictionary (從 Flask 模組匯入的要求)。如果您的應用程式是沒有網頁架構的 WSGI 應用程式,請在 get_uploads() 方法中使用 environ 參數。 修改使用者要求時,Blobstore 會清空已上傳檔案中的 MIME 區塊,然後以 MIME 區塊標頭的形式加入 blob 金鑰。Blobstore 會保留其他所有表單欄位和部分,並傳送至上傳處理常式。如果您未指定內容類型,Blobstore 會嘗試從副檔名推論。如果無法判斷內容類型,系統會為新建的 blob 指派內容類型 application/octet-stream

提供 blob

如要提供 blob,您必須以應用程式路徑的形式加入 blob 下載處理常式。blobstore.Send