Esegui la migrazione di Blobstore di App Engine a Cloud Storage

Questa guida illustra come eseguire la migrazione da Blobstore di App Engine a Cloud Storage.

Cloud Storage è simile a Blobstore di App Engine in quanto puoi utilizzarlo per pubblicare oggetti di dati di grandi dimensioni (BLOB), come file video o immagine, e consentire agli utenti di caricare file di dati di grandi dimensioni. Anche se App Engine Blobstore è accessibile solo tramite i servizi legacy in bundle di App Engine, Cloud Storage è un prodotto Google Cloud indipendente a cui si accede tramite le librerie client Cloud. Cloud Storage offre alla tua app una soluzione di archiviazione oggetti più moderna e ti consente di eseguire in un secondo momento la migrazione a Cloud Run o a un'altra piattaforma di hosting di app Google Cloud.

Per i progetti Google Cloud creati dopo novembre 2016, Blobstore utilizza i bucket Cloud Storage dietro le quinte. Ciò significa che quando esegui la migrazione della tua app a Cloud Storage, tutte le autorizzazioni e gli oggetti esistenti nei bucket Cloud Storage esistenti rimangono invariati. Puoi anche iniziare ad accedere ai bucket esistenti utilizzando le librerie client Cloud per Cloud Storage.

Differenze e somiglianze principali

Cloud Storage esclude le seguenti dipendenze e limitazioni di Blobstore:

  • L'API Blobstore per Python 2 ha una dipendenza da webapp.
  • L'API Blobstore per Python 3 utilizza classi di utilità per utilizzare gli handler Blobstore.
  • Per Blobstore, il numero massimo di file che possono essere caricati è 500. Non esiste alcun limite al numero di oggetti che puoi creare in un bucket Cloud Storage.

Cloud Storage non supporta:

  • Classi di gestori Blobstore
  • Oggetti Blobstore

Somiglianze tra Cloud Storage e Blobstore di App Engine:

  • In grado di leggere e scrivere oggetti di dati di grandi dimensioni in un ambiente di runtime, nonché di archiviare e pubblicare oggetti di dati di grandi dimensioni statici, come filmati, immagini o altri contenuti statici. Il limite di dimensione degli oggetti per Cloud Storage è 5 TiB.
  • Ti consente di archiviare oggetti in un bucket Cloud Storage.
  • Offrono un livello gratuito.

Prima di iniziare

  • Devi esaminare e comprendere i prezzi e le quote di Cloud Storage:
  • Avere un'app App Engine Python 2 o Python 3 esistente che utilizza Blobstore.
  • Gli esempi in questa guida mostrano un'app di cui viene eseguita la migrazione a Cloud Storage utilizzando il framework Flask. Tieni presente che puoi utilizzare qualsiasi framework web, anche se mantieni webapp2, durante la migrazione a Cloud Storage.

Panoramica

In linea generale, la procedura di migrazione a Cloud Storage da App Engine Blobstore è costituita dai seguenti passaggi:

  1. Aggiornare i file di configurazione
  2. Aggiorna l'app Python:
    • Aggiorna il framework web
    • Importa e inizializza Cloud Storage
    • Aggiorna i gestori di Blobstore
    • (Facoltativo) Aggiorna il modello dei dati se utilizzi Cloud NDB o App Engine NDB
  3. Testare e implementare l'app

Aggiornare i file di configurazione

Prima di modificare il codice dell'applicazione per passare da Blobstore a Cloud Storage, aggiorna i file di configurazione per utilizzare la libreria Cloud Storage.

  1. Aggiorna il file app.yaml. Segui le istruzioni per la tua versione di Python:

    Python 2

    Per le app Python 2:

    1. Rimuovi la sezione handlers ed eventuali dipendenze webapp non necessarie nella sezione libraries.
    2. Se utilizzi le librerie client di Cloud, aggiungi le versioni più recenti delle librerie grpcio e setuptools.
    3. Aggiungi la libreria ssl, poiché è richiesta da Cloud Storage.

    Di seguito è riportato un esempio di file app.yaml con le modifiche apportate:

    runtime: python27
