Esempio di App Engine e Google Cloud Storage

ID regione

REGION_ID è un codice abbreviato assegnato da Google in base alla regione selezionata al momento della creazione dell'app. Il codice non corrisponde a un paese o a una provincia, anche se alcuni ID regione possono apparire simili ai codici paese e provincia di uso comune. Per le app create dopo febbraio 2020, REGION_ID.r è incluso negli URL di App Engine. Per le app esistenti create prima di questa data, l'ID regione è facoltativo nell'URL. Scopri di più sugli ID regione.

OK

---

Scopri come abilitare l'accesso Cloud Storage alla tua app Python di App Engine e creare, scrivere, leggere ed elencare file nel bucket Cloud Storage.

Il tutorial presuppone che tu conosca già Python e abbia configurato l'ambiente di sviluppo.

Quando viene eseguito, questo esempio esegue uno script e scrive l'output nel browser. Lo script illustra le seguenti funzionalità della libreria client di Cloud Storage:

• Creare un file e scrivere il file in un bucket.
• Lettura del file e recupero dei relativi metadati.
• Creare diversi file e quindi elencarli nel bucket.
• Elenco dei file appena aggiunti al bucket.
• Lettura dello stesso insieme di file.
• L'eliminazione dell'insieme di file in questione.

Obiettivi

• Esplora il progetto Python per visualizzare il layout e i file richiesti.
• Comprendere il codice per la connessione a Cloud Storage.
• Scopri il codice per creare, scrivere, leggere, elencare ed eliminare file.
• Comprendi il codice per i nuovi tentativi.
• Crea e testa l'app nel tuo server di sviluppo locale.
• Eseguire il deployment dell'app in produzione su Google App Engine.

Costi

App Engine ha un livello di utilizzo gratuito. Se l'utilizzo totale di App Engine è inferiore ai limiti specificati nella quota gratuita di App Engine, non è previsto alcun costo per questo tutorial.

Prima di iniziare

Prima di poter eseguire questo esempio, sono necessari un ID progetto, lo strumento a riga di comando gcloud e un bucket Cloud Storage:

1. Crea un nuovo progetto nella console Google Cloud o recupera l'ID di un progetto esistente dalla console Google Cloud:

   Vai alla pagina Progetti

   Suggerimento: recupera un elenco degli ID progetto esistenti con lo strumento a riga di comando gcloud.

2. Installa e inizializza Google Cloud CLI:

   Scarica l'SDK

3. Attiva il bucket Cloud Storage predefinito.

Elenco degli ID progetto della console Google Cloud con gcloud

Dalla riga di comando, esegui:

gcloud projects list

OK

Clonazione del progetto del tutorial

Per clonare il progetto:

1. Clona la libreria client e l'app di esempio (demo) sulla tua macchina locale.

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples
   

   In alternativa, puoi scaricare l'esempio come file ZIP ed estrarlo.

2. Passa alla directory appropriata nel progetto clonato o scaricato:

   cd python-docs-samples/appengine/standard/storage/appengine-client
   

Installazione delle dipendenze

Lo strumento virtualenv ti consente di creare un ambiente Python pulito sul tuo sistema. Per lo sviluppo in App Engine, questo aiuta a garantire che il codice testato in locale sia simile all'ambiente in cui verrà eseguito il deployment del codice. Per scoprire di più, consulta la sezione Utilizzo di librerie di terze parti.

Per installare virtualenv e le dipendenze dell'esempio:

Mac OS / Linux

1. Se non hai virtualenv, installalo a livello di sistema utilizzando pip.

   sudo pip install virtualenv

2. Crea un ambiente Python isolato:

   virtualenv env
   source env/bin/activate

3. Se non ti trovi nella directory che contiene il codice di esempio, vai alla directory che contiene il codice campione hello_world. Quindi installa le dipendenze:

   cd YOUR_SAMPLE_CODE_DIR
   pip install -t lib -r requirements.txt

Windows

Se hai installato Google Cloud CLI, dovresti già avere installato Python 2.7, in genere in C:\python27_x64\ (per sistemi a 64 bit). Utilizza PowerShell per eseguire i pacchetti Python.

1. Individua l'installazione di PowerShell.
2. Fai clic con il pulsante destro del mouse sulla scorciatoia a PowerShell e avviala come amministratore.
3. Prova a eseguire il comando python. Se non la trovi, aggiungi la cartella Python al PATH dell'ambiente.

   $env:Path += ";C:\python27_x64\"

4. Se non hai virtualenv, installalo a livello di sistema utilizzando pip:

   python -m pip install virtualenv

5. Crea un ambiente Python isolato.

   python -m virtualenv env
   . env\Scripts\activate

6. Naviga alla directory del progetto e installa le dipendenze. Se non ti trovi nella directory che contiene il codice campione, vai a quella contenente il codice campione hello_world. Quindi, installa le dipendenze:

   cd YOUR_SAMPLE_CODE_DIR
   python -m pip install -t lib -r requirements.txt

