Migrazione alla libreria client Cloud per Cloud Storage

Cloud Storage consente alla tua applicazione di pubblicare oggetti di dati di grandi dimensioni, come file video o immagine, e consente agli utenti di caricare file di dati di grandi dimensioni. Nel runtime Python 2, App Engine fornisce una propria libreria client per scrivere e leggere oggetti in Cloud Storage. Questa libreria App Engine non è disponibile nei runtime App Engine più recenti, incluso il runtime Python 3.

Se la tua app Python 2 utilizza la libreria GoogleAppEngineCloudStorageClient, devi eseguire la migrazione alla libreria client di Cloud per Cloud Storage prima di poter eseguire l'app nell'ambiente di runtime Python 3. Tieni presente che devi eseguire la migrazione della tua app per utilizzare una nuova libreria client. Tutti gli oggetti dati e le autorizzazioni nei bucket Cloud Storage esistenti rimangono invariati e puoi accedere ai bucket esistenti utilizzando la nuova libreria client.

Confronto tra le librerie client App Engine e Cloud

Analogie:

La libreria client di Cloud supporta tutte le funzionalità di Cloud Storage attivate dalla libreria client App Engine, come la lettura, la scrittura, la rimozione e l'elenco degli oggetti. La migrazione dovrebbe richiedere solo piccole modifiche al codice.

La libreria client Cloud supporta anche funzionalità aggiuntive, come la creazione e l'etichettatura dei bucket e il recupero delle versioni precedenti degli oggetti.

Differenze:

Nella libreria App Engine, la funzione che recupera un elenco di oggetti funziona in modo asincrono. La libreria client Cloud non fornisce una funzione asincrona per elencare gli oggetti, anche se puoi utilizzare la paginazione e scorrere un piccolo insieme di oggetti.
La libreria client App Engine richiede l'utilizzo di elenchi di controllo dell'accesso (ACL) per controllare l'accesso a bucket e oggetti. Tuttavia, Cloud Storage e la libreria client di Cloud supportano due sistemi per concedere agli utenti l'autorizzazione ad accedere ai tuoi bucket e oggetti: ACL e accesso uniforme a livello di bucket. L'accesso uniforme a livello di bucket offre un'esperienza di controllo dell'accesso più semplice e coerente in tutte le tue risorse cloud.

Tutte le ACL che hai utilizzato con la libreria client App Engine rimangono in vigore per i bucket esistenti dopo la migrazione alla libreria client Cloud e puoi continuare a utilizzare le ACL, se necessario.

Se l'accesso uniforme a livello di bucket soddisfa le tue esigenze, ti consigliamo di utilizzare questo sistema più semplice per tutti i nuovi bucket che crei. Anche se puoi convertire i bucket esistenti per utilizzare l'accesso uniforme a livello di bucket, questa operazione potrebbe richiedere modifiche significative al modo in cui la tua app protegge l'accesso ai suoi oggetti di archiviazione.

Esempi di codice:

Operazioni di archiviazione di base utilizzando le API App Engine
Operazioni di archiviazione di base utilizzando la libreria client Cloud per Cloud Storage

Prima di iniziare la migrazione

Se non l'hai ancora fatto, configura il tuo ambiente di sviluppo Python per utilizzare una versione di Python compatibile con Google Cloude installa gli strumenti di test per creare ambienti Python isolati.

Informazioni sulle autorizzazioni Cloud Storage

Per impostazione predefinita, il service account predefinito creato automaticamente della tua app dispone dei privilegi di lettura e scrittura per i bucket del tuo progetto e ha pieni diritti sugli oggetti che crea, sia prima che dopo la migrazione.

Se hai utilizzato un account di servizio o un account utente diverso per proteggere l'accesso ai bucket e agli oggetti Cloud Storage, assicurati di continuare a utilizzare gli stessi account e le stesse tecniche di autenticazione prima e dopo la migrazione.

Panoramica del processo di migrazione

Per eseguire la migrazione della tua app Python in modo che utilizzi la libreria client di Cloud per Cloud Storage anziché la libreria client App Engine:

Installa la libreria client Cloud per Cloud Storage.
Aggiorna il codice per utilizzare la libreria client di Cloud.
Testa gli aggiornamenti.
Esegui il deployment dell'app in App Engine.

Installazione della libreria client Cloud per Cloud Storage

Per rendere disponibile la libreria client Cloud per Cloud Storage alla tua app quando viene eseguita in App Engine:

