Ringkasan Blobstore API untuk layanan paket lama

Go Java PHP Python

Catatan: Anda harus mempertimbangkan untuk menggunakan Cloud Storage daripada Blobstore untuk menyimpan data blob.

Blobstore API memungkinkan aplikasi Anda menyajikan objek data, yang disebut blob, dengan ukuran yang jauh lebih besar dari ukuran yang diizinkan untuk objek dalam layanan Datastore. Blob berguna untuk menyajikan file besar, seperti file video atau gambar, dan untuk memungkinkan pengguna mengupload file data berukuran besar. Blob dibuat dengan mengupload file melalui permintaan HTTP. Biasanya, aplikasi Anda akan melakukannya dengan menampilkan formulir yang berisi kolom upload file kepada pengguna. Saat formulir dikirimkan, Blobstore akan membuat blob dari konten file dan menampilkan referensi tersembunyi ke blob, yang disebut kunci blob yang nantinya dapat digunakan untuk menyajikan blob. Aplikasi dapat menyajikan nilai blob lengkap sebagai respons terhadap permintaan pengguna, atau dapat membaca nilai secara langsung menggunakan antarmuka seperti file streaming.

Memperkenalkan Blobstore

App Engine mencakup layanan Blobstore, yang memungkinkan aplikasi menyajikan objek data yang hanya dibatasi oleh jumlah data yang dapat diupload atau didownload melalui satu koneksi HTTP. Objek ini disebut nilai Blobstore atau blob. Nilai Blobstore berfungsi sebagai respons dari pengendali permintaan dan dibuat sebagai file yang diupload melalui formulir web. Aplikasi tidak membuat data blob secara langsung; sebagai gantinya, blob dibuat secara tidak langsung oleh formulir web yang dikirimkan atau permintaan POST HTTP lainnya. Nilai Blobstore dapat disajikan kepada pengguna, atau diakses oleh aplikasi dalam aliran data seperti file, menggunakan Blobstore API.

Catatan: Blob yang ditetapkan oleh layanan Blobstore tidak terkait dengan nilai properti blob yang digunakan oleh datastore.

Untuk meminta pengguna mengupload nilai Blobstore, aplikasi Anda harus menyajikan formulir web dengan kolom upload file. Aplikasi ini membuat URL tindakan formulir dengan memanggil Blobstore API. Browser pengguna mengupload file langsung ke Blobstore melalui URL yang dibuat. Blobstore kemudian menyimpan blob, menulis ulang permintaan untuk memuat kunci blob, dan meneruskannya ke jalur dalam aplikasi Anda. Pengendali permintaan di jalur tersebut dalam aplikasi Anda bisa melakukan pemrosesan formulir tambahan.

Untuk menyajikan blob, aplikasi Anda menetapkan header pada respons keluar, dan App Engine mengganti respons tersebut dengan nilai blob.

Blob tidak dapat diubah setelah dibuat, meskipun dapat dihapus. Setiap blob memiliki catatan info blob yang sesuai dan tersimpan di datastore, yang memberikan detail tentang blob, seperti waktu pembuatan dan jenis kontennya. Anda dapat menggunakan kunci blob untuk mengambil catatan info blob dan mengkueri propertinya.

Aplikasi dapat membaca nilai Blobstore sebagian dalam satu waktu menggunakan panggilan API. Ukuran bagian dapat mencapai ukuran maksimum dari nilai yang ditampilkan API. Ukuran ini kurang dari 32 megabyte, yang direpresentasikan di Python oleh konstanta google.appengine.ext.blobstore.MAX_BLOB_FETCH_SIZE . Aplikasi tidak dapat membuat atau mengubah nilai Blobstore, kecuali melalui file yang diupload oleh pengguna.

Menggunakan Blobstore

