Esegui il deployment di una versione di base di "Google Traduttore" su Cloud Functions Python 3

1. Panoramica

Questa serie di codelab (tutorial pratici con un programma autonomo) ha lo scopo di aiutare gli sviluppatori a comprendere le varie opzioni a loro disposizione per 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 disponibile nel repo di questo tutorial può essere implementata in (almeno) otto modi diversi con solo piccole modifiche di configurazione:

  1. Server Flask locale (Python 2)
  2. Server Flask locale (Python 3)
  3. App Engine (Python 2)
  4. App Engine (Python 3)
  5. Cloud Functions (Python 3)
  6. Cloud Run (Python 2 tramite Docker)
  7. Cloud Run (Python 3 tramite Docker)
  8. Cloud Run (Python 3 tramite Cloud Buildpacks)

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

Imparerai a

Che cosa ti serve

Sondaggio

Come utilizzerai questo tutorial?

Leggi e completa gli esercizi Leggi solo

Come valuteresti la tua esperienza con Python?

Principiante Intermedio Proficiente

Come valuteresti la tua esperienza con l'utilizzo dei servizi Google Cloud?

Principiante Intermedio Proficiente

2. Configurazione e requisiti

Configurazione dell'ambiente a tuo ritmo

  1. 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.

96a9c957bc475304.png

b9a10ebdf5b5a448.png

a1e3c01a38fa61c2.png

  • Il nome del progetto è il nome visualizzato per i partecipanti al progetto. Si tratta di 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 è importante quale sia. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID), quindi se non ti piace, generane un altro casuale oppure puoi provare il tuo e vedere se è disponibile. Dopo la creazione del progetto, viene "congelato".
  • Esiste un terzo valore, un Numero progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.
  1. Successivamente, dovrai abilitare la fatturazione nella console Cloud per utilizzare le API/risorse Cloud. L'esecuzione di questo codelab non dovrebbe costare molto, se non del tutto. Per arrestare le risorse in modo da non incorrere in addebiti oltre questo tutorial, segui le istruzioni di "pulizia" riportate alla fine del codelab. I nuovi utenti di Google Cloud possono partecipare al programma Prova senza costi di 300$.

3. Abilita l'API Translation

In questa sezione imparerai ad abilitare le API di Google in generale. Per la nostra app di esempio, abiliterai l'API Cloud Translation e il servizio Cloud Functions.

Introduzione

Indipendentemente dall'API Google che vuoi utilizzare nella tua applicazione, questa deve essere attivata. L'esempio seguente mostra due modi per attivare l'API Cloud Vision. Dopo aver appreso come 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 attivare un'API come segue:

gcloud services enable SERVICE_NAME.googleapis.com

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

gcloud services enable vision.googleapis.com

Questo comando attiva 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 attivare l'API Vision in API Manager. In Cloud Console, vai ad API Manager e seleziona Libreria.

fb0f1d315f122d4a.png

Se vuoi attivare l'API Cloud Vision, inizia a digitare"vision" nella barra di ricerca e verranno visualizzati tutti gli elementi corrispondenti a quanto hai inserito finora:

2275786a24f8f204.png

Seleziona l'API che vuoi attivare e fai clic su Attiva:

2556f923b628e31.png

Costo

Sebbene molte API Google possano essere utilizzate senza costi, l'utilizzo dei prodotti e delle API di Google Cloud non è senza costi. Quando attivi le API Cloud, ti potrebbe essere chiesto un account di fatturazione attivo. Tuttavia, è importante notare che alcuni prodotti Google Cloud dispongono di un livello "Sempre senza costi" (giornaliero/mensile) che devi superare per incorrere in addebiti di fatturazione; in caso contrario, non verrà addebitato alcun importo sulla tua carta di credito (o sullo strumento di fatturazione specificato).

Gli utenti devono fare riferimento alle informazioni sui prezzi di qualsiasi API prima di attivarla, in particolare devono verificare se è disponibile un livello senza costi e, in caso affermativo, di che tipo. Se abiliti l'API Cloud Vision, devi controllare la pagina Informazioni sui prezzi. Cloud Vision ha una quota senza costi e, a condizione che tu rispetti i relativi limiti in aggregato (entro ogni mese), non dovrai sostenere alcun costo.

