L'API Blobstore consente all'applicazione di gestire oggetti di dati, chiamati blob,molto più grandi delle dimensioni consentite per gli oggetti nel servizio Datastore. I BLOB sono utili per pubblicare file di grandi dimensioni, ad esempio file video o immagine, e per consentire agli utenti di caricare file di dati di grandi dimensioni. I BLOB vengono creati caricando un file tramite una richiesta HTTP. In genere, le applicazioni possono farlo presentando all'utente un modulo con un campo di caricamento file. Quando il modulo viene inviato, il Blobstore crea un BLOB dai contenuti del file e restituisce un riferimento opaco al BLOB, chiamato chiave blob,che puoi utilizzare in seguito per pubblicare il BLOB. L'applicazione può fornire il valore completo del blob in risposta alla richiesta di un utente oppure può leggere il valore direttamente utilizzando un'interfaccia simile a un file di inserimento di flussi.
Ti presentiamo Blobstore
Google App Engine include il servizio Blobstore, che consente alle applicazioni di gestire oggetti di dati limitati solo dalla quantità di dati che possono essere caricati o scaricati tramite una singola connessione HTTP. Questi oggetti sono chiamati valori BLOB o BLOB. I valori BLOB vengono forniti come risposte dai gestori delle richieste e vengono creati come caricamenti tramite moduli web. Le applicazioni non creano dati BLOB direttamente, ma vengono creati indirettamente tramite un modulo web inviato o un'altra richiesta POST
HTTP. I valori dell'archivio BLOB possono essere forniti all'utente o accessibili dall'applicazione in uno stream di tipo file, utilizzando l'API Blobstore.
Per richiedere a un utente di caricare un valore Blobstore, la tua applicazione presenta un modulo web con un campo di caricamento file. L'applicazione genera l'URL di azione del modulo chiamando l'API Blobstore. Il browser dell'utente carica il file direttamente nel Blobstore tramite l'URL generato. Blobstore quindi archivia il BLOB, riscrive la richiesta in modo che contenga la chiave BLOB e la passa a un percorso dell'applicazione. Un gestore delle richieste in quel percorso nella tua applicazione può eseguire un'ulteriore elaborazione dei moduli.
Per gestire un BLOB, l'applicazione imposta un'intestazione sulla risposta in uscita e App Engine sostituisce la risposta con il valore del BLOB.
I BLOB non possono essere modificati dopo la creazione, ma possono essere eliminati. A ogni BLOB è associato un record di informazioni sul BLOB, archiviato nel datastore, che fornisce i dettagli sul BLOB, ad esempio data e ora di creazione e tipo di contenuti. Puoi utilizzare la chiave BLOB per recuperare record con informazioni sui BLOB ed eseguire query sulle relative proprietà.
Un'applicazione può leggere un valore Blobstore una parte alla volta utilizzando una chiamata API. La dimensione della parte può arrivare fino alla dimensione massima di un valore restituito dall'API. Queste dimensioni sono di poco meno di 32 megabyte, rappresentati in Python dalla costante google.appengine.ext.blobstore.MAX_BLOB_FETCH_SIZE
. Un'applicazione non può creare o modificare i valori Blobstore se non tramite i file caricati dall'utente.
Utilizzo dell'archivio BLOB
Le applicazioni possono utilizzare l'archivio BLOB per accettare file di grandi dimensioni come caricamenti degli utenti e pubblicarli. Una volta caricati, i file vengono chiamati BLOB. Le applicazioni non accedono direttamente ai BLOB. Le applicazioni funzionano invece con i BLOB tramite entità di informazioni BLOB (rappresentate dalla classe BlobInfo
) nel datastore.
L'utente crea un blob inviando un modulo HTML che includa uno o più campi di immissione file. L'applicazione chiama create_upload_url()
per ottenere la destinazione (azione) di questo modulo, trasmettendo alla funzione il percorso dell'URL di un gestore nell'applicazione. Quando l'utente invia il modulo, il browser carica i file specificati direttamente nel Blobstore. Il Blobstore riscrive la richiesta dell'utente e archivia i dati del file caricato, sostituendo questi dati con una o più chiavi BLOB corrispondenti, quindi passa la richiesta riscritta al gestore nel percorso dell'URL che hai fornito a create_upload_url()
. Questo gestore può eseguire elaborazioni aggiuntive in base alla chiave BLOB.
L'applicazione può leggere parti di un valore Blobstore utilizzando un'interfaccia di inserimento di flussi di tipo file. Vedi Il corso BlobReader
.
Caricamento di un blob
Per creare e caricare un BLOB, segui questa procedura:
1. Creare un URL di caricamento
Chiama blobstore.create_upload_url()
per creare un URL di caricamento per il modulo che l'utente compilerà, trasmettendo il percorso della domanda da caricare una volta completato il campo POST
del modulo.
Esiste una versione asincrona, create_upload_url_async()
. Consente all'applicazione di continuare a eseguire il codice dell'applicazione mentre Blobstore genera l'URL di caricamento.
2. Crea un modulo di caricamento
Il modulo deve includere un campo di caricamento file e il valore enctype
del modulo deve essere impostato su multipart/form-data
. Quando l'utente invia il modulo, il POST
viene gestito dall'API Blobstore, che crea il blob. L'API crea inoltre un record di informazioni per il BLOB e lo archivia nel datastore, quindi passa la richiesta riscritta all'applicazione nel percorso specificato come chiave BLOB.
3. Implementare il gestore dei caricamenti
In questo gestore puoi archiviare la chiave BLOB con il resto del modello dei dati dell'applicazione. La chiave BLOB rimane accessibile dall'entità info BLOB nel datastore. Tieni presente che, dopo che l'utente invia il modulo e che il gestore è stato chiamato, il blob è già stato salvato e le informazioni sul blob sono state aggiunte al datastore. Se la tua applicazione non vuole conservare il BLOB, devi eliminarlo immediatamente per evitare che diventi orfano:
Il webapp framework fornisce la classe del gestore dei caricamenti blobstore_handlers.BlobstoreUploadHandler
per aiutarti ad analizzare i dati del modulo. Per saperne di più, consulta la riferimento per BlobstoreUploadHandler
.
Quando il Blobstore riscrive la richiesta dell'utente, il corpo delle parti MIME dei file caricati viene svuotato e la chiave blob viene aggiunta come intestazione di parte MIME. Tutti gli altri campi e le altre parti del modulo vengono conservati e passati al gestore del caricamento. Se non specifichi un tipo di contenuto, Blobstore proverà a deducerlo dall'estensione del file. Se non è possibile determinare il tipo di contenuto, al blob appena creato viene assegnato il tipo di contenuto application/octet-stream
.
Pubblicazione di un BLOB
Per pubblicare i BLOB, devi includere un gestore del download dei BLOB come percorso nell'applicazione. L'applicazione gestisce un BLOB impostando un'intestazione sulla risposta in uscita. L'esempio seguente utilizza il framework webapp
. Quando utilizzi webapp
, il gestore deve passare a self.send_blob()
la chiave del blob desiderato. In questo esempio, la chiave BLOB viene passata al gestore dei download come parte dell'URL. In pratica, il gestore dei download può ottenere la chiave blob con qualsiasi mezzo scelto, ad esempio con un altro metodo o con un'altra azione utente.
Il webapp framework fornisce la classe del gestore dei download blobstore_handlers.BlobstoreDownloadHandler
per aiutarti ad analizzare i dati del modulo. Per saperne di più, consulta la riferimento per BlobstoreDownloadHandler
.
I BLOB possono essere pubblicati da qualsiasi URL dell'applicazione. Per pubblicare un BLOB nella tua applicazione, inserisci un'intestazione speciale nella risposta contenente la chiave del BLOB. App Engine sostituisce il corpo della risposta con il contenuto del BLOB.
Intervalli di byte BLOB
Blobstore supporta la pubblicazione di parte di un valore elevato anziché dell'intero valore in risposta a una richiesta. Per pubblicare un valore parziale, includi l'intestazione X-AppEngine-BlobRange
nella risposta in uscita. Il suo valore è un intervallo di byte HTTP standard. La numerazione in byte è in base a zero. Un elemento X-AppEngine-BlobRange
vuoto indica all'API di ignorare l'intestazione dell'intervallo e pubblicare il blob completo. Gli intervalli di esempio includono:
0-499
gestisce i primi 500 byte del valore (byte da 0 a 499 inclusi).500-999
gestisce 500 byte a partire dal 501 byte.500-
gestisce tutti i byte a partire dal 501° byte fino alla fine del valore.-500
gestisce gli ultimi 500 byte del valore.
Se l'intervallo di byte è valido per il valore dell'archivio BLOB, l'archivio BLOB invia un codice di stato 206
Partial
Content
e l'intervallo di byte richiesto al client. Se l'intervallo non è valido per il valore, l'archivio BLOB invia 416
Requested
Range
Not
Satisfiable
.
Il Blobstore non supporta più intervalli di byte in una singola richiesta (ad esempio, 100-199,200-299
), indipendentemente dal fatto che si sovrappongano o meno.
La classe webapp.blobstore_handlers.BlobstoreDownloadHandler
include funzionalità per impostare questa intestazione utilizzando gli indici di byte forniti e per ricavare automaticamente l'intervallo di byte da un'intestazione range
fornita dall'utente.
Completa applicazione di esempio
Nella seguente applicazione di esempio, l'URL principale dell'applicazione carica il modulo che richiede all'utente il caricamento di un file e il gestore del caricamento chiama immediatamente il gestore dei download per pubblicare i dati. per semplificare l'applicazione di esempio. In pratica, probabilmente non useresti l'URL principale per richiedere i dati di caricamento, né pubblicheresti immediatamente un BLOB che hai appena caricato.
Utilizzo del servizio Google Immagini con Blobstore
Il servizio Google Immagini può utilizzare un valore Blobstore come origine di una trasformazione. L'immagine di origine può essere grande quanto la dimensione massima di un valore Blobstore. Il servizio Google Immagini restituisce comunque l'immagine trasformata all'applicazione, pertanto le dimensioni dell'immagine trasformata devono essere inferiori a 32 MB. Questo è utile per creare miniature di fotografie di grandi dimensioni caricate dagli utenti.
Per informazioni sull'utilizzo del servizio Google Immagini con i valori dell'archivio BLOB, consulta la documentazione del servizio immagini.
Utilizzo dell'API Blobstore con Google Cloud Storage
Puoi utilizzare l'API Blobstore per archiviare i BLOB in Cloud Storage anziché in Blobstore. Devi configurare un bucket come descritto nella documentazione di Google Cloud Storage e specificare il bucket e il nome file nel parametro gs_bucket_name
blobstore.blobstore.create_upload_url. Nel gestore del caricamento, devi elaborare i metadati FileInfo restituiti e archiviare in modo esplicito il nome file di Google Cloud Storage necessario per recuperare il BLOB in un secondo momento.
Puoi anche gestire gli oggetti di Cloud Storage utilizzando l'API Blobstore. I seguenti snippet di codice mostrano come eseguire questa operazione:
Utilizzo di BlobReader
Un'applicazione può leggere i dati dai valori dell'archivio BLOB utilizzando un'interfaccia simile a un oggetto file
Python. Questa interfaccia può iniziare a leggere un valore in qualsiasi posizione di byte e utilizza più chiamate di servizio e buffering, in modo che un'applicazione possa accedere alla dimensione massima del valore nonostante le dimensioni limitate di una singola risposta alla chiamata di servizio.
La classe BlobReader
può assumere uno di tre valori come argomento per il suo costruttore:
L'oggetto implementa i metodi con file familiari per la lettura del valore. L'applicazione non può modificare il valore dell'archivio BLOB; i metodi di scrittura di file non sono implementati.
Effettuare richieste asincrone
Un'applicazione può chiamare alcune funzioni dell'archivio BLOB che funzionano in background. L'archivio BLOB esegue la richiesta, mentre l'applicazione svolge altre attività. Per eseguire la richiesta, l'applicazione chiama una funzione asincrona. La funzione restituisce immediatamente un oggetto RPC, che rappresenta la richiesta. Quando l'applicazione necessita del risultato della richiesta, chiama il metodo get_result()
dell'oggetto RPC.
Se il servizio non ha completato la richiesta quando l'applicazione chiama get_result()
, il metodo attende fino al completamento della richiesta (o ha raggiunto la scadenza o si verifica un errore). Il metodo restituisce l'oggetto risultato o genera un'eccezione se si è verificato un errore durante l'esecuzione della richiesta. Ad esempio, questo snippet di codice
upload_url = blobstore.create_upload_url('/upload')
slow_operation()
self.response.out.write("""<form action="%s" method="POST"
enctype="multipart/form-data">""" % upload_url)
diventa
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 questo esempio, l'applicazione esegue il codice slow_operation()
nello stesso momento in cui Blobstore genera l'URL di caricamento.
Quote e limiti
Lo spazio utilizzato per i valori dell'archivio BLOB contribuisce alla quota di dati archiviati (fatturabili). Le entità di informazioni BLOB nel datastore vengono conteggiate ai fini dei limiti relativi al datastore. Google Cloud Storage è un servizio a pagamento, che ti verrà addebitato in base al listino prezzi di Cloud Storage.
Per maggiori informazioni sulle quote di sicurezza a livello di sistema, consulta Quote.
Oltre alle quote di sicurezza a livello di sistema, all'utilizzo di Blobstore si applicano in modo specifico i seguenti limiti:
- La dimensione massima dei dati dell'archivio BLOB che possono essere letti dall'applicazione con una chiamata API è di 32 megabyte.
- Il numero massimo di file che possono essere caricati in un POST in un unico formato è 500.