Il codice campione che hai clonato o scaricato contiene già un file appengine_config.py, necessario per indicare ad App Engine di utilizzare la cartella lib per caricare le dipendenze sia in locale sia al momento del deployment.

Esecuzione in locale

Importante:

• Prima di eseguire il server di sviluppo locale, segui le istruzioni di configurazione. Indipendentemente dalla versione del linguaggio o del runtime dell'app, devi eseguire dev_appserver.py con Python 3 e impostare la variabile di ambiente CLOUDSDK_DEVAPPSERVER_PYTHON nella shell sul percorso dell'interprete Python 2.
• Lo strumento dev_appserver non supporta lo sviluppo di app Python 3 su Windows.

Per eseguire l'esempio localmente:

1. Nella sottodirectory del progetto python-docs-samples/appengine/standard/storage/appengine-client, esegui l'app nel server di sviluppo locale:

   python3 CLOUD_SDK_ROOT/bin/dev_appserver.py .
   

2. Attendi che venga visualizzato il messaggio di operazione riuscita, che ha un aspetto simile al seguente:

   INFO     2016-04-12 21:33:35,446 api_server.py:205] Starting API server at: http://localhost:36884
   INFO     2016-04-12 21:33:35,449 dispatcher.py:197] Starting module "default" running at: http://localhost:8080
   INFO     2016-04-12 21:33:35,449 admin_server.py:116] Starting admin server at: http://localhost:8000
   

3. Visita questo URL nel browser:

   http://localhost:8080/

   L'applicazione verrà eseguita al caricamento della pagina, mostrando l'output al browser per indicare l'esecuzione dell'operazione. L'output sarà simile al seguente:

   

4. Interrompi il server di sviluppo premendo Ctrl-C.

Procedura dettagliata per app.yaml

Il file app.yaml specifica i dettagli di configurazione dell'applicazione:

appengine/standard/storage/appengine-client/app.yaml

Visualizza su GitHub

runtime: python27
api_version: 1
threadsafe: yes

env_variables:

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

- url: /.*
  script: main.app

Per ulteriori informazioni sulle opzioni di configurazione disponibili in questo file, consulta il riferimento app.yaml.

Procedura dettagliata per le importazioni

Il file main.py contiene le importazioni tipiche utilizzate per accedere a Cloud Storage tramite la libreria client:

appengine/standard/storage/appengine-client/main.py

Visualizza su GitHub

import os

import cloudstorage
from google.appengine.api import app_identity

import webapp2

Sono necessari il modulo os e l'API app_identity per ottenere il nome del bucket predefinito in fase di runtime. Avrai bisogno di questo nome bucket per tutte le operazioni di accesso a Cloud Storage.

L'esempio utilizza anche il framework web webapp2.

Specifica del bucket Cloud Storage

Prima di eseguire operazioni in Cloud Storage, devi fornire il nome del bucket. Il modo più semplice per eseguire questa operazione è utilizzare il bucket predefinito per il progetto, che puoi ottenere nel seguente modo:

appengine/standard/storage/appengine-client/main.py

Visualizza su GitHub

def get(self):
    bucket_name = os.environ.get(
        'BUCKET_NAME', app_identity.get_default_gcs_bucket_name())

    self.response.headers['Content-Type'] = 'text/plain'
    self.response.write(
        'Demo GCS Application running from Version: {}\n'.format(
            os.environ['CURRENT_VERSION_ID']))
    self.response.write('Using bucket name: {}\n\n'.format(bucket_name))

Scrittura di un file in Cloud Storage

Il seguente esempio mostra come scrivere nel bucket:

appengine/standard/storage/appengine-client/main.py

Visualizza su GitHub

def create_file(self, filename):
    """Create a file."""

    self.response.write('Creating file {}\n'.format(filename))

    # The retry_params specified in the open call will override the default
    # retry params for this particular file handle.
    write_retry_params = cloudstorage.RetryParams(backoff_factor=1.1)
    with cloudstorage.open(
        filename, 'w', content_type='text/plain', options={
            'x-goog-meta-foo': 'foo', 'x-goog-meta-bar': 'bar'},
            retry_params=write_retry_params) as cloudstorage_file:
                cloudstorage_file.write('abcde\n')
                cloudstorage_file.write('f'*1024*4 + '\n')
    self.tmp_filenames_to_clean_up.append(filename)

Tieni presente che nella chiamata a open il file per la scrittura, l'esempio specifica alcune intestazioni Cloud Storage che scrivono metadati personalizzati per il file. Questi metadati possono essere recuperati utilizzando cloudstorage.stat. Puoi trovare l'elenco delle intestazioni supportate nel riferimento cloudstorage.open.

Nota inoltre che l'intestazione x-goog-acl non è impostata. Ciò significa che all'oggetto verrà applicato l'ACL Cloud Storage predefinito di lettura pubblica quando viene scritto nel bucket.

Infine, nota la chiamata a close il file al termine della scrittura. Se non lo fai, il file non viene scritto in Cloud Storage. Tieni presente che dopo aver chiamato close, non puoi aggiungere elementi al file. Se devi modificare un file, dovrai aprirlo di nuovo in modalità di scrittura, il che comporta una sovrascrittura, non un'aggiunta.