I prezzi e i livelli senza costi variano in base alle API Google. Esempi:

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

Riepilogo

Ora che sai come attivare le API Google in generale, vai ad API Manager e attiva sia l'API Cloud Translation sia il servizio Cloud Functions (se non l'hai già fatto), quest'ultimo perché la nostra applicazione lo utilizzerà e la prima perché stai eseguendo il deployment di una funzione Cloud. Se preferisci farlo dalla riga di comando, esegui invece questo comando:

gcloud services enable cloudfunctions.googleapis.com translate.googleapis.com

Sebbene la quota mensile non sia elencata nella pagina di riepilogo del livello "Sempre senza costi", la pagina dei prezzi dell'API Translation indica che tutti gli utenti ricevono ogni mese un numero fisso di caratteri tradotti. Se non superi questa soglia, non ti verranno addebitati costi dall'API. Se sono presenti altri addebiti relativi a Google Cloud, verranno discussi alla fine nella sezione "Pulizia".

4. Ottieni il codice dell'app di esempio

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

5cd6110c4414cf65.png

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 per non dover clonarlo o scaricarlo di nuovo.

5. Tour dell'app di esempio

L'app di esempio è un semplice derivato di Google Traduttore che chiede agli utenti di inserire del testo in inglese e di ricevere la traduzione equivalente in spagnolo. Ora apri il file main.py per vedere come funziona. Se ometti le righe commentate relative alla licenza, il codice avrà questo aspetto in alto e in basso:

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)))
  1. Le importazioni includono la funzionalità Flask, il modulo google.auth e la libreria client dell'API Cloud Translation.
  2. Le variabili globali rappresentano l'app Flask, l'ID progetto Cloud, il client dell'API Translation, il "percorso della posizione" principale per le chiamate all'API Translation e le lingue di origine e di destinazione. In questo caso, sono inglese (en) e spagnolo (es), ma puoi modificare questi valori con altri codici lingua supportati dall'API Cloud Translation.
  3. Il grande blocco if in basso viene utilizzato nel tutorial per eseguire questa app localmente: utilizza il server di sviluppo Flask per pubblicare 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 contenitore, ma se non lo fai, il codice dell'app tornerà a utilizzare il server di sviluppo Flask. Non si tratta di un problema con App Engine o Cloud Functions perché si tratta di piattaforme basate su origini, il che significa che Google Cloud fornisce ed esegue un server web 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 acquisire l'input dell'utente e di chiamare l'API Translation per eseguire le operazioni più complesse. Analizziamo la questione nel dettaglio:

  1. Controlla se le richieste provengono da Cloud Functions utilizzando la variabile local_request. Cloud Functions invia il proprio oggetto Request di Flask, mentre tutti gli altri (in esecuzione in locale o di cui è stato eseguito il deployment in App Engine o Cloud Run) riceveranno l'oggetto request direttamente da Flask.
  2. Reimposta le variabili di base per il modulo. Questo vale principalmente per le richieste GET, poiché le richieste POST avranno dati che li sostituiscono.
  3. Se si tratta di un POST, acquisisci 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.
  4. In ogni caso, formatta i risultati effettivi (POST) o nessun dato (GET) nel contesto del modello e esegui il rendering.

La parte visiva dell'applicazione si trova nel file del modello index.html. Mostra eventuali risultati tradotti in precedenza (vuoto in caso contrario), seguiti dal modulo che chiede qualcosa da tradurre:

<!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. Esegui il deployment del servizio

Per eseguire il deployment del servizio di traduzione in Cloud Functions (Python 3), esegui questo comando:

gcloud functions deploy translate --runtime python37 --trigger-http --allow-unauthenticated

L'output dovrebbe avere il seguente aspetto e fornire alcuni prompt per i passaggi successivi:

$ gcloud functions deploy translate --runtime python37 --trigger-http --allow-unauthenticated
Deploying function (may take a while - up to 2 minutes)...⠹
For Cloud Build Stackdriver Logs, visit: https://console.cloud.google.com/logs/viewer?project=PROJECT_ID&advancedFilter=resource.type%3Dbuild%0Aresource.labels.build_id%3D7e32429d-ec36-422c-8a8b-43c4d661a15c%0AlogName%3Dprojects%2FPROJECT_ID%2Flogs%2Fcloudbuild
Deploying function (may take a while - up to 2 minutes)...done.
availableMemoryMb: 256
buildId: 7e32429d-ec36-422c-8a8b-43c4d661a15
entryPoint: translate
httpsTrigger:
  securityLevel: SECURE_OPTIONAL
  url: https://REGION-PROJECT_ID.cloudfunctions.net/translate
