Déployez une version de base de Google Traduction application sur Python 2 Cloud Run (Docker)

1. Présentation

Cette série d'ateliers de programmation (tutoriels pratiques à suivre à votre rythme) est destinée à aider les développeurs à comprendre les différentes options dont ils disposent lorsqu'ils déploient leurs applications. Dans cet atelier de programmation, vous allez apprendre à utiliser l'API Google Cloud Translation avec Python, et à l'exécuter localement ou à la déployer sur une plate-forme de calcul sans serveur Cloud (App Engine, Cloud Functions ou Cloud Run). L'application exemple disponible dans le dépôt de ce tutoriel peut être déployée (au moins) huit manières différentes avec seulement quelques modifications de configuration :

Serveur Flask local (Python 2)
Serveur Flask local (Python 3)
App Engine (Python 2)
App Engine (Python 3)
Cloud Functions (Python 3)
Cloud Run (Python 2 via Docker)
Cloud Run (Python 3 via Docker)
Cloud Run (Python 3 via Cloud Buildpacks)

Cet atelier de programmation se concentre sur le déploiement de cette application sur la ou les plates-formes en gras ci-dessus.

Vous apprendrez à effectuer les tâches suivantes :

Utiliser les API Google Cloud, en particulier l'API Cloud Translation (Advanced/v3)
Exécuter une application Web de base en local ou la déployer sur une plate-forme de calcul sans serveur dans le cloud

Prérequis

Un projet Google Cloud avec un compte de facturation Cloud actif
Flask installé pour l'exécution en local, ou une plate-forme de calcul sans serveur Cloud activée pour les déploiements dans le cloud
Des connaissances de base en Python
Bonne connaissance des commandes de base du système d'exploitation

Enquête

Comment allez-vous utiliser ce tutoriel ?

Je vais le lire et effectuer les exercices

Je vais le lire uniquement

Quel est votre niveau d'expérience avec Python ?

Débutant

Intermédiaire

Expert

Quel est votre niveau d'expérience avec les services Google Cloud ?

Débutant

Intermédiaire

Expert

2. Préparation

Configuration de l'environnement au rythme de chacun

Connectez-vous à la console Google Cloud, puis créez un projet ou réutilisez un projet existant. (Si vous ne possédez pas encore de compte Gmail ou Google Workspace, vous devez en créer un.)

Le nom du projet est le nom à afficher pour les participants au projet. Il s'agit d'une chaîne de caractères qui n'est pas utilisée par les API Google, et que vous pouvez modifier à tout moment.
L'ID du projet doit être unique sur l'ensemble des projets Google Cloud et doit être immuable (vous ne pouvez pas le modifier une fois que vous l'avez défini). Cloud Console génère automatiquement une chaîne unique dont la composition importe peu, en général. Dans la plupart des ateliers de programmation, vous devrez référencer l'ID du projet (généralement identifié comme PROJECT_ID), donc s'il ne vous convient pas, générez-en un autre au hasard ou définissez le vôtre, puis vérifiez s'il est disponible. Il est ensuite "gelé" une fois le projet créé.
La troisième valeur est le numéro de projet, utilisé par certaines API. Pour en savoir plus sur ces trois valeurs, consultez la documentation.

Vous devez ensuite activer la facturation dans Cloud Console afin d'utiliser les ressources/API Cloud. L'exécution de cet atelier de programmation est très peu coûteuse, voire sans frais. Pour arrêter les ressources afin d'éviter qu'elles ne vous soient facturées après ce tutoriel, suivez les instructions de nettoyage indiquées à la fin de l'atelier. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai sans frais pour bénéficier d'un crédit de 300$.

3. Activer l'API Translation

Activer les API Cloud

Dans cette section, vous allez apprendre à activer les API Google en général. Pour notre exemple d'application, vous allez activer l'API Cloud Translation, Cloud Run et Cloud Artifact Registry.

Introduction

Quelle que soit l'API Google que vous souhaitez utiliser dans votre application, vous devez l'activer. L'exemple suivant montre deux façons d'activer l'API Cloud Vision. Une fois que vous saurez comment activer une API Cloud, vous pourrez activer d'autres API, car la procédure est similaire.

Option 1 : Depuis Cloud Shell ou votre interface de ligne de commande

Bien qu'il soit plus courant d'activer les API depuis la console Cloud, certains développeurs préfèrent tout faire depuis la ligne de commande. Pour ce faire, vous devez rechercher le "nom de service " d'une API. Elle ressemble à une URL : SERVICE_NAME.googleapis.com. Vous les trouverez dans le tableau des produits compatibles. Vous pouvez également les interroger de manière programmatique avec l'API Google Discovery.

Grâce à ces informations, vous pouvez activer une API à l'aide de Cloud Shell (ou de votre environnement de développement local avec l'outil de ligne de commande gcloud installé), comme suit :