threadsafe: yes
api_version: 1

handlers:
- url: /.*
  script: main.app

libraries:
- name: grpcio
  version: latest
- name: setuptools
  version: latest
- name: ssl
  version: latest

    Python 3

    Per le app Python 3, elimina tutte le righe tranne l'elemento runtime. Ad esempio:

    runtime: python310 # or another support version

    Il runtime Python 3 installa le librerie automaticamente, quindi non è necessario specificare le librerie integrate del runtime Python 2 precedente. Se la tua app Python 3 utilizza altri servizi legacy in bundle durante la migrazione a Cloud Storage, lascia invariato il file app.yaml.

  2. Aggiorna il file requirements.txt. Segui le istruzioni relative alla tua versione di Python:

    Python 2

    Aggiungi le librerie client Cloud per Cloud Storage all'elenco delle dipendenze nel file requirements.txt.

    google-cloud-storage

    Quindi, esegui pip install -t lib -r requirements.txt per aggiornare l'elenco delle librerie disponibili per la tua app.

    Python 3

    Aggiungi le librerie client Cloud per Cloud Storage all'elenco delle dipendenze nel file requirements.txt.

    google-cloud-storage

    App Engine installa automaticamente queste dipendenze durante il deployment dell'app nel runtime di Python 3, quindi elimina la cartella lib, se esistente.

  3. Per le app Python 2, se la tua app utilizza librerie integrate o copiate, devi specificare questi percorsi nel file appengine_config.py:

    import pkg_resources
from google.appengine.ext import vendor

# Set PATH to your libraries folder.
PATH = 'lib'
# Add libraries installed in the PATH folder.
vendor.add(PATH)
# Add libraries to pkg_resources working set to find the distribution.
pkg_resources.working_set.add_entry(PATH)

Aggiornare l'app Python

Dopo aver modificato i file di configurazione, aggiorna l'app Python.

Aggiornare il framework web Python 2

Per le app Python 2 che utilizzano il framework webapp2, è consigliabile eseguire la migrazione dal framework webapp2 obsoleto. Consulta il programma di supporto del runtime per la data di fine del supporto di Python 2.

Puoi eseguire la migrazione a un altro framework web come Flask, Django o WSGI. Poiché Cloud Storage esclude le dipendenze da webapp2 e i gestori Blobstore non sono supportati, puoi eliminare o sostituire altre librerie relative alle web app.

Se scegli di continuare a utilizzare webapp2, tieni presente che gli esempi riportati in questa guida utilizzano Cloud Storage con Flask.

Se prevedi di utilizzare i servizi Google Cloud oltre a Cloud Storage o di accedere alle versioni più recenti del runtime, ti consigliamo di eseguire l'upgrade dell'app al runtime Python 3. Per ulteriori informazioni, consulta la panoramica della migrazione da Python 2 a Python 3.

Importa e inizializza Cloud Storage

Modifica i file dell'applicazione aggiornando le righe di importazione e inizializzazione:

  1. Rimuovi le istruzioni di importazione di Blobstore, ad esempio la seguente:

    import webapp2
from google.appengine.ext import blobstore
from google.appengine.ext.webapp import blobstore_handlers

  2. Aggiungi le istruzioni di importazione per Cloud Storage e le librerie di autenticazione di Google, ad esempio:

    import io
from flask import (Flask, abort, redirect, render_template,
request, send_file, url_for)
from google.cloud import storage
import google.auth

    La libreria di autenticazione Google è necessaria per ottenere lo stesso ID progetto utilizzato in Blobstore per Cloud Storage. Importa altre librerie come Cloud NBD, se applicabili alla tua app.

  3. Crea un nuovo client per Cloud Storage e specifica il bucket utilizzato in Blobstore. Ad esempio:

    gcs_client = storage.Client()
_, PROJECT_ID = google.auth.default()
BUCKET = '%s.appspot.com' % PROJECT_ID

    Per i progetti Google Cloud dopo novembre 2016, Blobstore scrive in un bucket Cloud Storage denominato in base all'URL dell'app e segue il formato PROJECT_ID.appspot.com. Utilizzi l'autenticazione Google per ottenere l'ID progetto per specificare il bucket Cloud Storage utilizzato per memorizzare i blob in Blobstore.

