Overview of Blobstore API for legacy bundled services

Note: You should consider using Cloud Storage rather than Blobstore for storing blob data.

The Blobstore API allows your application to serve data objects, called blobs, that are much larger than the size allowed for objects in the Datastore service. Blobs are useful for serving large files, such as video or image files, and for allowing users to upload large data files. Blobs are created by uploading a file through an HTTP request. Typically, your applications will do this by presenting a form with a file upload field to the user. When the form is submitted, the Blobstore creates a blob from the file's contents and returns an opaque reference to the blob, called a blob key, which you can later use to serve the blob. The application can serve the complete blob value in response to a user request, or it can read the value directly using a streaming file-like interface.

Introducing the Blobstore

Google App Engine includes the Blobstore service, which allows applications to serve data objects limited only by the amount of data that can be uploaded or downloaded over a single HTTP connection. These objects are called Blobstore values, or blobs. Blobstore values are served as responses from request handlers and are created as uploads via web forms. Applications do not create blob data directly; instead, blobs are created indirectly, by a submitted web form or other HTTP POST request. Blobstore values can be served to the user, or accessed by the application in a file-like stream, using the Blobstore API.

Note: Blobs as defined by the Blobstore service are not related to blob property values used by the datastore.

To prompt a user to upload a Blobstore value, your application presents a web form with a file upload field. The application generates the form's action URL by calling the Blobstore API. The user's browser uploads the file directly to the Blobstore via the generated URL. Blobstore then stores the blob, rewrites the request to contain the blob key, and passes it to a path in your application. A request handler at that path in your application can perform additional form processing.

To serve a blob, your application sets a header on the outgoing response, and App Engine replaces the response with the blob value.

Blobs can't be modified after they're created, though they can be deleted. Each blob has a corresponding blob info record, stored in the datastore, that provides details about the blob, such as its creation time and content type. You can use the blob key to fetch blob info records and query their properties.

An application can read a Blobstore value a portion at a time using an API call. The size of the portion can be up to the maximum size of an API return value. This size is a little less than 32 megabytes, represented in Python by the constant google.appengine.ext.blobstore.MAX_BLOB_FETCH_SIZE. An application cannot create or modify Blobstore values except through files uploaded by the user.

Using the Blobstore

Applications can use the Blobstore to accept large files as uploads from users and to serve those files. Files are called blobs once they're uploaded. Applications don't access blobs directly. Instead, applications work with blobs through blob info entities (represented by the BlobInfo class) in the datastore.

The user creates a blob by submitting an HTML form that includes one or more file input fields. Your application calls create_upload_url() to get the destination (action) of this form, passing the function a URL path of a handler in your application. When the user submits the form, the user's browser uploads the specified files directly to the Blobstore. The Blobstore rewrites the user's request and stores the uploaded file data, replacing the uploaded file data with one or more corresponding blob keys, then passes the rewritten request to the handler at the URL path you provided to create_upload_url(). This handler can do additional processing based on the blob key.

The application can read portions of a Blobstore value using a file-like streaming interface. See The BlobReader Class.

Uploading a blob

To create and upload a blob, follow this procedure:

1. Create an upload URL

Call blobstore.create_upload_url() to create an upload URL for the form that the user will fill out, passing the application path to load when the POST of the form is completed.

upload_url = blobstore.create_upload_url("/upload_photo")

There is an asynchronous version, create_upload_url_async(). It allows your application code to continue running while Blobstore generates the upload URL.

2. Create an upload form

The form must include a file upload field, and the form's enctype must be set to multipart/form-data. When the user submits the form, the POST is handled by the Blobstore API, which creates the blob. The API also creates an info record for the blob and stores the record in the datastore, and passes the rewritten request to your application on the given path as a blob key.

        # To upload files to the blobstore, the request method must be "POST"
        # and enctype must be set to "multipart/form-data".
        self.response.out.write(
            """
<html><body>
<form action="{0}" method="POST" enctype="multipart/form-data">
  Upload File: <input type="file" name="file"><br>
  <input type="submit" name="submit" value="Submit">
</form>
</body></html>""".format(
                upload_url
            )
        )