gcloud services enable SERVICE_NAME.googleapis.com

Par exemple, cette commande active l'API Cloud Vision :

gcloud services enable vision.googleapis.com

Cette commande active App Engine :

gcloud services enable appengine.googleapis.com

Vous pouvez également activer plusieurs API en une seule requête. Par exemple, cette ligne de commande active Cloud Run, Cloud Artifact Registry et l'API Cloud Translation :

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

Option 2 : Depuis la console Cloud

Vous pouvez également activer l'API Vision dans le gestionnaire d'API. Dans la console Cloud, accédez au Gestionnaire d'API, puis sélectionnez Bibliothèque.

Si vous souhaitez activer l'API Cloud Vision, commencez à saisir "vision" dans la barre de recherche. Tous les éléments correspondant à ce que vous avez saisi jusqu'à présent s'affichent :

Sélectionnez l'API que vous souhaitez activer, puis cliquez sur Activer :

Coût

Bien que de nombreuses API Google puissent être utilisées sans frais, l'utilisation des produits et API Google Cloud est payante. Lorsque vous activez les API Cloud, vous pouvez être invité à renseigner un compte de facturation actif. Il est toutefois important de noter que certains produits Google Cloud disposent d'un niveau "Always Free" (quotidien/mensuel) que vous devez dépasser pour que la facturation démarre. Sinon, votre carte de crédit (ou l'instrument de paiement spécifié) ne sera pas débitée.

Avant d'activer une API, les utilisateurs doivent consulter ses informations tarifaires, en particulier pour savoir si elle propose un niveau sans frais et, le cas échéant, quel est ce niveau. Si vous activiez l'API Cloud Vision, vous consulteriez sa page d'informations tarifaires. Cloud Vision dispose d'un quota sans frais. Tant que votre utilisation agrégée ne dépasse pas les limites (pour chaque mois), aucuns frais ne vous seront facturés.

Les tarifs et les niveaux sans frais varient selon les API Google. Exemples :

Google Cloud/GCP : chaque produit est facturé différemment. En général, il s'agit d'un paiement par cycle de processeur virtuel, par consommateur de stockage, par utilisation de mémoire ou par utilisation. Consultez les informations sur le niveau sans frais ci-dessus.
Google Maps : propose une suite d'API et offre aux utilisateurs un crédit mensuel sans frais de 200$.
Les API Google Workspace (anciennement G Suite) : elles offrent une utilisation sans frais (jusqu'à certaines limites) couverte par des frais d'abonnement mensuels Workspace. Par conséquent, il n'y a pas de facturation directe pour l'utilisation des API Gmail, Google Drive, Agenda, Docs, Sheets et Slides.

La procédure de facturation est différente selon les produits Google. Par conséquent, assurez-vous de vous référer à la documentation de votre API pour obtenir ces informations.

Résumé

Maintenant que vous savez comment activer les API Google en général, accédez au gestionnaire d'API et activez les API Cloud Translation, Cloud Run et Cloud Artifact Registry (si ce n'est pas déjà fait). Vous activez le premier, car notre application l'utilise. Vous devez activer ce dernier, car c'est là que nos images de conteneurs sont stockées avant d'être déployées pour démarrer votre service Cloud Run. C'est pourquoi vous devez l'activer. Si vous préférez les activer toutes avec l'outil gcloud, exécutez plutôt la commande suivante depuis votre terminal :

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

Bien que son quota mensuel ne soit pas indiqué sur la page récapitulative du niveau "Toujours sans frais ", la page des tarifs de l'API Translation indique que tous les utilisateurs bénéficient d'un nombre fixe de caractères traduits par mois. Si vous restez en dessous de ce seuil, vous ne devriez pas être facturé pour l'API. Si d'autres frais liés à Google Cloud sont facturés, ils seront abordés à la fin, dans la section "Nettoyer".

4. Obtenir le code de l'application exemple

Clonez le code dans le dépôt en local ou dans Cloud Shell (à l'aide de la commande git clone), ou téléchargez le fichier ZIP à partir de son bouton vert Code, comme illustré dans la capture d'écran suivante :

Maintenant que vous avez tout, créez une copie complète du dossier pour suivre ce tutoriel spécifique, car il impliquera probablement la suppression ou la modification des fichiers. Si vous souhaitez effectuer un autre déploiement, vous pouvez recommencer en copiant l'original afin de ne pas avoir à le cloner ni à le télécharger à nouveau.

5. Visite de l'application exemple

L'application exemple est un simple dérivé de Google Traduction qui invite les utilisateurs à saisir du texte en anglais et à recevoir la traduction équivalente de ce texte en espagnol. Ouvrez maintenant le fichier main.py pour voir comment il fonctionne. Si vous omettez les lignes commentées sur les licences, le résultat ressemble à ceci en haut et en bas :

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)))