Aplikasi dapat menggunakan Blobstore untuk menerima file besar sebagai upload dari pengguna dan menyajikan file tersebut. File disebut blob setelah diupload. Aplikasi tidak mengakses blob secara langsung, sebagai gantinya, aplikasi bekerja dengan blob melalui entity info blob (diwakili oleh class BlobInfo ) di Datastore.

Pengguna membuat blob dengan mengirimkan formulir HTML yang menyertakan satu atau beberapa kolom input file. Aplikasi Anda panggilan blobstore.create_upload_url() untuk mendapatkan tujuan (tindakan) formulir ini, dengan meneruskan fungsi jalur URL pengendali di aplikasi Anda. Saat pengguna mengirimkan formulir, browser pengguna akan mengupload file yang ditentukan langsung ke Blobstore. Blobstore menulis ulang permintaan pengguna dan menyimpan data file yang diupload, mengganti data file yang diupload dengan satu atau beberapa kunci blob yang sesuai, lalu meneruskan permintaan yang ditulis ulang ke pengendali di jalur URL yang Anda berikan ke blobstore.create_upload_url() .

Pengendali ini dapat melakukan pemrosesan tambahan berdasarkan kunci blob.

Aplikasi ini dapat membaca bagian dari nilai Blobstore menggunakan antarmuka streaming yang mirip file. antarmuka streaming yang mirip file. Lihat class BlobReader.

Mengupload blob

Untuk membuat dan mengupload blob, ikuti prosedur berikut:

1. Membuat URL upload

Panggil blobstore.create_upload_url() guna membuat URL upload untuk formulir yang akan diisi pengguna, yang meneruskan jalur aplikasi yang akan dimuat saat POST formulir selesai.

upload_url = blobstore.create_upload_url("/upload_photo")

Ada versi asinkron, create_upload_url_async(). Fungsi ini memungkinkan kode aplikasi Anda tetap berjalan sementara Blobstore membuat URL upload.

2. Membuat formulir upload

Formulir harus menyertakan kolom upload file, dan enctype formulir harus ditetapkan ke multipart/form-data. Saat pengguna mengirimkan formulir, POST akan ditangani oleh Blobstore API, yang membuat blob. API ini juga membuat catatan info untuk blob dan menyimpan catatan di Datastore, lalu meneruskan permintaan yang ditulis ulang ke aplikasi Anda di jalur yang diberikan sebagai kunci blob.

Anda harus menyajikan halaman formulir dengan Content-Type dari text/html; charset=utf-8. Jika tidak, nama file apa pun dengan karakter non-ASCII akan disalahartikan.
Karena Blobstore untuk Python 3 tidak menggunakan webapp, Anda harus menetapkan Content-Type sendiri untuk mencegah framework web menetapkan jenis konten default dan App Engine menetapkannya ke jenis yang diperkirakan.

Anda tidak dapat menggunakan Load Balancer Aplikasi eksternal global dengan NEG Serverless untuk menangani permintaan upload yang dikirim ke URL /_ah/upload/ yang ditampilkan dari panggilan blobstore.create_upload_url. Sebagai gantinya, Anda harus merutekan permintaan upload tersebut langsung ke layanan App Engine. Anda dapat melakukannya dengan menggunakan domain appspot.com atau domain kustom yang dipetakan langsung ke layanan App Engine.

3. Menerapkan pengendali upload

Dalam pengendali ini, Anda dapat menyimpan kunci blob bersama model data aplikasi lainnya. Kunci blob itu sendiri tetap dapat diakses dari entity info blob di Datastore. Perhatikan bahwa setelah pengguna mengirimkan formulir dan pengendali Anda dipanggil, blob telah disimpan dan info blob ditambahkan ke Datastore. Jika aplikasi Anda tidak ingin menyimpan blob, Anda harus segera menghapus blob agar tidak menjadi telantar.

