2011年3月2日水曜日

Blobstoreドキュメント日本語要約 (Google App Engine)

 

概要

BlobstoreはDatastoreより大きなblobオブジェクトを扱うことができる。BlobはHTTPリクエストでファイルをアップロードすることで作られる。ファイルがアップロードされるとBlobstoreがblob keyを返す。blogを操作するためにこのキーを使う。

blobのサイズは最大で2GB。
Blobstoreのblobは、Datastoreのblobプロパティとは別のもの。
blobは削除することはできるが変更することはできない。

blobの作成時刻やコンテントタイプなどの情報はDatastoreに記録される。blobキーはblobの情報を読み出すクエリに使うことができる。

Blobstoreの使い方

アプリはblobに直接アクセスできない。かわりにDatastoreのblob情報エンティティを通してblobを扱える。

ユーザはHTMLフォームの1つまたは複数のファイル入力フィールドからblobを作ることができる。

アプリはblobstoreService.createUploadUrl()で得られるURLをフォームのactionにセットする。このメソッドにはアプリのハンドラのパスを渡す。ユーザはBlobstoreに直接ファイルをアップロードする。

Blobstoreはユーザのリクエストを書き換えてアップロードされたファイルをストアし、blobキーに対応するファイルデータを置き換える。そして書き換えられたリクエストをあなたがcreateUploadUrl()に提供したURLパスのハンドラに渡す。

ハンドラはblobキーに基づいた追加の処理ができる。

最後に、ハンドラはヘッダのみのリダイレクトレスポンス(301, 302, 303)を返して、典型的にはブラウザは、blobアップロードのステータスを示す別のページにリダイレクトする。

アプリはファイルのようなストリーミングインタフェースを使ってBlobstoreのデータを読むことができる(BlobstoreInputStream)。

blobをアップロードする

フォームの例。

<form action="<%= blobstoreService.createUploadUrl("/upload") %>"
  method="post" enctype="multipart/form-data">
    <input type="file" name="myFile">
    <input type="submit" value="Submit">
</form>

actionのURLはcreateUploadUrl()で作成。メソッドにはアップロード完了で呼ばれるハンドラのURLを渡す。

フォームにはファイルinputのフィールドを含む必要がある。enctypeは"multipart/form-data"にする。

ハンドラが呼ばれるときにはすでにblobは保存され、Datastoreにblob情報ができている。

ハンドラでアップロードされたblobのリストを取り出す例。Mapには<ファイル名,BlobKey>の組で入っている。ファイル名はアップロードの際にフォームに書いた値。

Map<String, BlobKey> blobs = blobstoreService.getUploadedBlobs(req);

blobstoreがユーザリクエストを書き換えるとき、アップロードされたファイルのMIMEパートはbodyが空にして、MIMEパートのヘッダにblobキーを追加する。他のすべてのフォームフィールドとパートはそのままハンドラに渡される。

コンテントタイプを指定しない場合、Blobstoreはファイルの拡張子からコンテントタイプを推定する。コンテントタイプが決定されないときは、新しく作られたblobは application/octet-streamが割り当てられる。

blobを供給する

blobを供給するためにはアプリでblobのダウンロードハンドラを用意する必要がある。ハンドラでは欲しいblobのキーをblobstoreService.serve(blobKey, res)メソッドに渡す。

例:

BlobKey blobKey = new BlobKey(req.getParameter("blob-key"));
blobstoreService.serve(blobKey, res);

blobはアプリのどんなURLからも供給できる。アプリでblobを供給するために、blobキーを含んだ特別なヘッダをレスポンスに含める。App Engineはレスポンスのボディをblobの内容で置き換える。

blobのバイト範囲

レスポンスにX-AppEngine-BlobRangeヘッダを含めることで大きなデータの一部だけを標準的なHTTPバイトレンジで返すことができる。

X-AppEngine-BlobRangeをブランクにするとレンジヘッダを無視して完全なblobを返す。

範囲指定の例:

  • 0-499 最初の500バイト
  • 500-999 501バイト目から500バイト
  • 500- 501バイト目から最後まで
  • -500 最後の500バイト

バイト範囲が正しければBlobstoreはクライアントに"206 Partial Content"のステータスコードと要求されたバイト範囲を送る。もしレンジが正しくなければBlobstoreは"416 Requested Range Not Satisfiable"を送る。

Blobstoreは1つのリクエストで複数のバイト範囲をサポートしない。

Blobstoreでイメージサービスを使う

イメージサービスはBlobstoreのデータを変換のソースとして使用できる。ソースイメージはBlobstoreデータの最大サイズまで扱える。変換されたイメージは1MBより小さくなければならない。

詳しくはイメージサービスのドキュメントを参照。

ファイルをBlobstoreに書き込む (実験的)

プログラムからblobデータを読み書きするためのAPIが用意されている。この機能によってデータをエクスポートしたり、生成したバイナリデータを保存したりできる。

つきのようにして書き込み可能な空のファイルを作成し、書き込み可能な Channel をオープンする。

AppEngineFile file =
  fileService.createNewBlobFile("text/plain");

FileWriteChannel writeChannel =
  fileService.openWriteChannel(file, lock);

たとえ1バイトを書くだけでも、それぞれの書き込みが最小のCPUクォータを消費する。書き込みをバッチ処理することによって、効率的にクォータを使うことができる。
(訳注:この「書き込み」の単位がメソッド呼び出しなのかファイルをクローズするまでなのかは不明。)

クォータとリミット

Blobstoreデータに使われたスペースは保存データのクォータ(課金対象)に計上される。
Datastoreに含まれるblob情報エンティティがDatastore関連のクォータに計上される。
Blobstoreの操作によって消費されたCPU時間はCPU時間のクォータ(課金対象)に計上される。

詳しくはクォータの情報はクォータと管理コンソールの「クォータ詳細情報」のドキュメントを参照。

リミット

  • 最大オブジェクトサイズ 2GB
  • 1回のAPI呼び出しで読めるBlobstoreデータの最大のサイズ 1MB