Les importations apportent la fonctionnalité Flask, le module google.auth et la bibliothèque cliente de l'API Cloud Translation.
Les variables globales représentent l'application Flask, l'ID du projet Cloud, le client de l'API Translation, le "chemin d'emplacement" parent pour les appels de l'API Translation, ainsi que les langues source et cible. Dans ce cas, il s'agit de l'anglais (en) et de l'espagnol (es), mais n'hésitez pas à remplacer ces valeurs par d'autres codes de langue acceptés par l'API Cloud Translation.
Le grand bloc if en bas est utilisé dans le tutoriel pour exécuter cette application en local. Il utilise le serveur de développement Flask pour diffuser notre application. Cette section est également présente pour les tutoriels de déploiement Cloud Run au cas où le serveur Web ne serait pas inclus dans le conteneur. Il vous est demandé d'activer l'intégration du serveur dans le conteneur, mais si vous l'oubliez, le code de l'application revient à l'utilisation du serveur de développement Flask. (Il ne s'agit pas d'un problème lié à App Engine ou Cloud Functions, car il s'agit de plates-formes basées sur la source, ce qui signifie que Google Cloud fournit et exécute un serveur Web par défaut.)

Enfin, au milieu de main.py se trouve le cœur de l'application, la fonction 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 fonction principale consiste à prendre l'entrée utilisateur et à appeler l'API Translation pour effectuer le gros du travail. Examinons cela en détail :

Vérifiez si les requêtes proviennent de Cloud Functions à l'aide de la variable local_request. Cloud Functions envoie son propre objet de requête Flask, tandis que tous les autres (exécutés localement ou déployés sur App Engine ou Cloud Run) obtiennent l'objet de requête directement à partir de Flask.
Réinitialisez les variables de base du formulaire. Cela concerne principalement les requêtes GET, car les requêtes POST auront des données qui les remplaceront.
S'il s'agit d'une requête POST, récupérez le texte à traduire et créez une structure JSON représentant les exigences relatives aux métadonnées de l'API. Appelez ensuite l'API, en revenant à une version précédente de l'API si l'utilisateur utilise une ancienne bibliothèque.
Dans tous les cas, mettez en forme les résultats réels (POST) ou l'absence de données (GET) dans le contexte du modèle, puis affichez-les.

