webapp includes request handler classes for working with the
Blobstore API. BlobstoreUploadHandler
provides logic for parsing the upload request passed via the Blobstore into
BlobInfo
records for further processing. BlobstoreDownloadHandler
makes it easy to serve
Blobstore values from any path.
BlobstoreUploadHandler
Values are added to the Blobstore via file uploads posted by users or administrators of the app.
The app posts a web form with a file upload field and a form action that directs the upload to the
Blobstore. The app gets the form action URL by calling a function
(create_upload_url()),
passing it the URL of an app handler that gets called when users upload files. A webapp
application can use a subclass of the BlobstoreUploadHandler
class as the handler for
this URL.
The get_uploads()
method returns a list of
BlobInfo
objects, one for each uploaded file in the request. Each object contains the Blobstore key for
the uploaded value, as well as metadata such as the filename and size. Each uploaded file also
has a corresponding entity in the datastore with this information, so you can fetch the BlobInfo
object later given a blob key, or perform a datastore query over the metadata fields. The upload
handler parses this information directly from the request data, not the datastore.
By default, get_uploads()
returns BlobInfo objects for all uploaded files in the
request. The method also accepts a field_name
argument to get just the file (or
files) for a given file upload field. The return value is always a list, possibly an empty list.
Using BlobstoreUploadHandler
with Google Cloud Storage
If you use this upload handler with Cloud Storage, you'll need to get and store the full
Cloud Storage object file name, since this is required to retrieve the file again from Cloud Storage.
Use the function get_file_infos
, which returns a list of
FileInfo records
corresponding to each upload. The full Cloud Storage object name, content type, creation
time, and other data are available in the FileInfo
. (See the link for complete details.)
BlobstoreDownloadHandler
To serve a Blobstore value, the application sets the X-AppEngine-BlobKey
header to
the value of a Blobstore key, in string form. When App Engine sees this header in the response,
it serves the value of the blob as the body of the response. The webapp handler class
BlobstoreDownloadHandler
makes it easy to set this value in the response.
The send_blob()
method takes a
BlobKey
object, a string key, or a
BlobInfo
as the blob_key_or_info
argument, and sets the response data so that the blob value
will be served to the user. The method takes an optional content_type
argument which
overrides the MIME content type of the stored blob value. By default, the blob is served with the
content type set by the client that uploaded it, a content type derived from the filename, or a
generic type if no other type information is available.
The send_blob()
method accepts a save_as
argument that determines
whether the blob data is sent as raw response data or as a MIME attachment with a filename. If
the argument is a string, the blob is sent as an attachment, and the string value is used as
the filename. If True
and blob_key_or_info
is a BlobInfo
object, the filename from the object is used. By default, the blob data is sent as the body of
the response and not as a MIME attachment.
The Blobstore supports sending just part of a value instead of the full value, described as a range of byte indexes. You can provide a byte index range to BlobstoreDownloadHandler
's send_blob()
method in two ways. The first is to specify the range as the arguments start
and end
:
# Send the first 1,000 bytes of the value. self.send_blob(key, start=0, end=999)
By default, the BlobstoreDownloadHandler
honors the range
header in the request. If you wish to block use of the original range header, provide the parameter use_range=False
to send_blob()
:
# Send the full value of the blob and # block the "range" header. self.send_blob(key, use_range=False)
The value of the range
header is a standard HTTP byte range. BlobstoreDownloadHandler
uses webob.byterange to parse this header value.
Complete sample application
In the following sample application, the application's main URL loads the form that asks the user for a file to upload, and the upload handler immediately calls the download handler to serve the data. This is to simplify the sample application. In practice, you would probably not use the main URL to request upload data, nor would you immediately serve a blob you had just uploaded.