このページは Cloud Translation API によって翻訳されました。

以前のバンドルサービス用の Blobstore API の概要

Blobstore API を使用すると、blob と呼ばれるデータオブジェクトをアプリケーションで提供できるようになります。blob は、データストアサービスのオブジェクトに許可されているサイズよりはるかに大きいサイズのオブジェクトです。blob は、動画や画像などのサイズの大きいファイルを提供する場合や、ユーザーがサイズの大きいデータファイルをアップロードする場合に便利です。blob は HTTP リクエストでファイルをアップロードすることによって作成されます。通常アプリケーションでこの処理を行うには、ファイルアップロード用のフィールドを含むフォームをユーザーに提示します。フォームが送信されると、Blobstore によってファイルの内容から blob が作成され、blob への不透明な参照（blob キー）が返されます。このキーは後で blob を提供するときに使用できます。アプリケーションは、ユーザーリクエストに応じて完全な blob 値を提供でき、あるいはファイルに似たストリーミングインターフェースを使用して、値を直接読み取ることができます。

Blobstore を導入する

App Engine には Blobstore サービスが含まれています。このサービスを利用すると、アプリケーションでデータオブジェクトを提供できます。制限は 1 回の HTTP 接続でアップロードまたはダウンロードできるデータ量のみです。これらのオブジェクトを Blobstore 値または blob と呼びます。 Blobstore 値はリクエストハンドラからのレスポンスとして提供され、ウェブフォームを通じたアップロードデータとして作成されます。blob データは、アプリケーションで直接作成されるのではなく、送信されたウェブフォームや他の HTTP POST リクエストによって間接的に作成されます。Blobstore API を使用すると、Blobstore 値をユーザーに送信することや、ファイルに似たストリームでアプリケーションから Blobstore 値にアクセスできます。

アプリケーションで Blobstore 値のアップロードをユーザーに促すには、ファイルアップロード用のフィールドを含むウェブフォームを提示します。アプリケーションは、Blobstore API を呼び出してフォームのアクション URL を生成します。ユーザーのブラウザは、生成された URL を通じてファイルを Blobstore に直接アップロードします。次に、Blobstore は blob を保存し、blob キーが含まれるようにリクエストを書き換えて、アプリケーションのパスに渡します。そのパスにはアプリケーションのリクエストハンドラがあり、そこで追加のフォーム処理を行うことができます。

blob を提供するには、アプリケーションで送信レスポンスにヘッダーを設定します。このレスポンスは App Engine で blob 値に置き換えられます。

作成した blob は変更できませんが、削除することはできます。各 blob には対応する blob 情報レコードがあり、データストアに保存されています。blob 情報レコードを参照すると、作成日時やコンテンツタイプなどの blob の詳細がわかります。blob キーを使用して blob 情報レコードをフェッチし、そのプロパティへのクエリができます。

アプリケーションでは API を呼び出して Blobstore 値を読み取れますが、一度に読み取れるサイズは制限されています。制限サイズは API の戻り値の最大サイズで 32 MB より少し小さい値です。 Python では定数 google.appengine.ext.blobstore.MAX_BLOB_FETCH_SIZEで表されます。アプリケーションでは、ファイルをアップロードするという方法以外で Blobstore 値を作成または変更できません。

Blobstore を使用する

Blobstore を使用すると、ユーザーからアップロードされるサイズの大きなファイルをアプリケーションで受け取ることや提供することができます。アップロードされたファイルは blob と呼ばれます。アプリケーションが直接 blob にアクセスすることはありません。代わりに、Datastore の blob 情報エンティティ（ BlobInfo クラス）を介して blob を操作します。

ユーザーは 1 つ以上のファイル入力フィールドを含む HTML フォームを送信して blob を作成します。アプリケーションは、blobstore.create_upload_url()を呼び出して、このフォームの宛先（アクション）を取得します。この関数には、アプリケーションのハンドラの URL パスを渡します。ユーザーがフォームを送信すると、指定されたファイルがユーザーのブラウザから Blobstore に直接アップロードされます。Blobstore はユーザーのリクエストを書き換え、アップロードされたファイルデータを保存します。その際、アップロードされたファイルデータを 1 つ以上の対応する blob キーで置き換えます。その後、書き換えたリクエストを、blobstore.create_upload_url()に指定された URL パスにあるハンドラに渡します。

このハンドラは、blob キーに基づいて追加の処理を行えます。

アプリケーションは、Blobstore 値の一部を読み取るためにファイルに似たストリーミングインターフェースを使用します。BlobReader クラスをご覧ください。

blob をアップロードする

blob を作成してアップロードする手順は次のとおりです。

1. アップロード URL を作成する

