Esegui il deployment di una versione di base di "Google Traduttore" app su Python 3 Cloud Run (Docker)

1. Panoramica

Questa serie di codelab (tutorial pratici e autonomi) ha lo scopo di aiutare gli sviluppatori a comprendere le varie opzioni a loro disposizione durante il deployment delle applicazioni. In questo codelab imparerai a utilizzare l'API Google Cloud Translation con Python ed eseguirla localmente o eseguirne il deployment su una piattaforma di calcolo serverless Cloud (App Engine, Cloud Functions o Cloud Run). L'app di esempio che si trova nel repository di questo tutorial può essere implementata (almeno) in otto modi diversi con solo piccole modifiche alla configurazione:

Server Flask locale (Python 2)
Server Flask locale (Python 3)
App Engine (Python 2)
App Engine (Python 3)
Cloud Functions (Python 3)
Cloud Run (Python 2 tramite Docker)
Cloud Run (Python 3 tramite Docker)
Cloud Run (Python 3 tramite Cloud Buildpacks)

Questo codelab si concentra sul deployment di questa app sulle piattaforme in grassetto sopra.

Imparerai come

Utilizza le API Google Cloud, in particolare l'API Cloud Translation (avanzata/v3)
Esegui un'applicazione web di base localmente o esegui il deployment su una piattaforma di computing serverless cloud.

Che cosa ti serve

Un progetto Google Cloud con un account di fatturazione Cloud attivo
Flask installato per l'esecuzione locale o una piattaforma di computing serverless Cloud abilitata per i deployment basati sul cloud
Competenze di base di Python
Conoscenza pratica dei comandi di base del sistema operativo

Sondaggio

Come utilizzerai questo tutorial?

Leggilo e completa gli esercizi

Leggilo soltanto

Come valuteresti la tua esperienza con Python?

Principiante

Intermedio

Avanzato

Come valuti la tua esperienza di utilizzo dei servizi Google Cloud?

Principiante

Intermedio

Avanzato

2. Configurazione e requisiti

Configurazione dell'ambiente autonomo

Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Google Workspace, devi crearne uno.

Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google e puoi aggiornarla in qualsiasi momento.
L'ID progetto deve essere univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo essere stato impostato). Cloud Console genera automaticamente una stringa univoca, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, devi fare riferimento all'ID progetto (che in genere è identificato come PROJECT_ID), quindi, se non ti piace, generane un altro casuale oppure puoi provare il tuo e vedere se è disponibile. Viene "congelato" dopo la creazione del progetto.
Esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.

Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. L'esecuzione di questo codelab non dovrebbe costare molto, se non nulla. Per arrestare le risorse in modo da non incorrere in costi di fatturazione al termine di questo tutorial, segui le istruzioni di "pulizia" riportate alla fine del codelab. I nuovi utenti di Google Cloud possono beneficiare del programma prova senza costi di 300$.

3. Abilita l'API Translation

Attivazione delle API Cloud

In questa sezione, imparerai come abilitare le API di Google in generale. Per la nostra app di esempio, abiliterai l'API Cloud Translation, Cloud Run e Cloud Artifact Registry.

Introduzione

Indipendentemente dall'API Google che vuoi utilizzare nella tua applicazione, deve essere abilitata. Il seguente esempio mostra due modi per abilitare l'API Cloud Vision. Dopo aver imparato ad abilitare un'API Cloud, potrai abilitare altre API perché la procedura è simile.

Opzione 1: da Cloud Shell o dall'interfaccia a riga di comando

Sebbene l'abilitazione delle API dalla console Cloud sia più comune, alcuni sviluppatori preferiscono fare tutto dalla riga di comando. Per farlo, devi cercare il "nome del servizio " di un'API. Sembra un URL: SERVICE_NAME.googleapis.com. Puoi trovarli nel grafico dei prodotti supportati oppure puoi eseguire query in modo programmatico con l'API Google Discovery.

Con queste informazioni, utilizzando Cloud Shell (o il tuo ambiente di sviluppo locale con lo strumento a riga di comando gcloud installato), puoi abilitare un'API nel seguente modo:

gcloud services enable SERVICE_NAME.googleapis.com

Ad esempio, questo comando abilita l'API Cloud Vision:

gcloud services enable vision.googleapis.com

Questo comando abilita App Engine:

gcloud services enable appengine.googleapis.com

Puoi anche attivare più API con una sola richiesta. Ad esempio, questa riga di comando abilita Cloud Run, Cloud Artifact Registry e l'API Cloud Translation:

gcloud services enable artifactregistry.googleapis.com run.googleapis.com translate.googleapis.com

Opzione 2: da Cloud Console

Puoi anche abilitare l'API Vision in API Manager. Nella console Cloud, vai a API Manager e seleziona Libreria.