Untuk semua aplikasi Flask, semua panggilan yang dilakukan ke metode di BlobstoreUploadHandler class memerlukan request.environ dictionary (permintaan diimpor dari modul flask). Jika aplikasi Anda adalah aplikasi WSGI tanpa framework web, Anda menggunakan parameter environ dalam metode get_uploads(). Saat menulis ulang permintaan pengguna, Blobstore mengosongkan bagian MIME dari file yang diupload dan menambahkan kunci blob sebagai header bagian MIME. Blobstore mempertahankan semua kolom dan bagian formulir lainnya, meneruskannya ke pengendali upload. Jika Anda tidak menentukan jenis konten, Blobstore akan mencoba menyimpulkannya dari ekstensi file. Jika tidak dapat menentukan jenis konten, Blobstore akan menetapkan jenis konten application/octet-stream ke blob yang baru dibuat.

Menyajikan blob

Catatan: Jika Anda menyajikan gambar, metode yang lebih efisien dan berpotensi lebih hemat adalah menggunakan get_serving_url dengan App Engine Images API bukan send_blob . Metode get_serving_url memungkinkan Anda menyajikan gambar secara langsung, tanpa harus melalui instance App Engine.

Untuk menyajikan blob, Anda harus menyertakan pengendali download blob sebagai jalur dalam aplikasi Anda. Aplikasi menyajikan blob dengan menyetel header pada respons keluar. Jika menggunakan Flask, class BlobstoreDownloadHandler memerlukan request.environ dictionary (permintaan diimpor dari modul flask). Jika aplikasi Anda adalah aplikasi WSGI tanpa framework web, Anda menggunakan parameter environ dalam metode send_blob().

Blob dapat disajikan dari URL aplikasi apa pun. Untuk menyajikan blob dalam aplikasi Anda, tempatkan header khusus dalam respons yang berisi kunci blob. App Engine mengganti isi respons dengan konten blob.

Rentang byte Blob

Blobstore mendukung penyajian sebagian dari nilai yang besar, bukan nilai penuh, sebagai respons atas permintaan. Untuk menyajikan nilai parsial, sertakan header X-AppEngine-BlobRange dalam respons keluar. Nilainya adalah rentang byte HTTP standar. Penomoran byte berbasis nol. X-AppEngine-BlobRange kosong menginstruksikan API untuk mengabaikan header rentang dan menyajikan blob lengkap. Contoh rentang mencakup:

• 0-499 menyajikan 500 byte pertama dari nilai (0 hingga 499 byte, inklusif).
• 500-999 menyajikan 500 byte dimulai dari byte 501.
• 500- menyajikan semua byte yang dimulai dari byte 501 hingga akhir nilai.
• -500 menyajikan 500 byte terakhir dari nilai.

Jika rentang byte valid untuk nilai Blobstore, Blobstore akan mengirimkan kode status 206 Partial Content dan rentang byte yang diminta ke klien. Jika rentang tidak valid untuk nilai tersebut, Blobstore akan mengirim 416 Requested Range Not Satisfiable.

Blobstore tidak mendukung beberapa rentang byte dalam satu permintaan (misalnya 100-199,200-299), terlepas dari apakah keduanya tumpang-tindih atau tidak.

Menyelesaikan aplikasi contoh

Lihat contoh aplikasi Flask di panduan Blobstore API untuk Python 3.

Menggunakan layanan Gambar dengan Blobstore

Layanan Gambar dapat menggunakan nilai Blobstore sebagai sumber transformasi. Ukuran gambar sumber bisa sebesar ukuran maksimum untuk nilai Blobstore. Layanan Gambar tetap menampilkan gambar yang ditransformasi ke aplikasi, sehingga ukuran gambar yang ditransformasi harus lebih kecil dari 32 megabyte. Hal ini berguna untuk membuat gambar thumbnail foto besar yang diupload oleh pengguna. Untuk mengetahui informasi tentang penggunaan layanan Gambar dengan nilai Blobstore, lihat Dokumentasi Layanan Gambar.

Menggunakan Blobstore API dengan Cloud Storage