blobstore.create_upload_url()を呼び出して、ユーザーが記入するフォームのアップロード URL を作成し、そのフォームの POST が完了したときに読み込むアプリケーションパスを渡します。

upload_url = blobstore.create_upload_url("/upload_photo")

非同期バージョンの create_upload_url_async() があります。このバージョンでは、Blobstore がアップロード URL を生成している間も、アプリケーションコードを実行し続けることができます。

2. アップロードフォームを作成する

フォームにはファイルアップロード用のフィールドを含め、フォームの enctype を multipart/form-data と設定する必要があります。ユーザーがフォームを送信すると、Blobstore API が POST を処理し、blob を作成します。この API はさらに、blob の情報レコードを作成してデータストアに保存し、指定されたパスにあるアプリケーションに、blob キーに書き換えたリクエストを渡します。

3. アップロードハンドラを実装する

このハンドラでは、blob キーとともにアプリケーションのデータモデルの残りの部分を保存できます。blob キー自体には、データストアの blob 情報エンティティから引き続きアクセスできます。ユーザーがフォームを送信し、ハンドラが呼び出された時点で、blob はすでに保存され、blob 情報がデータストアに追加されていることに注意してください。アプリケーションに blob を保持しない場合は、すぐに blob を削除して blob が孤立しないようにしてください。

すべての Flask アプリの場合、BlobstoreUploadHandler クラスのメソッドに対するすべての呼び出しでは request.environ dictionary が必要です（flask モジュールからのインポートリクエスト）。ウェブフレームワークを備えていない WSGI アプリの場合は、get_uploads() メソッドで environ パラメータを使用します。

Blobstore がユーザーのリクエストを書き換えると、アップロードされたファイルの MIME パーツの本文が空になり、MIME パーツのヘッダーとして blob キーが追加されます。他のすべてのフォームフィールドとパーツは保持され、アップロードハンドラに渡されます。コンテンツタイプを指定していない場合、Blobstore はファイル拡張子から推定を試みます。コンテンツタイプが判断できない場合、新しく作成される blob にはコンテンツタイプ application/octet-stream が割り当てられます。

blob を提供する

blob を提供するには、blob のダウンロードハンドラをパスとしてアプリケーションに含める必要があります。このアプリケーションは、送信レスポンスにヘッダーを設定して blob を提供します。Flask を使用する場合、BlobstoreDownloadHandler クラスには request.environ 辞書が必要です（リクエストは flask モジュールからインポートされます）。ウェブフレームワークを使用しない WSGI アプリの場合は、send_blob() メソッドで environ パラメータを使用します。 blob は、任意のアプリケーション URL から提供できます。アプリケーションで blob を提供するには、blob キーを含むレスポンスに特別なヘッダーを配置します。App Engine はレスポンスの本文を blob のコンテンツに置き換えます。

blob バイトの範囲

Blobstore は、リクエストへのレスポンスとして、サイズの大きな値全体ではなく値の一部の提供をサポートしています。値の一部を提供するには、送信レスポンスに X-AppEngine-BlobRange ヘッダーを含めます。その値は標準的な HTTP バイト範囲とします。バイト番号は 0 から始まります。X-AppEngine-BlobRange を空にすると、API は範囲ヘッダーを無視して blob 全体を提供します。範囲の例を以下に示します。

0-499: 値の最初の 500 バイト（0～499 バイト目まで）を提供します。
500-999: 501 バイト目から始まる 500 バイトを提供します。
500-: 501 バイト目から値の最後までのすべてのバイトを提供します。
-500: 値の最後の 500 バイトを提供します。

Blobstore 値に対して有効なバイト範囲が指定されている場合、Blobstore は 206 Partial Content ステータスコードとリクエストされたバイト範囲をクライアントに送信します。範囲が有効でなければ、Blobstore は 416 Requested Range Not Satisfiable を送信します。

Blobstore では、重複の有無にかかわらず 1 回のリクエストでの複数のバイト範囲の指定（100-199,200-299 など）はサポートしていません。

サンプルアプリケーションを完成させる

Python 3 用の Blobstore API ガイドで Flask アプリの例をご覧ください。

Blobstore で Images サービスを使用する

Images サービスでは、変換のソースとして Blobstore 値を使用できます。Blobstore 値の最大サイズと同サイズのソース画像を使用できます。Images サービスで変換後の画像がアプリケーションに返されるので、そのサイズは 32 MB より小さくなければなりません。これは、ユーザーがアップロードしたサイズの大きな写真のサムネイル画像を作成する場合に便利です。Images サービスで Blobstore 値を使用する方法については、 Images サービスのドキュメントをご覧ください。

Cloud Storage で Blobstore API を使用する