Aggiorna i gestori di Blobstore

Poiché Cloud Storage non supporta gli elaboratori di caricamento e download di Blobstore, devi utilizzare una combinazione di funzionalità di Cloud Storage, del modulo della libreria standard io, del tuo framework web e delle utilità Python per caricare e scaricare oggetti (blob) in Cloud Storage.

Di seguito viene mostrato come aggiornare i gestori di Blobstore utilizzando Flask come framework web di esempio:

  1. Sostituisci le classi di gestore dei caricamenti di Blobstore con una funzione di caricamento in Flask. Segui le istruzioni per la tua versione di Python:

    Python 2

    Gli handler di Blobstore in Python 2 sono classi webapp2, come mostrato nel seguente esempio di Blobstore:

    class UploadHandler(blobstore_handlers.BlobstoreUploadHandler):
    'Upload blob (POST) handler'
    def post(self):
        uploads = self.get_uploads()
        blob_id = uploads[0].key() if uploads else None
        store_visit(self.request.remote_addr, self.request.user_agent, blob_id)
        self.redirect('/', code=307)
...
app = webapp2.WSGIApplication([
    ('/', MainHandler),
    ('/upload', UploadHandler),
    ('/view/([^/]+)?', ViewBlobHandler),
], debug=True)

    Per utilizzare Cloud Storage:

    1. Sostituisci la classe di caricamento dell'app web con una funzione di caricamento Flask.
    2. Sostituisci il gestore del caricamento e il routing con un metodo POST di Flask ornamentato con il routing.

    Esempio di codice aggiornato:

    @app.route('/upload', methods=['POST'])
def upload():
    'Upload blob (POST) handler'
    fname = None
    upload = request.files.get('file', None)
    if upload:
        fname = secure_filename(upload.filename)
        blob = gcs_client.bucket(BUCKET).blob(fname)
        blob.upload_from_file(upload, content_type=upload.content_type)
    store_visit(request.remote_addr, request.user_agent, fname)
    return redirect(url_for('root'), code=307)

    Nel esempio di codice di Cloud Storage aggiornato, ora l'app identifica gli elementi dell'oggetto in base al nome dell'oggetto (fname) anziché blob_id. Il routing avviene anche nella parte inferiore del file dell'applicazione.

    Per ottenere l'oggetto caricato, il metodo get_uploads() di Blobstore viene sostituita con il metodo request.files.get() di Flask. In Flask, puoi utilizzare il metodo secure_filename() per ottenere un nome senza caratteri di percorso per il file e identificare l'oggetto utilizzando gcs_client.bucket(BUCKET).blob(fname) per specificare il nome del bucket e dell'oggetto./

    La chiamata Cloud Storage upload_from_file() esegue il caricamento come mostrato nell'esempio aggiornato.

    Python 3

    La classe di gestore del caricamento in Blobstore per Python 3 è una classe di utilità e richiede l'utilizzo del dizionario environ WSGI come parametro di input, come mostrato nel seguente esempio di Blobstore:

    class UploadHandler(blobstore.BlobstoreUploadHandler):
    'Upload blob (POST) handler'
    def post(self):
        uploads = self.get_uploads(request.environ)
        if uploads:
            blob_id = uploads[0].key()
            store_visit(request.remote_addr, request.user_agent, blob_id)
        return redirect('/', code=307)
...
@app.route('/upload', methods=['POST'])
def upload():
    """Upload handler called by blobstore when a blob is uploaded in the test."""
    return UploadHandler().post()

    Per utilizzare Cloud Storage, sostituisci il metodo get_uploads(request.environ) di Blobstore con il metodo request.files.get() di Flask.

    Esempio di codice aggiornato:

    @app.route('/upload', methods=['POST'])