Anda dapat menggunakan Blobstore API untuk menyimpan blob di Cloud Storage, bukan menyimpannya di Blobstore. Anda harus menyiapkan bucket seperti yang dijelaskan dalam dokumentasi Cloud Storage dan menentukan bucket serta nama file dalam blobstore.create_upload_url gs_bucket_name.

Di pengendali upload, Anda perlu memproses FileInfo dan secara eksplisit menyimpan nama file Cloud Storage yang diperlukan untuk mengambil blob nanti.

Anda juga dapat menyajikan objek Cloud Storage menggunakan API Blobstore.

Catatan: Setelah Anda mendapatkan blobKey untuk objek Cloud Storage, Anda dapat meneruskannya, melakukan serialisasi, dan menggunakannya secara bergantian di mana pun Anda dapat menggunakan blobKey untuk objek yang disimpan di Blobstore. Hal ini memungkinkan penggunaan saat aplikasi menyimpan beberapa data di blobstore dan sebagian di Cloud Storage, tetapi memperlakukan data tersebut secara identik oleh aplikasi lainnya. (Namun, objek BlobInfo tidak tersedia untuk objek Cloud Storage.)

Jika Anda menginginkan solusi penyimpanan objek yang lebih modern, pertimbangkan untuk bermigrasi dari Blobstore App Engine ke Cloud Storage.

Menggunakan BlobReader

Aplikasi dapat membaca data dari nilai Blobstore menggunakan antarmuka yang mirip dengan objek file Python. Antarmuka ini dapat mulai membaca nilai pada posisi byte apa pun, dan menggunakan beberapa panggilan layanan serta buffering, sehingga aplikasi dapat mengakses ukuran penuh nilai meskipun ada batasan ukuran respons panggilan layanan tunggal.

Class BlobReader dapat menggunakan salah satu dari tiga nilai sebagai argumen untuk konstruktornya:

• BlobKey
• Format string BlobKey
• Objek BlobInfo

Objek ini mengimplementasikan metode file yang sudah dikenal untuk membaca nilai. Aplikasi tidak dapat mengubah nilai Blobstore; metode file untuk menulis tidak diterapkan.

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

Membuat permintaan asinkron

Aplikasi dapat memanggil beberapa fungsi Blobstore yang bekerja di latar belakang. Blobstore melakukan permintaan ketika aplikasi melakukan hal-hal lain. Untuk membuat permintaan, aplikasi memanggil fungsi asinkron. Fungsi ini segera menampilkan objek RPC; objek ini mewakili permintaan. Saat memerlukan hasil permintaan, aplikasi akan memanggil metode get_result() objek RPC.

Jika layanan belum menyelesaikan permintaan saat aplikasi memanggil get_result(), metode akan menunggu hingga permintaan selesai (atau telah mencapai batas waktu, atau terjadi error). Metode ini menampilkan objek hasil, atau memunculkan pengecualian jika terjadi error saat menjalankan permintaan. Misalnya, cuplikan kode ini

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

menjadi

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)

Dalam contoh ini, aplikasi menjalankan kode slow_operation() pada saat yang sama ketika Blobstore membuat URL upload.

Kuota dan batas

Ruang yang digunakan untuk nilai Blobstore berkontribusi pada kuota Data Tersimpan (dapat ditagih). Entity info Blob di Datastore diperhitungkan dalam batas terkait Datastore. Perhatikan bahwa Cloud Storage adalah layanan bayar sesuai penggunaan; Anda akan dikenai biaya sesuai dengan lembar harga Cloud Storage.

Untuk mengetahui informasi selengkapnya tentang kuota keamanan di seluruh sistem, lihat Kuota.

Selain kuota keamanan di seluruh sistem, batas berikut berlaku khusus untuk penggunaan Blobstore:

• Ukuran maksimum data Blobstore yang dapat dibaca oleh aplikasi dengan satu panggilan API adalah 32 megabyte.
• Jumlah file maksimum yang dapat diupload dalam satu format POST adalah 500.