La partie visuelle de l'application se trouve dans le fichier de modèle index.html. Il affiche les résultats précédemment traduits (vide dans le cas contraire), suivis du formulaire demandant un élément à traduire :

<!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. Déployer le service

Vous êtes maintenant prêt à déployer votre service de traduction sur Cloud Run en exécutant la commande suivante :

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

Le résultat doit se présenter comme suit et fournir des suggestions pour les prochaines étapes :

$ 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

Maintenant que votre application est disponible dans le monde entier, vous devriez pouvoir y accéder à l'URL contenant l'ID de votre projet, comme indiqué dans le résultat du déploiement :

Traduisez quelque chose pour voir comment ça marche !

7. Conclusion

Félicitations ! Vous avez appris à activer l'API Cloud Translation, à obtenir les identifiants nécessaires et à déployer une application Web simple sur Python 2 Cloud Run. Pour en savoir plus sur ce déploiement, consultez ce tableau dans le dépôt.

Effectuer un nettoyage

L'API Cloud Translation vous permet de traduire sans frais un nombre fixe de caractères par mois. App Engine dispose également d'un quota sans frais, tout comme Cloud Functions et Cloud Run. Des frais vous seront facturés si l'un ou l'autre de ces seuils est dépassé. Si vous prévoyez de passer au prochain atelier de programmation, vous n'avez pas besoin d'arrêter votre application.

Toutefois, si vous n'êtes pas encore prêt à passer au tutoriel suivant ou si vous craignez que l'application que vous venez de déployer soit découverte sur Internet, désactivez votre application App Engine, supprimez votre fonction Cloud Functions ou désactivez votre service Cloud Run pour éviter les frais. Lorsque vous serez prêt à passer au prochain atelier de programmation, vous pourrez le réactiver. En revanche, si vous ne souhaitez pas poursuivre avec cette application ni d'autres ateliers de programmation et que vous souhaitez tout supprimer complètement, vous pouvez arrêter le projet.

De plus, le déploiement sur une plate-forme de calcul sans serveur Google Cloud entraîne des coûts de compilation et de stockage mineurs. Cloud Build et Cloud Storage disposent chacun de leur propre quota sans frais. Pour plus de transparence, Cloud Build compile l'image de votre application, qui est ensuite stockée dans Cloud Container Registry ou Artifact Registry, son successeur. Le stockage de cette image utilise une partie de ce quota, tout comme le trafic sortant du réseau lors du transfert de cette image vers le service. Toutefois, il est possible que vous résidiez dans une région où ce niveau sans frais n'est pas disponible. Veillez donc à surveiller votre utilisation de l'espace de stockage pour minimiser les coûts potentiels.

8. Ressources supplémentaires

Dans les sections suivantes, vous trouverez des ressources de lecture supplémentaires ainsi que des exercices recommandés pour approfondir vos connaissances acquises en suivant ce tutoriel.

Étude supplémentaire

Maintenant que vous avez acquis de l'expérience avec l'API Translation, faisons quelques exercices supplémentaires pour développer vos compétences. Pour poursuivre votre parcours d'apprentissage, modifiez notre exemple d'application pour effectuer les opérations suivantes :

Suivez toutes les autres éditions de cet atelier de programmation pour l'exécuter en local ou le déployer sur les plates-formes de calcul sans serveur Google Cloud (consultez le fichier README du dépôt).
Suivez ce tutoriel en utilisant un autre langage de programmation.
Modifiez cette application pour qu'elle accepte différentes langues sources ou cibles.
Mettez à niveau cette application pour pouvoir traduire du texte dans plusieurs langues. Modifiez le fichier de modèle pour qu'il contienne un menu déroulant des langues cibles acceptées.

En savoir plus

Google App Engine

Google Cloud Functions

Google Cloud Run

Google Cloud Buildpacks, Container Registry, Artifact Registry

Google Cloud Translation et Google ML Kit

Autres produits/pages Google Cloud

Python et Flask

Flask

Licence

Ce tutoriel est publié sous licence Creative Commons Attribution 2.0 Generic, tandis que le code source du dépôt est publié sous licence Apache 2.