ingressSettings: ALLOW_ALL
labels:
  deployment-tool: cli-gcloud
name: projects/PROJECT_ID/locations/REGION/functions/translate
runtime: python37
serviceAccountEmail: PROJECT_ID@appspot.gserviceaccount.com
sourceUploadUrl: https://storage.googleapis.com/gcf-upload-REGION-873f8448-838f-4eb2-beda-3e200a1420d/cb1cbdca-34eb-41d0-88d6-c276d5205fb.zip?GoogleAccessId=service-104690130103@gcf-admin-robot.iam.gserviceaccount.com&Expires=1619139674
status: ACTIVE
timeout: 60s
updateTime: '2021-04-23T00:32:58.065Z'
versionId: '3'

Ora che la tua app è disponibile in tutto il mondo, dovresti riuscire a raggiungerla all'URL contenente l'ID progetto, come mostrato nell'output di deployment. L'URL dovrebbe avere il seguente aspetto: https://REGION-PROJECT_ID.cloudfunctions.net/translate, che varia in base alla regione selezionata e all'ID progetto Cloud.

518f1c3165f2096d.png

Traduci qualcosa per vedere come funziona.

539b52bd25377888.png

7. Conclusione

Complimenti! Hai imparato ad attivare l'API Cloud Translation, a ottenere le credenziali necessarie e a eseguire il deployment di una semplice app web in Cloud Functions. Puoi scoprire di più su questo deployment in questa tabella del repository.

Esegui la pulizia

L'API Cloud Translation ti consente di eseguire una quantità fissa di caratteri tradotti al mese senza costi. App Engine ha anche una quota senza costi, così come Cloud Functions e Cloud Run. Ti verranno addebitati degli importi se uno dei due limiti viene superato. Se prevedi di passare al prossimo codelab, non devi arrestare l'app.

Tuttavia, se non vuoi ancora passare al tutorial successivo o temi che internet possa scoprire l'app che hai appena disegnato, disattiva l'app App Engine, elimina la funzione Cloud o disattiva il servizio Cloud Run per evitare di incorrere in addebiti. Quando vuoi passare al prossimo codelab, puoi riattivarlo. Se invece non vuoi continuare con questa applicazione o con altri codelab e vuoi eliminare tutto, puoi chiudere il progetto.

Inoltre, il deployment su una piattaforma di calcolo serverless di Google Cloud comporta costi di compilazione e archiviazione ridotti. 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 Artifact Registry, il suo successore. Lo spazio di archiviazione dell'immagine utilizza parte di questa quota, così come l'egresso di rete durante il trasferimento dell'immagine al servizio. Tuttavia, potresti risiedere in una regione in cui non è disponibile questo livello senza costi, quindi tieni d'occhio il tuo utilizzo dello spazio di archiviazione per ridurre al minimo i potenziali costi.

8. Risorse aggiuntive

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

Ulteriori studi

Ora che hai un po' di esperienza con l'API Translation, esegui alcuni esercizi aggiuntivi per sviluppare ulteriormente le tue competenze. Per continuare il tuo percorso di apprendimento, modifica la nostra app di esempio in modo da:

  1. Completa tutte le altre versioni di questo codelab per l'esecuzione locale o il deployment nelle piattaforme di calcolo serverless di Google Cloud (vedi README del repo).
  2. Completa questo tutorial utilizzando un altro linguaggio di programmazione.
  3. Modifica questa applicazione in modo che supporti lingue di origine o di destinazione diverse.
  4. Esegui l'upgrade di questa applicazione per poter tradurre il testo in più lingue; modifica il file del modello in modo da avere un menu a discesa delle lingue di destinazione supportate.

Scopri di più

Google App Engine

Google Cloud Functions

Google Cloud Run

Buildpack di Google Cloud, Container Registry, Artifact Registry

Google Cloud Translation e Google ML Kit

Altri prodotti/pagine Google Cloud

Python e 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.