Note: You must serve the form's page with a Content-Type of text/html; charset=utf-8, or any filenames with non-ASCII characters will be misinterpreted.
This is the default content type in webapp and webapp2, but you must remember to do this if you set your own Content-Type or are not using webapp.

3. Implement upload handler

In this handler, you can store the blob key with the rest of your application's data model. The blob key itself remains accessible from the blob info entity in the datastore. Note that after the user submits the form and your handler is called, the blob has already been saved and the blob info added to the datastore. If your application doesn't want to keep the blob, you should delete the blob immediately to prevent it from becoming orphaned:

class PhotoUploadHandler(blobstore_handlers.BlobstoreUploadHandler):
    def post(self):
        upload = self.get_uploads()[0]
        user_photo = UserPhoto(
            user=users.get_current_user().user_id(), blob_key=upload.key()
        )
        user_photo.put()

        self.redirect("/view_photo/%s" % upload.key())

The webapp framework provides the blobstore_handlers.BlobstoreUploadHandler upload handler class to help you parse the form data. For more information, see the reference for BlobstoreUploadHandler.

Note: Even if you are using the webapp2 framework, you will still need to use the Blobstore handlers provided by the old webapp framework. These handlers are specific to the App Engine Blobstore service, whereas webapp2 is provided by a third party.

When the Blobstore rewrites the user's request, the MIME parts of the uploaded files have their bodies emptied, and the blob key is added as a MIME part header. All other form fields and parts are preserved and passed to the upload handler. If you don't specify a content type, the Blobstore will try to infer it from the file extension. If no content type can be determined, the newly created blob is assigned content type application/octet-stream.

Serving a blob

Note: If you are serving images, a more efficient and potentially less-expensive method is to use get_serving_url using the App Engine Images API rather than send_blob. The get_serving_url function lets you serve the image directly, without having to go through your App Engine instances.

To serve blobs, you must include a blob download handler as a path in your application. The application serves a blob by setting a header on the outgoing response. The following sample uses the webapp framework. When using webapp, the handler should pass the blob key for the desired blob to self.send_blob(). In this example, the blob key is passed to the download handler as part of the URL. In practice, the download handler can get the blob key by any means you choose, such as through another method or user action.

class ViewPhotoHandler(blobstore_handlers.BlobstoreDownloadHandler):
    def get(self, photo_key):
        if not blobstore.get(photo_key):
            self.error(404)
        else:
            self.send_blob(photo_key)

The webapp framework provides the download handler class blobstore_handlers.BlobstoreDownloadHandler to help you parse the form data. For more information, see the reference for BlobstoreDownloadHandler.

Note: Even if you are using the webapp2 framework, you will still need to use the Blobstore handlers provided by the old webapp framework. These handlers are specific to the App Engine Blobstore service, whereas webapp2 is provided by a third party.

Blobs can be served from any application URL. To serve a blob in your application, you put a special header in the response containing the blob key. App Engine replaces the body of the response with the content of the blob.

Blob byte ranges

The Blobstore supports serving part of a large value instead of the full value in response to a request. To serve a partial value, include the X-AppEngine-BlobRange header in the outgoing response. Its value is a standard HTTP byte range. The byte numbering is zero-based. A blank X-AppEngine-BlobRange instructs the API to ignore the range header and serve the full blob. Example ranges include:

• 0-499 serves the first 500 bytes of the value (bytes 0 through 499, inclusive).
• 500-999 serves 500 bytes starting with the 501st byte.
• 500- serves all bytes starting with the 501st byte to the end of the value.
• -500 serves the last 500 bytes of the value.

If the byte range is valid for the Blobstore value, the Blobstore sends a 206 Partial Content status code and the requested byte range to the client. If the range is not valid for the value, the Blobstore sends 416 Requested Range Not Satisfiable.

