Fonctions Cloud HTTP en Python

1. Introduction

Python est un langage de programmation Open Source populaire utilisé par les data scientists, les développeurs d'applications Web, les administrateurs système et bien d'autres.

Cloud Functions est une plate-forme de calcul sans serveur basée sur des événements. Cloud Functions vous permet d'écrire votre code sans vous soucier du provisionnement des ressources ni du scaling pour répondre aux exigences changeantes.

Il existe deux types de fonctions Cloud :

• Les fonctions HTTP répondent aux requêtes HTTP. Vous en créerez quelques-uns dans cet atelier de programmation.
• Les fonctions d'arrière-plan sont déclenchées par des événements, comme la publication d'un message dans Cloud Pub/Sub ou l'importation d'un fichier dans Cloud Storage. Nous n'aborderons pas ce point dans cet atelier, mais vous pouvez en savoir plus dans la documentation.

Cet atelier de programmation vous expliquera comment créer vos propres fonctions Cloud en Python.

Cet atelier de programmation s'adresse aux personnes qui connaissent un peu Python et qui souhaitent en savoir plus sur Cloud Functions. Des explications sont fournies pour tout le code Python, mais elles peuvent ne pas suffire pour une personne qui ne connaît pas du tout ce langage. Aucune connaissance préalable de Cloud Functions n'est requise.

Ce que vous allez faire

Dans cet atelier de programmation, vous allez publier une fonction Cloud qui, lorsqu'elle est appelée via HTTP, affiche le logo "Python Powered" :

Points abordés

• Comment écrire une fonction Cloud HTTP
• Comment écrire une fonction Cloud HTTP qui accepte des arguments
• Tester une fonction Cloud HTTP
• Comment exécuter un serveur HTTP Python local pour tester la fonction
• Comment écrire une fonction Cloud HTTP qui renvoie une image

2. Préparation

Configuration de l'environnement au rythme de chacun

1. Connectez-vous à la console Google Cloud, puis créez un projet ou réutilisez un projet existant. Si vous n'avez 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 non utilisée par les API Google. Vous pourrez toujours le modifier.
• L'ID du projet est unique parmi tous les projets Google Cloud et non modifiable une fois défini. La console Cloud génère automatiquement une chaîne unique (en général, vous n'y accordez d'importance particulière). Dans la plupart des ateliers de programmation, vous devrez indiquer l'ID de votre projet (généralement identifié par PROJECT_ID). Si l'ID généré ne vous convient pas, vous pouvez en générer un autre de manière aléatoire. Vous pouvez également en spécifier un et voir s'il est disponible. Après cette étape, l'ID n'est plus modifiable et restera donc le même pour toute la durée du projet.
• Pour information, il existe une troisième valeur (le numéro de projet) que certaines API utilisent. Pour en savoir plus sur ces trois valeurs, consultez la documentation.

Attention : Un ID de projet est unique. Une fois que vous l'avez choisi, personne d'autre ne peut l'employer. Vous en êtes le seul utilisateur. Même si un projet est supprimé, son ID ne peut pas être réutilisé.

Remarque : Si vous utilisez un compte Gmail, vous pouvez conserver l'emplacement par défaut défini sur Aucune organisation. Si vous utilisez un compte Google Workspace, choisissez un emplacement qui ait du sens pour votre organisation.

2. Vous devez ensuite activer la facturation dans la console Cloud pour utiliser les ressources/API Cloud. L'exécution de cet atelier de programmation est très peu coûteuse, voire sans frais. Pour désactiver les ressources et éviter ainsi que des frais ne vous soient facturés après ce tutoriel, vous pouvez supprimer le projet ou les ressources que vous avez créées. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai sans frais pour bénéficier d'un crédit de 300 $.

Démarrer Cloud Shell

Bien que Google Cloud puisse être utilisé à distance depuis votre ordinateur portable, nous allons nous servir de Cloud Shell pour cet atelier de programmation, un environnement de ligne de commande exécuté dans le cloud.

Activer Cloud Shell

1. Dans Cloud Console, cliquez sur Activer Cloud Shell .

Si vous démarrez Cloud Shell pour la première fois, un écran intermédiaire s'affiche pour vous expliquer de quoi il s'agit. Si cet écran s'est affiché, cliquez sur Continuer.

Le provisionnement et la connexion à Cloud Shell ne devraient pas prendre plus de quelques minutes.

Cette machine virtuelle contient tous les outils de développement nécessaires. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud, ce qui améliore nettement les performances du réseau et l'authentification. Vous pouvez réaliser une grande partie, voire la totalité, des activités de cet atelier de programmation dans un navigateur.