Se vuoi abilitare l'API Cloud Vision, inizia a digitare"vision" nella barra di ricerca e verranno visualizzati tutti i risultati corrispondenti a ciò che hai digitato finora:

Seleziona l'API che vuoi abilitare e fai clic su Abilita:

Costo

Sebbene molte API di Google possano essere utilizzate senza costi, l'utilizzo di prodotti e API Google Cloud non è senza costi. Quando abiliti le API Cloud, potrebbe esserti chiesto un account di fatturazione attivo. Tuttavia, è importante notare che alcuni prodotti Google Cloud includono un livello "Sempre senza costi" (giornaliero/mensile), che devi superare per incorrere in addebiti di fatturazione; in caso contrario, la tua carta di credito (o lo strumento di fatturazione specificato) non verrà addebitata.

Prima di abilitare un'API, gli utenti devono consultare le informazioni sui prezzi, in particolare per verificare se è disponibile un livello senza costi e, in caso affermativo, qual è. Se abilitassi l'API Cloud Vision, dovresti controllare la pagina con le informazioni sui prezzi. Cloud Vision ha una quota senza costi e, se rispetti i limiti complessivi (entro ogni mese), non dovresti sostenere alcun costo.

I prezzi e i livelli senza costi variano a seconda delle API di Google. Esempi:

Google Cloud/GCP: ogni prodotto viene fatturato in modo diverso e generalmente si paga per ciclo di vCPU, consumer di spazio di archiviazione, utilizzo di memoria o in base al consumo; consulta le informazioni sul livello senza costi riportate sopra.
Google Maps: offre una suite di API e un credito mensile senza costi di 200$.
API Google Workspace (in precedenza G Suite): forniscono un utilizzo senza costi (fino a determinati limiti) coperto da una tariffa di abbonamento mensile a Workspace, pertanto non è prevista una fatturazione diretta per l'utilizzo delle API Gmail, Google Drive, Calendar, Documenti, Fogli e Presentazioni.

I diversi prodotti Google vengono fatturati in modo diverso, quindi assicurati di consultare la documentazione dell'API per queste informazioni.

Riepilogo

Ora che sai come abilitare le API di Google in generale, vai a API Manager e abilita l'API Cloud Translation, Cloud Run e Cloud Artifact Registry (se non l'hai già fatto). Attiva il primo perché la nostra applicazione lo utilizza. Attivi quest'ultimo perché è qui che vengono archiviate le nostre immagini container prima di essere sottoposte a deployment per avviare il servizio Cloud Run, motivo per cui devi attivarlo. Se preferisci abilitarle tutte con lo strumento gcloud, esegui invece questo comando dal terminale:

gcloud services enable artifactregistry.googleapis.com run.googleapis.com translate.googleapis.com

Sebbene la quota mensile non sia elencata nella pagina di riepilogo del livello "Sempre senza costi" complessivo, la pagina dei prezzi dell'API Translation indica che tutti gli utenti ricevono mensilmente un importo fisso di caratteri tradotti. Se rimani al di sotto di questa soglia, non dovresti sostenere alcun costo per l'API. Eventuali altri addebiti correlati a Google Cloud verranno discussi alla fine della sezione "Pulizia".

4. Ottieni il codice dell'app di esempio

Clona il codice nel repository in locale o in Cloud Shell (utilizzando il comando git clone) oppure scarica il file ZIP dal pulsante verde Code, come mostrato nello screenshot seguente:

Ora che hai tutto, crea una copia completa della cartella per seguire questo tutorial specifico, perché probabilmente dovrai eliminare o modificare i file. Se vuoi eseguire un deployment diverso, puoi ricominciare copiando l'originale, in modo da non doverlo clonare o scaricare di nuovo.

5. Tour dell'app di esempio

L'app di esempio è un semplice derivato di Google Traduttore che chiede agli utenti di inserire un testo in inglese e di ricevere la traduzione equivalente in spagnolo. Ora apri il file main.py per vedere come funziona. Omettendo le righe commentate relative alle licenze, la parte superiore e inferiore ha questo aspetto:

from flask import Flask, render_template, request
import google.auth
from google.cloud import translate

app = Flask(__name__)
_, PROJECT_ID = google.auth.default()
TRANSLATE = translate.TranslationServiceClient()
PARENT = 'projects/{}'.format(PROJECT_ID)
SOURCE, TARGET = ('en', 'English'), ('es', 'Spanish')

# . . . [translate() function definition] . . .

if __name__ == '__main__':
    import os
    app.run(debug=True, threaded=True, host='0.0.0.0',
            port=int(os.environ.get('PORT', 8080)))