The Blobstore does not support multiple byte ranges in a single request (for example, 100-199,200-299), whether or not they overlap.

The webapp.blobstore_handlers.BlobstoreDownloadHandler class includes features for setting this header using provided byte indices, and for deriving the byte range automatically from a range header provided by the user.

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.

from google.appengine.api import users
from google.appengine.ext import blobstore
from google.appengine.ext import ndb
from google.appengine.ext.webapp import blobstore_handlers
import webapp2


# This datastore model keeps track of which users uploaded which photos.
class UserPhoto(ndb.Model):
    user = ndb.StringProperty()
    blob_key = ndb.BlobKeyProperty()


class PhotoUploadFormHandler(webapp2.RequestHandler):
    def get(self):
        upload_url = blobstore.create_upload_url("/upload_photo")
        # To upload files to the blobstore, the request method must be "POST"
        # and enctype must be set to "multipart/form-data".
        self.response.out.write(
            """
<html><body>
<form action="{0}" method="POST" enctype="multipart/form-data">
  Upload File: <input type="file" name="file"><br>
  <input type="submit" name="submit" value="Submit">
</form>
</body></html>""".format(
                upload_url
            )
        )


class PhotoUploadHandler(blobstore_handlers.BlobstoreUploadHandler):
    def post(self):
        upload = self.get_uploads()[0]
        user_photo = UserPhoto(
            user=users.get_current_user().user_id(), blob_key=upload.key()
        )
        user_photo.put()

        self.redirect("/view_photo/%s" % upload.key())




class ViewPhotoHandler(blobstore_handlers.BlobstoreDownloadHandler):
    def get(self, photo_key):
        if not blobstore.get(photo_key):
            self.error(404)
        else:
            self.send_blob(photo_key)




app = webapp2.WSGIApplication(
    [
        ("/", PhotoUploadFormHandler),
        ("/upload_photo", PhotoUploadHandler),
        ("/view_photo/([^/]+)?", ViewPhotoHandler),
    ],
    debug=True,
)

Using the Images service with the Blobstore

The Images service can use a Blobstore value as the source of a transformation. The source image can be as large as the maximum size for a Blobstore value. The Images service still returns the transformed image to the application, so the transformed image must be smaller than 32 megabytes. This is useful for making thumbnail images of large photographs uploaded by users.

For information on using the Images service with Blobstore values, see the Images Service documentation.

Using the Blobstore API with Google Cloud Storage

You can use the Blobstore API to store blobs in Cloud Storage instead of storing them in Blobstore. You need to set up a bucket as described in the Google Cloud Storage documentation and specify the bucket and filename in the blobstore.blobstore.create_upload_url gs_bucket_name parameter. In your upload handler, you need to process the returned FileInfo metadata and explicitly store the Google Cloud Storage filename needed to retrieve the blob later.

You can also serve Cloud Storage objects using the Blobstore API. The following code snippets shows how to do this:

# Copyright 2021 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""A sample app that operates on GCS files with blobstore API."""

import cloudstorage
from google.appengine.api import app_identity
from google.appengine.ext import blobstore
from google.appengine.ext.webapp import blobstore_handlers
import webapp2


# This handler creates a file in Cloud Storage using the cloudstorage
# client library and then reads the data back using the Blobstore API.
class CreateAndReadFileHandler(webapp2.RequestHandler):
    def get(self):
        # Get the default Cloud Storage Bucket name and create a file name for
        # the object in Cloud Storage.
        bucket = app_identity.get_default_gcs_bucket_name()

        # Cloud Storage file names are in the format /bucket/object.
        filename = "/{}/blobstore_demo".format(bucket)

        # Create a file in Google Cloud Storage and write something to it.
        with cloudstorage.open(filename, "w") as filehandle:
            filehandle.write("abcde\n")

        # In order to read the contents of the file using the Blobstore API,
        # you must create a blob_key from the Cloud Storage file name.
        # Blobstore expects the filename to be in the format of:
        # /gs/bucket/object
        blobstore_filename = "/gs{}".format(filename)
        blob_key = blobstore.create_gs_key(blobstore_filename)

        # Read the file's contents using the Blobstore API.
        # The last two parameters specify the start and end index of bytes we
        # want to read.
        data = blobstore.fetch_data(blob_key, 0, 6)

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

        # Delete the file from Google Cloud Storage using the blob_key.
        blobstore.delete(blob_key)