Aggiorna il file app.yaml:
1. Se utilizzi le librerie client di Cloud, aggiungi le ultime versioni delle librerie grpcio e setuptools.
2. Aggiungi la libreria ssl, poiché è richiesta da Cloud Storage.
Ecco un esempio di file app.yaml:
```
runtime: python27
threadsafe: yes
api_version: 1

libraries:
- name: grpcio
  version: 1.0.0
- name: setuptools
  version: 36.6.0
- name: ssl
  version: latest
```
Alcune librerie client non richiedono la libreria SSL. Se non includi la libreria SSL per una libreria client che ne ha bisogno, vedrai un errore SSL in Esplora log quando la tua app riceve una richiesta.
Aggiorna il file requirements.txt aggiungendo le librerie client Cloud per Cloud Storage all'elenco delle dipendenze:
```
google-cloud-storage==1.24.1
```
Ti consigliamo di utilizzare la versione 1.24.1 della libreria client Cloud Storage, poiché supporta le app Python 2.7.

Quindi esegui pip install -t lib -r requirements.txt per aggiornare l'elenco delle librerie disponibili per la tua app.
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)
```
Il file appengine_config.py nell'esempio precedente presuppone che la cartella lib si trovi nella directory di lavoro corrente. Se non puoi garantire che lib si trovi sempre nella directory di lavoro corrente, specifica il percorso completo della cartella lib. Ad esempio:
```
import os
path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
```

Aggiornamento del codice per utilizzare la libreria client di Cloud

Creazione di un client Cloud Storage

Per utilizzare la libreria client Cloud per Cloud Storage, crea un oggetto Client. Il client contiene le credenziali e altri dati necessari per connettersi a Cloud Storage. Ad esempio:

from google.cloud import storage

client = storage.Client()

Nello scenario di autorizzazione predefinito descritto in precedenza, il client Cloud Storage contiene le credenziali del account di servizio predefinito di App Engine, che è autorizzato a interagire con i bucket e gli oggetti del tuo progetto. Se non lavori in questo scenario predefinito, consulta Credenziali predefinite dell'applicazione (ADC) per informazioni su come fornire le credenziali.

Utilizzo dei metodi della libreria client di Cloud

La tabella seguente riassume i metodi della libreria client Cloud da utilizzare quando implementi funzionalità specifiche di Cloud Storage.

Funzionalità di Cloud Storage	Metodi client cloud
Elenca gli oggetti in un bucket	`Client.list_blobs` Visualizza un semplice esempio di codice e un esempio di emulazione della modalità directory. Per scorrere l'elenco degli oggetti, utilizza la proprietà `pages` dell'oggetto iteratore restituito da `Client.list_blobs`.
Scrivi nello spazio di archiviazione	`blob.upload_from_file` `blob.upload_from_filename` `blob.upload_from_string` Visualizza un esempio di codice.
Specificare gli ACL	Per applicare un ACL predefinito, utilizza il parametro `predefined_acl` quando crei un bucket o crei un oggetto. Per un controllo più granulare, utilizza `bucket.acl.reload()` o `blob.acl.reload()` per recuperare gli ACL attualmente definiti. Poi utilizza i metodi `ACL` per aggiungere o rimuovere gli elenchi di controllo dell'accesso. Visualizza un esempio di codice.
Lettura dallo spazio di archiviazione	`blob.download_to_file` `blob.download_to_filename` `blob.download_as_string` Visualizza un esempio di codice.
Elimina un oggetto	`blob.delete` Visualizza un esempio di codice.
Copiare un oggetto	`bucket.copy_blob` Visualizza un esempio di codice.
Leggere i metadati di un oggetto	`blob.propertyname` e `blob.metadata` Visualizza un esempio di codice.

Test degli aggiornamenti

Puoi testare gli aggiornamenti alla tua app in un ambiente locale, ma tutte le richieste Cloud Storage devono essere inviate su internet a un bucket Cloud Storage effettivo. Né App Engine né Cloud Storage forniscono un emulatore Cloud Storage.

Per ulteriori informazioni sul test delle app Python 3, consulta Test e deployment dell'applicazione.

Deployment dell'app

Quando è tutto pronto per il deployment dell'app, devi:

Testa l'app su App Engine.
Se l'app viene eseguita senza errori, utilizza la suddivisione del traffico per aumentare gradualmente il traffico per l'app aggiornata. Monitora attentamente l'app per rilevare eventuali problemi prima di indirizzare più traffico verso l'app aggiornata.