Esegui la migrazione di Blobstore di App Engine a Cloud Storage

Questa guida spiega come eseguire la migrazione dall'archivio BLOB di App Engine a Cloud Storage.

Cloud Storage è simile ad App Engine Blobstore 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. Mentre l'archivio BLOB di App Engine è accessibile solo tramite i servizi in bundle legacy di App Engine, Cloud Storage è un prodotto Google Cloud autonomo a cui si accede tramite le librerie client Cloud. Cloud Storage offre alla tua app una soluzione di archiviazione di oggetti più moderna e ti offre la flessibilità di eseguire la migrazione a Cloud Run o a un'altra piattaforma di hosting di app in un secondo momento. Google Cloud

Per i Google Cloud progetti creati dopo novembre 2016, Blobstore utilizza bucket Cloud Storage in background. Ciò significa che quando esegui la migrazione dell'app a Cloud Storage, tutti gli oggetti e le autorizzazioni esistenti in questi bucket Cloud Storage rimangono invariati. Puoi anche iniziare ad accedere a questi bucket esistenti utilizzando le librerie client di Cloud per Cloud Storage.

Principali differenze e somiglianze

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 i gestori Blobstore.
  • Per Blobstore, il numero massimo di file che possono essere caricati è 500. Non esiste un limite al numero di oggetti che puoi creare in un bucket Cloud Storage.

Cloud Storage non supporta:

  • Classi gestore Blobstore
  • Oggetti Blobstore

Somiglianze tra Cloud Storage e l'archivio BLOB di App Engine:

  • In grado di leggere e scrivere oggetti di dati di grandi dimensioni in un ambiente di runtime, nonché archiviare ed erogare oggetti di dati statici di grandi dimensioni, come film, immagini o altri contenuti statici. Il limite dimensionale per gli oggetti di Cloud Storage è di 5 TiB.
  • Consente di archiviare oggetti in un bucket Cloud Storage.
  • Offrire un Livello senza costi.

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 che esegue la migrazione a Cloud Storage utilizzando il framework Flask. Tieni presente che puoi utilizzare qualsiasi framework web, incluso 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 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 in modo che utilizzino 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 e le dipendenze webapp non necessarie nella sezione libraries.
    2. Se utilizzi le librerie client di Cloud, aggiungi le ultime versioni 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 automaticamente le librerie, quindi non devi specificare le librerie integrate del runtime Python 2 precedente. Se la tua app Python 3 utilizza altri servizi legacy inclusi durante la migrazione a Cloud Storage, lascia il file app.yaml così com'è.

  2. Aggiorna il file requirements.txt. Segui le istruzioni per la 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 nell'ambiente di runtime Python 3, quindi elimina la cartella lib, se esiste.

  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)

Aggiorna l'app Python

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

Aggiorna 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 correlate alle app web.

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 in aggiunta 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 saperne di più, 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, come le seguenti:

    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 Google, come le seguenti:

    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 applicabile 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 successivi a 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 archiviare i blob in Blobstore.

Aggiorna i gestori Blobstore

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

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

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

    Python 2

    I gestori Blobstore in Python 2 sono classi webapp2 come mostrato nell'esempio di Blobstore seguente:

    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 Webapp con una funzione di caricamento Flask.
    2. Sostituisci il gestore di caricamento e il routing con un metodo Flask POST decorato 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 Cloud Storage aggiornato, l'app ora identifica gli artefatti degli oggetti in base al nome dell'oggetto (fname) anziché blob_id. Il routing si verifica anche nella parte inferiore del file dell'applicazione.

    Per ottenere l'oggetto caricato, il metodo get_uploads() di Blobstore viene sostituito dal metodo request.files.get() di Flask. In Flask, puoi utilizzare il metodo secure_filename() per ottenere un nome senza caratteri di percorso, come /, 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 gestione del caricamento in Blobstore per Python 3 è una classe di utilità e richiede l'utilizzo del dizionario WSGI environ come parametro di input, come mostrato nell'esempio di Blobstore seguente:

    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 Cloud Storage aggiornato, l'app ora identifica gli artefatti degli oggetti in base al nome dell'oggetto (fname) anziché blob_id. Il routing si verifica anche nella parte inferiore del file dell'applicazione.

    Per ottenere l'oggetto caricato, il metodo get_uploads() di Blobstore viene sostituito dal metodo request.files.get() di Flask. In Flask, puoi utilizzare il metodo secure_filename() per ottenere un nome senza caratteri di percorso, come /, 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 del gestore di 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 di 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)

    Nel esempio di codice 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 del bucket e utilizza il metodo download_as_bytes() per scaricare l'oggetto come byte, anziché utilizzare il metodo send_blob di Blobstore. Se l'artefatto non viene trovato, l'app restituisce un errore HTTP 404.

    Python 3

    Come il gestore di caricamento, la classe del gestore di download in Blobstore per Python 3 è una classe di utilità e richiede l'utilizzo del dizionario WSGI environ 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)

    Nell'esempio di codice 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 dell'app web 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 radice Flask 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 che la tua app funzioni, ma non potrai testare Cloud Storage finché non avrai eseguito il deployment di una nuova versione, perché tutte le richieste Cloud Storage devono essere inviate su internet a un bucket Cloud Storage effettivo. Consulta 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 appaia come prima.

App che utilizzano App Engine NDB o Cloud NDB

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

Aggiornare 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, framework web o altro.

Per aggiornare il modello dei dati:

  1. Trova le righe che utilizzano BlobKey nel modello dei dati, come le seguenti:

    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 durante la migrazione esegui anche l'upgrade da App Engine NDB a Cloud NDB, consulta la guida alla migrazione di Cloud NDB per indicazioni su come eseguire il refactoring del codice NDB per utilizzare i gestori di contesto Python.

Compatibilità con le versioni precedenti per modello dei dati Datastore

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

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

  1. Crea due campi proprietà separati 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 Estrazione, trasformazione e caricamento (ETL) per scorrere tutti i visitatori e i 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