Une fois connecté à Cloud Shell, vous êtes en principe authentifié, et le projet est défini avec votre ID de projet.

2. Exécutez la commande suivante dans Cloud Shell pour vérifier que vous êtes authentifié :

gcloud auth list

Résultat de la commande

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Remarque : gcloud est l'outil de ligne de commande performant et unifié de Google Cloud. Il est préinstallé dans Cloud Shell. Il est également compatible avec la saisie semi-automatique via la touche de tabulation. Vous serez peut-être invité à vous authentifier la première fois que vous exécuterez une commande. Pour en savoir plus, consultez la présentation de l'outil de ligne de commande gcloud.

3. Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet :

gcloud config list project

Résultat de la commande

[core]
project = <PROJECT_ID>

Si vous obtenez un résultat différent, exécutez cette commande :

gcloud config set project <PROJECT_ID>

Résultat de la commande

Updated property [core/project].

Remarque : Si vous suivez ce tutoriel en dehors de Cloud Shell, suivez Configurer les identifiants par défaut de l'application.

Vérifier que les API Cloud Functions et Cloud Build sont activées

Exécutez la commande suivante depuis Cloud Shell pour vous assurer que les API Cloud Functions et Cloud Build sont activées :

gcloud services enable \
  cloudfunctions.googleapis.com \
  cloudbuild.googleapis.com

Remarque : Cloud Build sera appelé par la commande gcloud functions deploy et compilera automatiquement votre code dans une image de conteneur.

Télécharger le code source

Dans le terminal Cloud Shell, exécutez les commandes suivantes :

REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="cloud-functions-python-http"

git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL
cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR

Consultez le contenu du répertoire source :

ls

Vous devez disposer des fichiers suivants :

main.py  python-powered.png  test_main.py  web_app.py

3. Présentation des fonctions Cloud HTTP

Les fonctions Cloud HTTP en Python sont écrites en tant que fonctions Python standards. La fonction doit accepter un seul argument flask.Request, généralement nommé request.

main.py

import flask


def hello_world(request: flask.Request) -> flask.Response:
    """HTTP Cloud Function.

    Returns:
    - "Hello World! 👋"
    """
    response = "Hello World! 👋"

    return flask.Response(response, mimetype="text/plain")

# ...

Vous pouvez ouvrir le fichier avec l'éditeur de ligne de commande de votre choix (nano, vim ou emacs). Vous pouvez également l'ouvrir dans l'éditeur Cloud Shell après avoir défini le répertoire source comme espace de travail :

cloudshell open-workspace .

Déployons cette fonction en tant que fonction Cloud Functions HTTP à l'aide de la commande gcloud functions deploy :

FUNCTION_NAME="hello_world"

gcloud functions deploy $FUNCTION_NAME \
  --runtime python312 \
  --trigger-http \
  --allow-unauthenticated

Résultat de la commande :

...
Deploying function (may take a while - up to 2 minutes)...done.
availableMemoryMb: 256
...
entryPoint: FUNCTION_NAME
httpsTrigger:
  url: https://REGION-PROJECT_ID.cloudfunctions.net/FUNCTION_NAME
...

Remarques sur les options gcloud functions deploy :

• --runtime : spécifie l'environnement d'exécution du langage. Pour Python, il peut actuellement s'agir de python37, python38, python39, python310 ou python312. Consultez Environnements d'exécution.
• --trigger-http : un point de terminaison sera attribué à la fonction. Les requêtes HTTP (POST, PUT, GET, DELETE et OPTIONS) envoyées au point de terminaison déclenchent l'exécution de la fonction.
• --allow-unauthenticated : la fonction sera publique, ce qui permettra à tous les appelants d'y accéder sans authentification.
• Pour en savoir plus, consultez gcloud functions deploy.

Vous avez rencontré une erreur lors du déploiement ? Vérifiez les éléments suivants :

• Les API sont-elles activées ? Revérifiez l'étape précédente "Configuration et conditions requises".
• Assurez-vous que votre répertoire de travail (celui à partir duquel vous exécutez gcloud) est celui qui contient le fichier main.py.
• Le nom de la fonction est-il correct ? Il doit s'agir de hello_world, le nom de la fonction Python que nous essayons de déployer.

Pour tester la fonction, vous pouvez cliquer sur l'URL httpsTrigger.url affichée dans le résultat de la commande ci-dessus. Vous pouvez également récupérer l'URL de manière programmatique et appeler la fonction à l'aide des commandes suivantes :