Le importazioni includono la funzionalità Flask, il modulo google.auth e la libreria client dell'API Cloud Translation.
Le variabili globali rappresentano l'app Flask, l'ID progetto Cloud, il client API Translation, il "percorso della posizione" principale per le chiamate all'API Translation e le lingue di origine e di destinazione. In questo caso, si tratta di inglese (en) e spagnolo (es), ma puoi modificare questi valori con altri codici lingua supportati dall'API Cloud Translation.
Il blocco if di grandi dimensioni in basso viene utilizzato nel tutorial per eseguire questa app localmente: utilizza il server di sviluppo Flask per gestire la nostra app. Questa sezione è presente anche per i tutorial sul deployment di Cloud Run nel caso in cui il server web non sia incluso nel contenitore. Ti viene chiesto di attivare il bundling del server nel container, ma se lo trascuri, il codice dell'app torna a utilizzare il server di sviluppo Flask. Non si tratta di un problema di App Engine o Cloud Functions, perché si tratta di piattaforme basate sull'origine, il che significa che Google Cloud fornisce ed esegue un web server predefinito.

Infine, al centro di main.py si trova il cuore dell'applicazione, la funzione translate():

@app.route('/', methods=['GET', 'POST'])
def translate(gcf_request=None):
    """
    main handler - show form and possibly previous translation
    """

    # Flask Request object passed in for Cloud Functions
    # (use gcf_request for GCF but flask.request otherwise)
    local_request = gcf_request if gcf_request else request

    # reset all variables (GET)
    text = translated = None

    # if there is data to process (POST)
    if local_request.method == 'POST':
        text = local_request.form['text']
        data = {
            'contents': [text],
            'parent': PARENT,
            'target_language_code': TARGET[0],
        }
        # handle older call for backwards-compatibility
        try:
            rsp = TRANSLATE.translate_text(request=data)
        except TypeError:
            rsp = TRANSLATE.translate_text(**data)
        translated = rsp.translations[0].translated_text

    # create context & render template
    context = {
        'orig':  {'text': text, 'lc': SOURCE},
        'trans': {'text': translated, 'lc': TARGET},
    }
    return render_template('index.html', **context)

La funzione principale si occupa di prendere l'input dell'utente e chiamare l'API Translation per svolgere il lavoro più pesante. Analizziamo la questione nel dettaglio:

Verifica se le richieste provengono da Cloud Functions utilizzando la variabile local_request. Cloud Functions invia il proprio oggetto Flask Request, mentre tutti gli altri (in esecuzione in locale o deployment su App Engine o Cloud Run) ricevono l'oggetto richiesta direttamente da Flask.
Reimposta le variabili di base per il modulo. Questo vale principalmente per le richieste GET, poiché le richieste POST avranno dati che li sostituiranno.
Se si tratta di un POST, prendi il testo da tradurre e crea una struttura JSON che rappresenti il requisito dei metadati dell'API. Quindi chiama l'API, tornando a una versione precedente dell'API se l'utente utilizza una libreria precedente.
In ogni caso, formatta i risultati effettivi (POST) o nessun dato (GET) nel contesto del modello ed esegui il rendering.

La parte visiva dell'applicazione si trova nel file modello index.html. Mostra i risultati tradotti in precedenza (altrimenti vuoti), seguiti dal modulo che chiede di tradurre qualcosa:

<!doctype html>
<html><head><title>My Google Translate 1990s</title><body>
<h2>My Google Translate (1990s edition)</h2>

{% if trans['text'] %}
    <h4>Previous translation</h4>
    <li><b>Original</b>:   {{ orig['text'] }}  (<i>{{ orig['lc'][0] }}</i>)</li>
    <li><b>Translated</b>: {{ trans['text'] }} (<i>{{ trans['lc'][0] }}</i>)</li>
{% endif %}

<h4>Enter <i>{{ orig['lc'][1] }}</i> text to translate to <i>{{ trans['lc'][1] }}</i>:</h4>
<form method="POST"><input name="text"><input type="submit"></form>
</body></html>

6. Imposta Docker per creare l'immagine Python 3

Ora apri il file Dockerfile, che, senza le informazioni sulla licenza, ha questo aspetto:

#FROM python:3-slim
FROM python:2-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
ENTRYPOINT ["python", "main.py"]

Come puoi notare, per impostazione predefinita è configurato per Python 2, quindi modifichiamolo modificando la riga FROM da python:2-slim a python:3-slim o rimuovendo il commento dalla prima riga ed eliminando la vecchia riga FROM. Al termine, Dockerfile dovrebbe avere il seguente aspetto:

FROM python:3-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
ENTRYPOINT ["python", "main.py"]

7. Esegui il deployment del servizio

Ora puoi eseguire il deployment del servizio di traduzione su Cloud Run eseguendo questo comando:

gcloud run deploy translate --source . --allow-unauthenticated --platform managed