# This handler creates a file in Cloud Storage using the cloudstorage
# client library and then serves the file back using the Blobstore API.
class CreateAndServeFileHandler(blobstore_handlers.BlobstoreDownloadHandler):
    def get(self):
        # Get the default Cloud Storage Bucket name and create a file name for
        # the object in Cloud Storage.
        bucket = app_identity.get_default_gcs_bucket_name()

        # Cloud Storage file names are in the format /bucket/object.
        filename = "/{}/blobstore_serving_demo".format(bucket)

        # Create a file in Google Cloud Storage and write something to it.
        with cloudstorage.open(filename, "w") as filehandle:
            filehandle.write("abcde\n")

        # In order to read the contents of the file using the Blobstore API,
        # you must create a blob_key from the Cloud Storage file name.
        # Blobstore expects the filename to be in the format of:
        # /gs/bucket/object
        blobstore_filename = "/gs{}".format(filename)
        blob_key = blobstore.create_gs_key(blobstore_filename)

        # BlobstoreDownloadHandler serves the file from Google Cloud Storage to
        # your computer using blob_key.
        self.send_blob(blob_key)


app = webapp2.WSGIApplication(
    [
        ("/", CreateAndReadFileHandler),
        ("/blobstore/read", CreateAndReadFileHandler),
        ("/blobstore/serve", CreateAndServeFileHandler),
    ],
    debug=True,
)

Note: Once you obtain a blobKey for the Google Cloud Storage object, you can pass it around, serialize it, and otherwise use it interchangeably anywhere you can use a blobKey for objects stored in Blobstore. This allows for usage where an app stores some data in blobstore and some in Google Cloud Storage, but treats the data otherwise identically by the rest of the app. (However, BlobInfo objects are not available for Google Cloud Storage objects.)

Using BlobReader

An application can read data from Blobstore values using an interface similar to a Python file object. This interface can start reading a value at any byte position, and uses multiple service calls and buffering, so an application can access the full size of the value despite the limit on the size of a single service call response.

The BlobReader class can take one of three values as an argument to its constructor:

• A BlobKey
• The string form of a BlobKey
• A BlobInfo object

The object implements the familiar file methods for reading the value. The application cannot modify the Blobstore value; file methods for writing are not implemented.

# 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)

Making asynchronous requests

An application can call some Blobstore functions that work in the background. Blobstore carries out the request while the application does other things. To make the request, the application calls an asynchronous function. The function immediately returns an RPC object; this object represents the request. When the application needs the result of the request, it calls the RPC object's get_result() method.

If the service has not completed the request when the application calls get_result(), the method waits until the request is complete (or has reached the deadline, or an error occurs). The method returns the result object, or raises an exception if an error occurred while carrying out the request. For example, this code snippet

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

becomes

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)

In this example, the application carries out the slow_operation() code at the same time that Blobstore generates the upload URL.

Quotas and limits

Space used for Blobstore values contributes to the Stored Data (billable) quota. Blob info entities in the datastore count towards datastore-related limits. Notice that Google Cloud Storage is a pay-to-use service; you will be charged according to the Cloud Storage price sheet.

For more information on system-wide safety quotas, see Quotas.

In addition to system-wide safety quotas, the following limits apply specifically to the use of the Blobstore:

• The maximum size of Blobstore data that can be read by the application with one API call is 32 megabytes.
• The maximum number of files that can be uploaded in a single form POST is 500.