URL=$(gcloud functions describe $FUNCTION_NAME --format "value(httpsTrigger.url)")
curl -w "\n" $URL

Vous devriez obtenir le résultat suivant :

Hello World! 👋

Félicitations ! Vous avez écrit et déployé une fonction Cloud HTTP.

4. Écrire une fonction Cloud HTTP qui accepte des arguments

Les fonctions sont plus polyvalentes lorsqu'elles acceptent des arguments. Définissons une nouvelle fonction hello_name qui accepte un paramètre name :

main.py

# ...

def hello_name(request: flask.Request) -> flask.Response:
    """HTTP Cloud Function.

    Returns:
    - "Hello {NAME}! 🚀" if "name=NAME" is defined in the GET request
    - "Hello World! 🚀" otherwise
    """
    name = request.args.get("name", "World")
    response = f"Hello {name}! 🚀"

    return flask.Response(response, mimetype="text/plain")

# ...

Déployons cette nouvelle fonction :

FUNCTION_NAME="hello_name"

gcloud functions deploy $FUNCTION_NAME \
  --runtime python312 \
  --trigger-http \
  --allow-unauthenticated

Résultat de la commande :

...
Deploying function (may take a while - up to 2 minutes)...done.
availableMemoryMb: 256
...
entryPoint: FUNCTION_NAME
httpsTrigger:
  url: https://REGION-PROJECT_ID.cloudfunctions.net/FUNCTION_NAME
...

Pour tester la fonction, vous pouvez cliquer sur l'URL httpsTrigger.url affichée dans le résultat de la commande ci-dessus. Vous pouvez également récupérer l'URL de manière programmatique et appeler la fonction à l'aide des commandes suivantes :

URL=$(gcloud functions describe $FUNCTION_NAME --format "value(httpsTrigger.url)")
curl -w "\n" $URL

Vous devriez obtenir le résultat par défaut :

Hello World! 🚀

Vous obtenez le résultat par défaut, car l'argument name n'est pas défini. Ajoutez un paramètre à l'URL :

curl -w "\n" $URL?name=YOUR%20NAME

Cette fois, vous obtiendrez votre réponse personnalisée :

Hello YOUR NAME! 🚀

L'étape suivante consiste à ajouter des tests unitaires pour vous assurer que vos fonctions continuent de fonctionner comme prévu lorsque le code source est mis à jour.

5. Écrire des tests

Les fonctions Cloud Functions HTTP en Python sont testées à l'aide du module unittest de la bibliothèque standard. Vous n'avez pas besoin d'exécuter un émulateur ou une autre simulation pour tester votre fonction, seulement du code Python classique.

Voici à quoi ressemble un test pour les fonctions hello_world et hello_name :

test_main.py

import unittest
import unittest.mock

import main


class TestHello(unittest.TestCase):
    def test_hello_world(self):
        request = unittest.mock.Mock()

        response = main.hello_world(request)
        assert response.status_code == 200
        assert response.get_data(as_text=True) == "Hello World! 👋"

    def test_hello_name_no_name(self):
        request = unittest.mock.Mock(args={})

        response = main.hello_name(request)
        assert response.status_code == 200
        assert response.get_data(as_text=True) == "Hello World! 🚀"

    def test_hello_name_with_name(self):
        name = "FirstName LastName"
        request = unittest.mock.Mock(args={"name": name})

        response = main.hello_name(request)
        assert response.status_code == 200
        assert response.get_data(as_text=True) == f"Hello {name}! 🚀"

1. Les tests Python sont écrits de la même manière que les autres fichiers Python. Ils commencent par un ensemble d'importations, puis définissent des classes et des fonctions.
2. La déclaration de test se présente sous la forme class TestHello(TestCase). Il doit s'agir d'une classe qui hérite de unittest.TestCase.
3. La classe de test comporte des méthodes, chacune devant commencer par test_, qui représentent des scénarios de test individuels.
4. Chaque scénario de test teste l'une de nos fonctions en simulant le paramètre request (c'est-à-dire en le remplaçant par un faux objet contenant les données spécifiques requises pour le test).
5. Après avoir appelé chaque fonction, le test vérifie la réponse HTTP pour s'assurer qu'elle correspond à nos attentes.

Comme main.py dépend de flask, assurez-vous que le framework Flask est installé dans votre environnement de test :

pip install flask

L'installation de Flask génère un résultat semblable à celui-ci :

Collecting flask
...
Successfully installed ... flask-3.0.2 ...