Importante: nota che il file close() viene chiamato SOLO dopo che il file è stato scritto correttamente. Non ignorare le eccezioni generate durante le scritture. Non includere finally:close() nel codice perché ciò può comportare la finalizzazione dei caricamenti degli oggetti anche se si è verificata un'eccezione durante una scrittura.

Lettura di un file da Cloud Storage

Il seguente esempio mostra come leggere un file dal bucket:

appengine/standard/storage/appengine-client/main.py

Visualizza su GitHub

def read_file(self, filename):
    self.response.write(
        'Abbreviated file content (first line and last 1K):\n')

    with cloudstorage.open(filename) as cloudstorage_file:
        self.response.write(cloudstorage_file.readline())
        cloudstorage_file.seek(-1024, os.SEEK_END)
        self.response.write(cloudstorage_file.read())

L'esempio mostra come visualizzare le righe selezionate del file letto, in questo caso la riga di apertura e le ultime 1000 righe, utilizzando seek.

Tieni presente che non è specificata alcuna modalità nel codice precedente quando il file viene aperto per la lettura. L'impostazione predefinita per open è la modalità di sola lettura.

Elenco dei contenuti del bucket

Il codice campione mostra come sfogliare un bucket con un numero elevato di file, utilizzando i parametri marker e max_keys per sfogliare un elenco dei contenuti del bucket:

appengine/standard/storage/appengine-client/main.py

Visualizza su GitHub

def list_bucket(self, bucket):
    """Create several files and paginate through them."""

    self.response.write('Listbucket result:\n')

    # Production apps should set page_size to a practical value.
    page_size = 1
    stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size)
    while True:
        count = 0
        for stat in stats:
            count += 1
            self.response.write(repr(stat))
            self.response.write('\n')

        if count != page_size or count == 0:
            break
        stats = cloudstorage.listbucket(
            bucket + '/foo', max_keys=page_size, marker=stat.filename)

Tieni presente che il nome file completo viene visualizzato come un'unica stringa senza delimitatori di directory. Se vuoi visualizzare il file con la sua gerarchia di directory più riconoscibile, imposta il parametro delimiter sul delimitatore di directory che vuoi utilizzare.

Eliminazione di file in corso...

L'esempio di codice mostra le eliminazioni di file, in questo caso l'eliminazione di tutti i file aggiunti durante l'esecuzione dell'applicazione. Non lo faresti nel codice, poiché questa è solo una funzionalità di pulizia di questo esempio:

appengine/standard/storage/appengine-client/main.py

Visualizza su GitHub

def delete_files(self):
    self.response.write('Deleting files...\n')
    for filename in self.tmp_filenames_to_clean_up:
        self.response.write('Deleting file {}\n'.format(filename))
        try:
            cloudstorage.delete(filename)
        except cloudstorage.NotFoundError:
            pass

Deployment dell'esempio

Per eseguire il deployment ed eseguire l'esempio su App Engine:

1. Carica l'app di esempio eseguendo questo comando dall'interno della directory python-docs-samples/appengine/standard/storage/appengine-client in cui si trova il file app.yaml:

   gcloud app deploy
   

   Flag facoltativi:

   • Includi il flag --project per specificare un ID progetto della console Google Cloud alternativo a quello che hai inizializzato come predefinito in gcloud CLI. Esempio: --project [YOUR_PROJECT_ID]
   • Includi il flag -v per specificare un ID versione, altrimenti ne verrà generato automaticamente uno. Esempio: -v [YOUR_VERSION_ID]
   Suggerimento: se specifichi l'ID versione di un'applicazione che è stata caricata in precedenza, il tuo deployment sovrascriverà la versione esistente su App Engine. Questo non è sempre auspicabile, soprattutto se la versione su App Engine gestisce il traffico. Per evitare di interrompere il traffico verso l'applicazione, puoi eseguire il deployment dell'applicazione con un ID versione diverso e quindi trasferire il traffico a quella versione. Per saperne di più sullo spostamento del traffico, consulta la suddivisione del traffico.

2. Al termine del processo di deployment, puoi visualizzare l'applicazione all'indirizzo https://PROJECT_ID.REGION_ID.r.appspot.com eseguendo questo comando:

   gcloud app browse
   

   L'app demo viene eseguita al caricamento pagina, proprio come quando l'hai eseguita in locale. Tuttavia, ora l'app scriverà e leggerà dal bucket Cloud Storage.

Per scoprire di più sul deployment della tua app dalla riga di comando, consulta la pagina relativa al deployment di un'app Python 2.

Passaggi successivi

• Scopri alcuni concetti fondamentali di Cloud Storage.
• Leggi il riferimento della funzione della libreria client di Cloud Storage.
• Leggi il riferimento RiprovaParams Class.
• Leggi il riferimento Gestione degli errori.
• Esplora le architetture di riferimento, i diagrammi e le best practice su Google Cloud. Dai un'occhiata al nostro Cloud Architecture Center.