Descripción general de la API de Blobstore para servicios agrupados en paquetes heredados

Go Java PHP Python

Nota: Considera usar Cloud Storage en lugar de Blobstore para almacenar datos BLOB

La API de Blobstore permite que tu aplicación entregue objetos de datos, llamados blobs, que son mucho más grandes que el tamaño permitido para los objetos en el servicio de Datastore. Los BLOB son útiles en la entrega de archivos grandes, como archivos de video o de imagen, y para permitir que los usuarios suban archivos de datos grandes. Los BLOB se crean cuando subes un archivo a través de una solicitud HTTP. Por lo general, las aplicaciones realizarán esta acción con un formulario para el usuario con un campo de carga de archivos. Cuando se envía el formulario, Blobstore crea un BLOB a partir del contenido del archivo y muestra una referencia opaca al BLOB, llamada clave de BLOB, que luego puedes usar para entregar el BLOB. La aplicación puede entregar el valor completo del blob en respuesta a una solicitud del usuario, o puede leer el valor de forma directa a través de una interfaz similar a un archivo de transmisión.

Presentación de Blobstore

App Engine incluye el servicio Blobstore, que permite a las aplicaciones entregar objetos de datos limitados solo por la cantidad de datos que se pueden subir o descargar a través de una única conexión HTTP. Estos objetos se denominan valores de Blobstore, o blobs. Los valores de Blobstore se entregan como respuestas a la solicitud de los controladores y se crean como cargas a través de formularios web. Las aplicaciones no crean datos BLOB de forma directa. En cambio, los BLOB se crean de forma indirecta con un formulario web enviado o una solicitud HTTP POST. Los valores de Blobstore se pueden entregar al usuario, o la aplicación puede acceder a ellos en una transmisión similar a archivos, con la API de Blobstore.

Nota: Los BLOB que define el servicio de Blobstore no están relacionados con los valores de propiedad de BLOB que usa el almacén de datos.

Para solicitar a un usuario que suba un valor de Blobstore, tu aplicación presenta un formulario web con un campo de carga de archivos. La aplicación genera la URL de acción del formulario con una llamada a la API de Blobstore. El navegador del usuario sube el archivo de forma directa a Blobstore a través de la URL generada. Luego, Blobstore almacena el BLOB, reescribe la solicitud para que contenga la clave de BLOB y la pasa a una ruta de acceso en la aplicación. Un controlador de solicitudes en esa ruta de tu aplicación puede realizar un procesamiento de formulario adicional.

Para entregar un blob, tu aplicación establece un encabezado en la respuesta saliente y App Engine reemplaza la respuesta con el valor de blob.

Los blobs no se pueden modificar después de que se crean, pero sí borrar. Cada blob tiene un registro de información de blob correspondiente, guardado en el almacén de datos, que proporciona detalles sobre el blob, como su hora de creación y tipo de contenido. Puedes usar la clave del BLOB para obtener registros de información de BLOB y consultar sus propiedades.

Una aplicación puede leer un valor de Blobstore de a una parte a la vez con una llamada a la API. El tamaño de la parte puede tener hasta el máximo de un valor de muestra de API. Este tamaño es un poco menor de 32 megabytes, que se representa en Python con la constante google.appengine.ext.blobstore.MAX_BLOB_FETCH_SIZE. Una aplicación no puede crear ni modificar los valores de Blobstore, excepto a través de archivos que sube el usuario.

Usa Blobstore

Las aplicaciones pueden usar el Blobstore para aceptar archivos grandes como cargas de los usuarios y entregarlos. Una vez que se suben, los archivos se llaman BLOB. Las aplicaciones no acceden a los BLOB de forma directa, en su lugar, de modo que funcionan con BLOB a través de entidades de información de BLOB (representado por la clase BlobInfo ) en Datastore.

El usuario crea un BLOB cuando envía un formulario HTML que incluye uno o más campos de entrada de archivos. Tu aplicación llama a blobstore.create_upload_url() para obtener el destino (acción) de este formulario, pasando a la función una ruta de URL de un controlador en la aplicación. Cuando el usuario envía el formulario, el navegador del usuario sube a Blobstore los archivos especificados. Blobstore reescribe la solicitud del usuario, almacena los datos del archivo subido y los reemplaza por una o más claves de BLOB correspondientes. Luego, pasa la solicitud reescrita al controlador en la ruta de URL que proporcionaste a blobstore.create_upload_url() .

Este controlador puede realizar procesamientos adicionales según la clave de BLOB.

La aplicación puede leer partes de un valor de Blobstore con una interfaz de transmisión similar a archivos. Consulta la clase BlobReader.