Exécutez ces tests en local :

python -m unittest

Les trois tests unitaires devraient réussir :

...
----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK

Le test ne fonctionne pas ?

• Vérifiez si le message d'erreur contient des informations utiles.
• Vérifiez que vous vous trouvez bien dans le même répertoire que celui qui contient les fichiers main.py et test_main.py.

Ensuite, vous allez créer une fonction qui renvoie le logo "Python Powered".

6. Écrire la fonction Cloud HTTP "Python Powered"

Rendons une nouvelle fonction un peu plus amusante en renvoyant l'image "Python Powered" pour chaque requête :

La liste suivante montre le code à utiliser pour cette tâche :

main.py

# ...

def python_powered(request: flask.Request) -> flask.Response:
    """HTTP Cloud Function.

    Returns:
    - The official "Python Powered" logo
    """
    return flask.send_file("python-powered.png")

Déployez une fonction python_powered :

FUNCTION_NAME="python_powered"

gcloud functions deploy $FUNCTION_NAME \
  --runtime python312 \
  --trigger-http \
  --allow-unauthenticated

Résultat de la commande :

...
Deploying function (may take a while - up to 2 minutes)...done.
availableMemoryMb: 256
...
entryPoint: FUNCTION_NAME
httpsTrigger:
  url: https://REGION-PROJECT_ID.cloudfunctions.net/FUNCTION_NAME
...

Pour tester la fonction, cliquez sur l'URL httpsTrigger.url affichée dans le résultat de la commande ci-dessus. Si tout fonctionne correctement, le logo "Python Powered" s'affiche dans un nouvel onglet de navigateur.

Ensuite, vous allez créer une application pour pouvoir exécuter et tester votre fonction en local avant le déploiement.

7. Exécuter la fonction en local

Vous pouvez exécuter une fonction HTTP en local en créant une application Web et en appelant votre fonction dans un itinéraire. Vous pouvez l'ajouter dans le même répertoire que votre fonction. Le fichier nommé web_app.py contient les éléments suivants :

web_app.py

import flask

import main

app = flask.Flask(__name__)


@app.get("/")
def index():
    return main.python_powered(flask.request)


if __name__ == "__main__":
    # Local development only
    # Run "python web_app.py" and open http://localhost:8080
    app.run(host="localhost", port=8080, debug=True)

1. Ce fichier crée une application Flask.
2. Il enregistre un itinéraire à l'URL de base, qui est géré par une fonction nommée index().
3. La fonction index() appelle ensuite notre fonction python_powered, en lui transmettant la requête actuelle.

Assurez-vous que le framework Flask est installé dans votre environnement de développement :

pip install flask

L'installation de Flask génère un résultat semblable à celui-ci :

Collecting flask
...
Successfully installed ... flask-3.0.2 ...

Pour exécuter cette application en local, exécutez la commande suivante :

python web_app.py

Utilisez maintenant l'option d'aperçu sur le Web de Cloud Shell pour tester l'application Web dans votre navigateur. Dans Cloud Shell, cliquez sur le bouton "Aperçu sur le Web", puis sélectionnez "Prévisualiser sur le port 8080" :

Cloud Shell utilise son service proxy pour ouvrir l'URL d'aperçu dans une nouvelle fenêtre de navigateur. L'aperçu Web limite l'accès via HTTPS à votre compte utilisateur uniquement. Si tout fonctionne correctement, le logo "Python Powered" devrait s'afficher.

Vous ne voyez pas le logo ?

• Vérifiez que vous vous trouvez bien dans le même répertoire que celui qui contient les fichiers main.py, python_powered.jpg et web_app.py.
• Le serveur est-il démarré ? Veillez à le démarrer en exécutant python web_app.py. La sortie devrait afficher Running on http://localhost:8080.

8. Félicitations !

Vous avez déployé des fonctions Cloud HTTP à l'aide de fonctions idiomatiques qui gèrent les requêtes Web avec le framework Flask.

Les tarifs de Cloud Functions sont basés sur la fréquence d'appel de votre fonction. Ils incluent une version sans frais pour les fonctions qui ne s'exécutent pas souvent. Une fois que vous avez terminé de tester vos fonctions Cloud, vous pouvez les supprimer à l'aide de gcloud :

gcloud functions delete hello_world --quiet
gcloud functions delete hello_name --quiet
gcloud functions delete python_powered --quiet

Vous pouvez également supprimer les fonctions à partir de la console Google Cloud.

Nous espérons que vous apprécierez l'utilisation de Cloud Functions en Python.