L'output dovrebbe essere simile al seguente e fornire alcuni suggerimenti per i passaggi successivi:

$ gcloud run deploy translate --source . --allow-unauthenticated --platform managed
Please specify a region:
 [1] asia-east1
 [2] asia-east2
. . . (other regions) . . .
 [28] us-west4
 [29] cancel
Please enter your numeric choice:  REGION_CHOICE

To make this the default region, run `gcloud config set run/region REGION`.

Deploying from source requires an Artifact Registry repository to
store build artifacts. A repository named [cloud-run-source-deploy] in
 region [REGION] will be created.

Do you want to continue (Y/n)?

This command is equivalent to running "gcloud builds submit --pack image=[IMAGE] ." and "gcloud run deploy translate --image [IMAGE]"

Building . . . and deploying container to Cloud Run service [translate] in project [PROJECT_ID] region [REGION]
✓ Building and deploying... Done.
  ✓ Creating Container Repository...
  ✓ Uploading sources...
  ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/60e1b
  9bb-b991-4b4e-8d8a-HASH?project=PROJECT_NUMBER].
  ✓ Creating Revision...
  ✓ Routing traffic...
  ✓ Setting IAM Policy...
Done.
Service [translate] revision [translate-00001-xyz] has been deployed and is serving 100 percent of traffic.
Service URL: https://SVC_NAME-HASH-REG_ABBR.a.run.app

Ora che la tua app è disponibile a livello globale in tutto il mondo, dovresti essere in grado di raggiungerla all'URL contenente l'ID progetto, come mostrato nell'output del deployment:

Traduci qualcosa per vedere come funziona.

8. Conclusione

Complimenti! Hai imparato ad abilitare l'API Cloud Translation, a ottenere le credenziali necessarie e a eseguire il deployment di una semplice app web in Python 3 Cloud Run.

Esegui la pulizia

L'API Cloud Translation ti consente di eseguire una quantità fissa di caratteri tradotti al mese senza costi. Anche App Engine ha una quota senza costi, così come Cloud Functions e Cloud Run. Se uno dei due viene superato, ti verranno addebitati dei costi. Se prevedi di continuare con il codelab successivo, non devi chiudere l'app.

Tuttavia, se non sei ancora pronto per passare al tutorial successivo o temi che internet possa scoprire l'app che hai appena eseguito il deployment, disattiva l'app App Engine, elimina la tua Cloud Function o disattiva il servizio Cloud Run per evitare addebiti. Quando vuoi passare al codelab successivo, puoi riattivarlo. D'altra parte, se non intendi continuare con questa applicazione o con altri codelab e vuoi eliminare tutto completamente, puoi chiudere il progetto.

Inoltre, il deployment su una piattaforma di serverless computing di Google Cloud comporta costi minimi di build e archiviazione. Cloud Build ha una propria quota senza costi, così come Cloud Storage. Per una maggiore trasparenza, Cloud Build crea l'immagine dell'applicazione, che viene poi archiviata in Cloud Container Registry o in Artifact Registry, il suo successore. L'archiviazione di questa immagine utilizza parte della quota, così come l'uscita di rete durante il trasferimento dell'immagine al servizio. Tuttavia, potresti vivere in una regione che non dispone di un livello senza costi, quindi tieni sotto controllo l'utilizzo dello spazio di archiviazione per ridurre al minimo i potenziali costi.

9. Risorse aggiuntive

Nelle sezioni seguenti puoi trovare materiale di lettura aggiuntivo ed esercizi consigliati per approfondire le conoscenze acquisite completando questo tutorial.

Ulteriori studi

Ora che hai un po' di esperienza con l'API Translation, facciamo altri esercizi per sviluppare ulteriormente le tue competenze. Per continuare il tuo percorso di apprendimento, modifica la nostra app di esempio per eseguire le seguenti operazioni:

Completa tutte le altre versioni di questo codelab per l'esecuzione locale o il deployment sulle piattaforme di serverless computing di Google Cloud (vedi il file README del repository).
Completa questo tutorial utilizzando un altro linguaggio di programmazione.
Modifica questa applicazione per supportare lingue di origine o di destinazione diverse.
Esegui l'upgrade di questa applicazione per poter tradurre il testo in più di una lingua; modifica il file del modello in modo che contenga un menu a discesa delle lingue di destinazione supportate.

Scopri di più

Google App Engine

Google Cloud Functions

Google Cloud Run

Google Cloud Buildpacks, Container Registry, Artifact Registry

Google Cloud Translation e Google ML Kit

Altre pagine/altri prodotti Google Cloud

Python e Flask

Flask

Licenza

Questo tutorial è concesso in licenza ai sensi di una licenza Creative Commons Attribution 2.0 Generic, mentre il codice sorgente nel repository è concesso in licenza ai sensi di Apache 2.