Sube un BLOB

Para crear y subir un blob, sigue este procedimiento:

1. Crea una URL de carga

Llama a blobstore.create_upload_url() para crear una URL de carga para el formulario que completará el usuario y pasa la ruta de la aplicación que debe cargarse cuando se complete el POST del formulario.

upload_url = blobstore.create_upload_url("/upload_photo")

Existe una versión asíncrona, create_upload_url_async(). Permite que tu código de la aplicación se siga ejecutando mientras Blobstore genera la URL de carga.

2. Crea un formulario de carga

El formulario debe incluir un campo de carga de archivos y el enctype del formulario debe establecerse como multipart/form-data. Cuando el usuario envía el formulario, se controla el POST con la API de Blobstore, que crea el BLOB. La API también crea un registro de información para el BLOB, y almacena el registro en el almacén de datos y pasa la solicitud reescrita a tu aplicación en la ruta dada como una clave de BLOB.

Nota: Debes entregar la página del formulario con un Content-Type de text/html; charset=utf-8, o cualquier nombre de archivo con caracteres que no sean ASCII se interpretará de forma incorrecta.
Dado que Blobstore para Python 3 no usa webapp, debes configurar tu propio Content-Type para evitar que tu framework web establezca un tipo de contenido predeterminado y que App Engine lo establezca en un tipo adivinado.

3. Implementa un controlador de carga

En este controlador, puedes almacenar la clave de blob con el resto de tu modelo de datos de la aplicación. La clave de blob en sí permanece accesible desde la entidad de información de blob en el almacén de datos. Ten en cuenta que después de que el usuario envíe el formulario y se llame a tu controlador, el blob ya estará guardado y la información agregada al almacén de datos. Si tu aplicación no quiere mantener el BLOB, debes borrarlo de inmediato para evitar que quede suelto.

Para todas las apps de Flask, todas las llamadas realizadas a los métodos en la clase BlobstoreUploadHandler requieren el request.environ dictionary (la solicitud se importa desde el módulo de experimento). Si tu app es una app WSGI sin un framework web, debes usar el parámetro environ en el método get_uploads().

Cuando Blobstore reescribe la solicitud del usuario, se vacían los cuerpos de las partes MIME de los archivos subidos y se agrega la clave BLOB como parte del encabezado MIME. Todos los demás campos de formulario y las partes se conservan y se pasan al controlador de carga. Si no especificas un tipo de contenido, Blobstore intentará inferirlo de la extensión del archivo. Si no se puede determinar un tipo de contenido, se asigna el tipo de contenido application/octet-stream al BLOB recién creado.

Entrega un BLOB

Nota: Si entregas imágenes, un método más eficiente y menos costoso es usar get_serving_url a través de la API de imágenes de App Engine, en lugar de send_blob . La get_serving_url de método te permite entregar la imagen de forma directa, sin tener que pasar por las instancias de App Engine.

Para entregar BLOB, debes incluir un controlador de descarga de BLOB como una ruta en tu aplicación. La aplicación entrega un BLOB a través de la configuración de un encabezado en la respuesta saliente. Si usas Flask, la clase BlobstoreDownloadHandler requiere el diccionario request.environ (la solicitud se importa desde el módulo de experimento). Si tu app es una app WSGI sin un framework web, debes usar el parámetro environ en los métodos send_blob().. Los BLOB se pueden entregar desde cualquier URL de aplicación. Para entregar un BLOB en la aplicación, debes colocar un encabezado especial en la respuesta que contiene la clave de BLOB. App Engine reemplaza el cuerpo de la respuesta por el contenido del BLOB.

Rangos de bytes de BLOB

Blobstore admite la entrega de parte de un valor grande en lugar del valor completo en respuesta a una solicitud. Para entregar un valor parcial, incluye el encabezado X-AppEngine-BlobRange en la respuesta saliente. El valor es un rango de byte HTTP estándar. La numeración de bytes está basada en cero. Un X-AppEngine-BlobRange en blanco indica a la API que ignore el encabezado del rango y entregue el BLOB completo. Los rangos de ejemplo incluyen lo siguiente:

• 0-499 entrega los primeros 500 bytes del valor (bytes 0 a 499, inclusive).
• 500-999 entrega 500 bytes a partir del byte 501.
• 500- entrega todos los bytes desde el byte 501 hasta el final del valor.
• -500 entrega los últimos 500 bytes del valor.

Si el rango de bytes es válido para el valor de Blobstore, este envía un código de estado 206 Partial Content y el rango de bytes solicitado al cliente. Si el rango no es válido para el valor, Blobstore envía 416 Requested Range Not Satisfiable.