def upload():
    'Upload blob (POST) handler'
    fname = None
    upload = request.files.get('file', None)
    if upload:
        fname = secure_filename(upload.filename)
        blob = gcs_client.bucket(BUCKET).blob(fname)
        blob.upload_from_file(upload, content_type=upload.content_type)
    store_visit(request.remote_addr, request.user_agent, fname)
    return redirect(url_for('root'), code=307)

    Nel esempio di codice di Cloud Storage aggiornato, ora l'app identifica gli elementi dell'oggetto in base al nome dell'oggetto (fname) anziché blob_id. Il routing avviene anche nella parte inferiore del file dell'applicazione.

    Per ottenere l'oggetto caricato, il metodo get_uploads() di Blobstore viene sostituita con il metodo request.files.get() di Flask. In Flask, puoi utilizzare il metodo secure_filename() per ottenere un nome senza caratteri di percorso per il file e identificare l'oggetto utilizzando gcs_client.bucket(BUCKET).blob(fname) per specificare il nome del bucket e dell'oggetto./

    Il metodo Cloud Storage upload_from_file() esegue il caricamento come mostrato nell'esempio aggiornato.

  2. Sostituisci le classi di gestore dei download di Blobstore con una funzione di download in Flask. Segui le istruzioni per la tua versione di Python:

    Python 2

    Il seguente esempio di gestore dei download mostra l'utilizzo della classe BlobstoreDownloadHandler, che utilizza webapp2:

    class ViewBlobHandler(blobstore_handlers.BlobstoreDownloadHandler):
    'view uploaded blob (GET) handler'
    def get(self, blob_key):
        self.send_blob(blob_key) if blobstore.get(blob_key) else self.error(404)
...
app = webapp2.WSGIApplication([
    ('/', MainHandler),
    ('/upload', UploadHandler),
    ('/view/([^/]+)?', ViewBlobHandler),
], debug=True)

    Per utilizzare Cloud Storage:

    1. Aggiorna il metodo send_blob() di Blobstore per utilizzare il metodo download_as_bytes() di Cloud Storage.
    2. Modifica il routing da webapp2 a Flask.

    Esempio di codice aggiornato:

    @app.route('/view/<path:fname>')
def view(fname):
    'view uploaded blob (GET) handler'
    blob = gcs_client.bucket(BUCKET).blob(fname)
    try:
        media = blob.download_as_bytes()
    except exceptions.NotFound:
        abort(404)
    return send_file(io.BytesIO(media), mimetype=blob.content_type)

    Nell'esempio di codice di Cloud Storage aggiornato, Flask decora la route nella funzione Flask e identifica l'oggetto utilizzando '/view/<path:fname>'. Cloud Storage identifica l'oggetto blob in base al nome dell'oggetto e al nome del bucket e utilizza il metodo download_as_bytes() per scaricare l'oggetto sotto forma di byte, anziché utilizzare il metodo send_blob di Blobstore. Se l'elemento non viene trovato, l'app restituisce un errore HTTP 404.

    Python 3

    Come il gestore di caricamento, la classe di gestore dei download in Blobstore per Python 3 è una classe di utilità e richiede l'utilizzo del dizionario environ WSGI come parametro di input, come mostrato nell'esempio di Blobstore seguente:

    class ViewBlobHandler(blobstore.BlobstoreDownloadHandler):
    'view uploaded blob (GET) handler'
    def get(self, blob_key):
        if not blobstore.get(blob_key):
            return "Photo key not found", 404
        else:
            headers = self.send_blob(request.environ, blob_key)

        # Prevent Flask from setting a default content-type.
        # GAE sets it to a guessed type if the header is not set.
        headers['Content-Type'] = None
        return '', headers
...
@app.route('/view/<blob_key>')
def view_photo(blob_key):
    """View photo given a key."""
    return ViewBlobHandler().get(blob_key)

    Per utilizzare Cloud Storage, sostituisci send_blob(request.environ, blob_key) di Blobstore con il metodo blob.download_as_bytes() di Cloud Storage.

    Esempio di codice aggiornato:

    @app.route('/view/<path:fname>')