Blobstore API を使用して Blobstore ではなく Cloud Storage に blob を保存できます。Cloud Storage のドキュメントの説明に従ってバケットを設定し、そのバケットとファイル名をblobstore.create_upload_url gs_bucket_name パラメータに指定する必要があります。

アップロードハンドラで、必要なFileInfo メタデータを処理し、あとで blob の取得で必要になる Cloud Storage のファイル名を明示的に格納する必要があります。

Blobstore API を使用して Cloud Storage オブジェクトを提供することもできます。

最新のオブジェクトストレージソリューションが必要な場合は、App Engine Blobstore から Cloud Storage への移行を検討してください。

BlobReader を使用する

アプリケーションは、Python の file オブジェクトと同様のインターフェースを使用して Blobstore 値からデータを読み取ることができます。このインターフェースでは、任意のバイト位置で値の読み取りを開始できます。また、1 つのサービス呼び出しのレスポンスにサイズ制限があったとしても、アプリケーションが値全体にアクセスできるように、複数のサービス呼び出しとバッファリングを使用します。

BlobReader クラスは、コンストラクタへの引数として次の 3 つのいずれかの値を取ることができます。

BlobKey
BlobKey の文字列形式
BlobInfo オブジェクト。

このオブジェクトは、値を読み取るために使い慣れたファイルメソッドを実装しています。ただし、アプリケーションは Blobstore 値を変更できません。つまり、書き込むためのファイルメソッドは実装されていません。

# Instantiate a BlobReader for a given Blobstore blob_key.
blob_reader = blobstore.BlobReader(blob_key)

# Instantiate a BlobReader for a given Blobstore blob_key, setting the
# buffer size to 1 MB.
blob_reader = blobstore.BlobReader(blob_key, buffer_size=1048576)

# Instantiate a BlobReader for a given Blobstore blob_key, setting the
# initial read position.
blob_reader = blobstore.BlobReader(blob_key, position=0)

# Read the entire value into memory. This may take a while depending
# on the size of the value and the size of the read buffer, and is not
# recommended for large values.
blob_reader_data = blob_reader.read()

# Write the contents to the response.
self.response.headers["Content-Type"] = "text/plain"
self.response.write(blob_reader_data)

# Set the read position back to 0, then read and write 3 bytes.
blob_reader.seek(0)
blob_reader_data = blob_reader.read(3)
self.response.write(blob_reader_data)
self.response.write("\n")

# Set the read position back to 0, then read and write one line (up to
# and including a '\n' character) at a time.
blob_reader.seek(0)
for line in blob_reader:
    self.response.write(line)

非同期リクエストを行う

アプリケーションは、バックグラウンドで動作するいくつかの Blobstore 関数を呼び出すことができます。アプリケーションが他の処理を実行している最中に、Blobstore はリクエストを実行できます。このリクエストを行うには、アプリケーションから非同期関数を呼び出します。この関数はすぐに RPC オブジェクトを返し、このオブジェクトがリクエストを表します。アプリケーションでリクエストの結果が必要な場合は、RPC オブジェクトの get_result() メソッドを呼び出します。

アプリケーションが get_result() を呼び出したときにサービスがリクエストを完了していない場合、メソッドはリクエストが完了する（または、期限切れになるかエラーが発生する）まで待機します。メソッドは結果オブジェクトを返します。リクエストの実行中にエラーが発生した場合は、例外を発生させます。たとえば、次のコードスニペットは、

upload_url = blobstore.create_upload_url('/upload')
slow_operation()
self.response.out.write("""<form action="%s" method="POST"
                           enctype="multipart/form-data">""" % upload_url)

以下のようになります。

upload_url_rpc = blobstore.create_upload_url_async('/upload')
slow_operation()
upload_url = upload_url_rpc.get_result()
self.response.out.write("""<form action="%s" method="POST"
                           enctype="multipart/form-data">""" % upload_url)

この例では、Blobstore がアップロード URL を生成すると同時に、アプリケーションが slow_operation() コードを実行します。

割り当てと上限

Blobstore 値に使用する領域は、保存データ（課金対象）の割り当て量の計算対象になります。データストアの blob 情報エンティティはデータストア関連の制限に対してカウントされます。なお、Cloud Storage は従量課金サービスであり、Cloud Storage の価格表に従って課金されることに注意してください。

システム全体の安全上の割り当て量について詳しくは、割り当てをご覧ください。

Blobstore の使用については特に、システム全体の安全上の割り当て量に加えて次の制限が適用されます。

アプリケーションからの API 呼び出し 1 回で読み取ることのできる Blobstore データの最大サイズは 32 MB です。
1 つのフォームの POST でアップロードできるファイルの最大数は 500 です。