Blobstore no admite varios rangos de bytes en una sola solicitud (por ejemplo, 100-199,200-299), sin importar si se superponen o no.

Aplicación de muestra completa

Consulta el ejemplo de la app de Flask en la guía de la API de Blobstore para Python 3.

Usa el servicio de Imágenes con Blobstore

Con el servicio de imágenes, se puede usar un valor de Blobstore como la fuente de una transformación. La imagen fuente puede ser tan grande como el tamaño máximo de un valor de Blobstore. El servicio de imágenes aún muestra la imagen transformada a la aplicación, por lo que esta imagen debe ser menor de 32 megabytes. Esto es útil para crear imágenes en miniatura de fotografías grandes subidas por los usuarios. Para obtener información del uso de servicios de imagen con valores Blobstore, consulta la Documentación sobre el servicio de imágenes.

Usa la API de Blobstore con Cloud Storage

Puedes usar la API de Blobstore para almacenar BLOB en Cloud Storage en lugar de almacenarlos en Blobstore. Debes configurar un bucket como se describe en la documentación de Cloud Storage y especificar el bucket y el nombre de archivo en el blobstore.create_upload_url gs_bucket_name parámetro.

En el controlador de carga, debes procesar el valor que se muestra. FileInfo metadatosy almacenar de forma explícita el nombre de archivo de Cloud Storage necesario para recuperar el BLOB más tarde.

También puedes entregar objetos de Cloud Storage mediante la API de Blobstore.

Nota: Una vez que obtengas una blobKeypara el objeto de Cloud Storage, puedes pasarlo, serializarlo y usarlo de forma intercambiable en cualquier lugar en el que puedas usar una blobKey en los objetos almacenados en Blobstore. Esto permite el uso en el caso que una app almacene algunos datos en blobstore y otros en Cloud Storage, pero trate los datos de otra manera idéntica en el resto de la app (sin embargo, los objetos BlobInfo no están disponibles para los objetos de Cloud Storage).

Si deseas una solución de almacenamiento de objetos más moderna, considera migrar de Blobstore App Engine a Cloud Storage.

Usa BlobReader

Una aplicación puede leer datos de los valores de Blobstore con una interfaz similar a un objeto file de Python. Esta interfaz puede comenzar a leer un valor en cualquier posición de byte y usa varias llamadas de servicio y almacenamiento en búfer, por lo que una aplicación puede acceder al tamaño completo del valor a pesar del límite de tamaño de una única respuesta a una llamada de servicio.

La clase BlobReader puede tomar uno de los tres valores como un argumento para el constructor:

• Un objeto BlobKey
• El formulario de string de un BlobKey
• Un objeto BlobInfo

El objeto implementa los métodos de archivo familiares para leer el valor. La aplicación no puede modificar el valor de Blobstore. Los métodos de archivo para escribir no están implementados.

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

Realiza solicitudes asíncronas

Una aplicación puede llamar a algunas funciones de Blobstore que funcionan en segundo plano. Blobstore lleva a cabo la solicitud, mientras que la aplicación realiza otras acciones. Para llevar a cabo la solicitud, la aplicación llama a una función asíncrona. La función muestra de inmediato un objeto RPC; este objeto representa la solicitud. Cuando la aplicación necesita el resultado de la solicitud, llama al método get_result() del objeto RPC.

Si el servicio no completó la solicitud cuando la aplicación llama a get_result(), el método espera hasta que se complete la solicitud (o hasta que se cumpla el plazo o se produzca un error). El método muestra el objeto de resultado o genera una excepción si se produjo un error cuando se realizó la solicitud. Por ejemplo, este fragmento de código

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

se convierte en

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)

En este ejemplo, la aplicación ejecuta el código slow_operation() al mismo tiempo que Blobstore genera la URL de carga.

Cuotas y límites

El espacio usado por los valores de Blobstore contribuyen a la cuota Datos almacenados (facturable). Las entidades de información de blob en el almacén de datos cuentan con los límites relacionados con el almacén de datos. Ten en cuenta que Cloud Storage es un servicio de pago por uso. Se te cobrará de acuerdo con la hoja de precios de Cloud Storage.

Para obtener más información de las cuotas de seguridad en todo el sistema, consulta Cuotas.

Además de las cuotas de seguridad para todo el sistema, los límites siguientes se aplican en específico al uso de Blobstore:

• El tamaño máximo de los datos de Blobstore que puede leer la aplicación con una llamada a la API es de 32 megabytes.
• La cantidad máxima de archivos que pueden subirse en un solo formulario POST es de 500.