def view(fname):
    'view uploaded blob (GET) handler'
    blob = gcs_client.bucket(BUCKET).blob(fname)
    try:
        media = blob.download_as_bytes()
    except exceptions.NotFound:
        abort(404)
    return send_file(io.BytesIO(media), mimetype=blob.content_type)

    Nel esempio di codice di Cloud Storage aggiornato, blob_key viene sostituito con fname e Flask identifica l'oggetto utilizzando l'URL '/view/<path:fname>'. Il metodo gcs_client.bucket(BUCKET).blob(fname) viene utilizzato per individuare il nome del file e il nome del bucket. Il metodo download_as_bytes() di Cloud Storage scarica l'oggetto come byte anziché utilizzare il metodo send_blob() di Blobstore.

  3. Se la tua app utilizza un gestore principale, sostituisci la classe MainHandler con la funzione root() in Flask. Segui le istruzioni per la tua versione di Python:

    Python 2

    Di seguito è riportato un esempio di utilizzo della classe MainHandler di Blobstore:

    class MainHandler(BaseHandler):
    'main application (GET/POST) handler'
    def get(self):
        self.render_response('index.html',
                upload_url=blobstore.create_upload_url('/upload'))

    def post(self):
        visits = fetch_visits(10)
        self.render_response('index.html', visits=visits)

app = webapp2.WSGIApplication([
    ('/', MainHandler),
    ('/upload', UploadHandler),
    ('/view/([^/]+)?', ViewBlobHandler),
], debug=True)

    Per utilizzare Cloud Storage:

    1. Rimuovi la classe MainHandler(BaseHandler), poiché Flask gestisce il routing per te.
    2. Semplifica il codice Blobstore con Flask.
    3. Rimuovi il routing della web app alla fine.

    Esempio di codice aggiornato:

    @app.route('/', methods=['GET', 'POST'])
def root():
    'main application (GET/POST) handler'
    context = {}
    if request.method == 'GET':
        context['upload_url'] = url_for('upload')
    else:
        context['visits'] = fetch_visits(10)
    return render_template('index.html', **context)

    Python 3

    Se hai utilizzato Flask, non avrai una classe MainHandler, ma la funzione Flask root deve essere aggiornata se viene utilizzato Blobstore. L'esempio seguente utilizza la funzione blobstore.create_upload_url('/upload'):

    @app.route('/', methods=['GET', 'POST'])
def root():
    'main application (GET/POST) handler'
    context = {}
    if request.method == 'GET':
        context['upload_url'] = blobstore.create_upload_url('/upload')
    else:
        context['visits'] = fetch_visits(10)
    return render_template('index.html', **context)

    Per utilizzare Cloud Storage, sostituisci la funzione blobstore.create_upload_url('/upload') con il metodo url_for() di Flask per ottenere l'URL della funzione upload().

    Esempio di codice aggiornato:

    @app.route('/', methods=['GET', 'POST'])
def root():
    'main application (GET/POST) handler'
    context = {}
    if request.method == 'GET':
        context['upload_url'] = url_for('upload') # Updated to use url_for
    else:
        context['visits'] = fetch_visits(10)
    return render_template('index.html', **context)

Test e deployment dell'app

Il server di sviluppo locale ti consente di verificare il funzionamento dell'app, ma non sarà in grado di testare Cloud Storage finché non eseguirai il deployment di una nuova versione perché tutte le richieste di Cloud Storage devono essere inviate tramite internet a un bucket Cloud Storage effettivo. Consulta la sezione Test e deployment dell'applicazione per scoprire come eseguire l'applicazione localmente. Poi esegui il deployment di una nuova versione per verificare che l'app sia visualizzata come prima.

App che utilizzano App Engine NDB o Cloud NDB

Devi aggiornare il modello dei dati di Datastore se la tua app utilizza NDB di App Engine o NDB di Cloud per includere proprietà correlate a Blobstore.

Aggiorna il modello dei dati

Poiché le proprietà BlobKey di NDB non sono supportate da Cloud Storage, devi modificare le righe relative a Blobstore per utilizzare gli equivalenti integrati di NDB, dei framework web o di altre origini.

Per aggiornare il modello dei dati:

  1. Individua le righe che utilizzano BlobKey nel modello dei dati, ad esempio:

    class Visit(ndb.Model):
    'Visit entity registers visitor IP address & timestamp'
    visitor   = ndb.StringProperty()
    timestamp = ndb.DateTimeProperty(auto_now_add=True)
    file_blob = ndb.BlobKeyProperty()

  2. Sostituisci ndb.BlobKeyProperty() con ndb.StringProperty():

    class Visit(ndb.Model):
    'Visit entity registers visitor IP address & timestamp'
    visitor   = ndb.StringProperty()
    timestamp = ndb.DateTimeProperty(auto_now_add=True)
    file_blob = ndb.StringProperty() # Modified from ndb.BlobKeyProperty()

  3. Se esegui anche l'upgrade da App Engine NDB a Cloud NDB durante la migrazione, consulta la guida alla migrazione a Cloud NDB per indicazioni su come eseguire il refactoring del codice NDB in modo da utilizzare i gestori contestuali di Python.

Compatibilità con le versioni precedenti per modello dei dati di Datastore

Nella sezione precedente, la sostituzione di ndb.BlobKeyProperty con ndb.StringProperty ha reso l'app non compatibile con le versioni precedenti, il che significa che l'app non potrà elaborare le voci precedenti create da Blobstore. Se devi conservare i dati precedenti, anziché aggiornare il campo ndb.BlobKeyProperty, crea un campo aggiuntivo per le nuove voci Cloud Storage e una funzione per normalizzare i dati.

A partire dagli esempi delle sezioni precedenti, apporta le seguenti modifiche:

  1. Crea due campi proprietà distinti quando definisci il modello dei dati. Utilizza la proprietà file_blob per identificare gli oggetti creati da Blobstore e la proprietà file_gcs per identificare gli oggetti creati da Cloud Storage:

    class Visit(ndb.Model):
    'Visit entity registers visitor IP address & timestamp'
    visitor   = ndb.StringProperty()
    timestamp = ndb.DateTimeProperty(auto_now_add=True)
    file_blob = ndb.BlobKeyProperty()  # backwards-compatibility
    file_gcs  = ndb.StringProperty()

  2. Trova le righe che fanno riferimento alle nuove visite, ad esempio:

    def store_visit(remote_addr, user_agent, upload_key):
    'create new Visit entity in Datastore'
    with ds_client.context():
        Visit(visitor='{}: {}'.format(remote_addr, user_agent),
                file_blob=upload_key).put()

  3. Modifica il codice in modo che file_gcs venga utilizzato per le voci recenti. Ad esempio:

    def store_visit(remote_addr, user_agent, upload_key):
    'create new Visit entity in Datastore'
    with ds_client.context():
        Visit(visitor='{}: {}'.format(remote_addr, user_agent),
                file_gcs=upload_key).put() # change file_blob to file_gcs for new requests

  4. Crea una nuova funzione per normalizzare i dati. L'esempio seguente mostra l'utilizzo di ETL (estrazione, trasformazione e caricamento) per eseguire un ciclo per tutte le visite e acquisisce i dati del visitatore e del timestamp per verificare se esistono file_gcs o file_gcs:

    def etl_visits(visits):
    return [{
            'visitor': v.visitor,
            'timestamp': v.timestamp,
            'file_blob': v.file_gcs if hasattr(v, 'file_gcs') \
                    and v.file_gcs else v.file_blob
            } for v in visits]

  5. Trova la riga che fa riferimento alla funzione fetch_visits():

    @app.route('/', methods=['GET', 'POST'])
def root():
    'main application (GET/POST) handler'
    context = {}
    if request.method == 'GET':
        context['upload_url'] = url_for('upload')
    else:
        context['visits'] = fetch_visits(10)
    return render_template('index.html', **context)

  6. Inserisci fetch_visits() all'interno della funzione etl_visits(), ad esempio:

    @app.route('/', methods=['GET', 'POST'])
def root():
    'main application (GET/POST) handler'
    context = {}
    if request.method == 'GET':
        context['upload_url'] = url_for('upload')
    else:
        context['visits'] = etl_visits(fetch_visits(10)) # etl_visits wraps around fetch_visits
    return render_template('index.html', **context)

Esempi

Passaggi successivi