Tutoriel sur les fonctions à distance et l'API Translation

Ce tutoriel explique comment créer une fonction distante BigQuery, appeler l'API Cloud Translation et effectuer une traduction de contenu de n'importe quelle langue vers l'espagnol en utilisant SQL et Python.

Voici quelques exemples d'utilisation de cette fonction :

• Traduire les commentaires d'utilisateurs d'un site Web dans la langue locale.
• Traduire les demandes d'assistance de nombreuses langues vers une langue commune pour le personnel d'assistance.

Objectifs

• Attribuer les rôles nécessaires à votre compte ;
• créer une fonction Cloud Functions ;
• créer un ensemble de données BigQuery ;
• créer une connexion BigQuery et un compte de service ;
• accorder des autorisations au compte de service BigQuery ;
• créer une fonction distante BigQuery ;
• appeler la fonction distante BigQuery.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• BigQuery
• Cloud Functions
• Cloud Translation

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Avant de commencer

Nous vous recommandons de créer un projet Google Cloud pour ce tutoriel. Assurez-vous également que vous disposez des rôles requis pour suivre ce tutoriel.

Configurer un projet Google Cloud

Pour configurer un projet Google Cloud pour ce tutoriel, procédez comme suit :

1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

   Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

   Accéder au sélecteur de projet

3. Vérifiez que la facturation est activée pour votre projet Google Cloud.

4. Activer les API BigQuery, BigQuery Connection, Cloud Translation, Cloud Functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry et Cloud Run Admin.

   Activer les API

5. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

   Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

   Accéder au sélecteur de projet

6. Vérifiez que la facturation est activée pour votre projet Google Cloud.

7. Activer les API BigQuery, BigQuery Connection, Cloud Translation, Cloud Functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry et Cloud Run Admin.

   Activer les API

Rôles requis pour votre compte

Pour obtenir les autorisations nécessaires pour effectuer les tâches de ce tutoriel, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

• Propriétaire de données BigQuery (roles/bigquery.dataOwner)
• Administrateur de connexion BigQuery (roles/bigquery.connectionAdmin)
• Développeur Cloud Functions (roles/cloudfunctions.developer)

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Ces rôles prédéfinis contiennent les autorisations requises pour effectuer les tâches décrites dans ce tutoriel. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour effectuer les tâches décrites dans ce tutoriel :

• bigquery.datasets.create
• bigquery.connections.create
• bigquery.connections.get
• cloudfunctions.functions.create

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Rôles requis pour le compte de service Compute Engine par défaut

Lorsque vous avez activé l'API pour Cloud Functions, un compte de service Compute Engine par défaut a été créé. Pour suivre ce tutoriel, vous devez attribuer le rôle d'utilisateur de l'API Cloud Translation à ce compte de service par défaut.

1. Récupérez l'ID attribué au projet

2. Copiez votre compte de service Compute Engine par défaut. Votre compte de service par défaut ressemble à ceci :

   [e-mail]
   

   Remplacez PROJECT_NUMBER par l'ID du projet.

3. Dans la console Google Cloud, accédez à la page IAM.

   Accéder à IAM

4. Sélectionnez votre projet.

5. Cliquez sur Accorder l'accès, puis collez le compte de service Compute Engine par défaut que vous avez copié précédemment dans le champ Nouveaux comptes principaux.

6. Dans la liste Attribuer des rôles, recherchez et sélectionnez Utilisateur de l'API Cloud Translation.

7. Cliquez sur Enregistrer.

Créer une fonction Cloud Functions

À l'aide de Cloud Functions, créez une fonction qui traduit le texte d'entrée en espagnol.

1. Créez une fonction Cloud Functions avec les spécifications suivantes :

   • Pour Environnement, sélectionnez 2e génération.
   • Dans le champ Nom de la fonction, saisissez translation-handler.
   • Dans le champ Région, sélectionnez us-central1.

   • Dans le champ Nombre maximal d'instances, saisissez 10.

     Ce paramètre se trouve dans la section Paramètres d'exécution, de compilation, de connexion et de sécurité.

     Dans ce tutoriel, nous utilisons une valeur inférieure à la valeur par défaut pour contrôler le taux de requêtes envoyées à Cloud Translation.

   • Dans le champ Environnement d'exécution, sélectionnez Python 3.10.

   • Dans le champ Point d'entrée, saisissez handle_translation.

2. Dans la liste des fichiers, sélectionnez main.py, puis collez le code suivant :

   Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.

   Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

   from __future__ import annotations
   
   import flask
   import functions_framework
   from google.api_core.retry import Retry
   from google.cloud import translate
   
   # Construct a Translation Client object
   translate_client = translate.TranslationServiceClient()
   
   # Register an HTTP function with the Functions Framework
   @functions_framework.http
   def handle_translation(request: flask.Request) -> flask.Response:
       """BigQuery remote function to translate input text.
   
       Args:
           request: HTTP request from BigQuery
           https://cloud.google.com/bigquery/docs/reference/standard-sql/remote-functions#input_format
   
       Returns:
           HTTP response to BigQuery
           https://cloud.google.com/bigquery/docs/reference/standard-sql/remote-functions#output_format
       """
       try:
           # Parse request data as JSON
           request_json = request.get_json()
           # Get the project of the query
           caller = request_json["caller"]
           project = extract_project_from_caller(caller)
           if project is None:
               return flask.make_response(
                   flask.jsonify(
                       {
                           "errorMessage": (
                               'project can\'t be extracted from "caller":' f" {caller}."
                           )
                       }
                   ),
                   400,
               )
           # Get the target language code, default is Spanish ("es")
           context = request_json.get("userDefinedContext", {})
           target = context.get("target_language", "es")
   
           calls = request_json["calls"]
           translated = translate_text([call[0] for call in calls], project, target)
   
           return flask.jsonify({"replies": translated})
       except Exception as err:
           return flask.make_response(
               flask.jsonify({"errorMessage": f"Unexpected error {type(err)}:{err}"}),
               400,
           )
   
   def extract_project_from_caller(job: str) -> str:
       """Extract project id from full resource name of a BigQuery job.
   
       Args:
           job: full resource name of a BigQuery job, like
             "//bigquery.googleapi.com/projects/<project>/jobs/<job_id>"
   
       Returns:
           project id which is contained in the full resource name of the job.
       """
       path = job.split("/")
       return path[4] if len(path) > 4 else None
   
   def translate_text(
       calls: list[str], project: str, target_language_code: str
   ) -> list[str]:
       """Translates the input text to specified language using Translation API.
   
       Args:
           calls: a list of input text to translate.
           project: the project where the translate service will be used.
           target_language_code: The ISO-639 language code to use for translation
             of the input text. See
             https://cloud.google.com/translate/docs/advanced/discovering-supported-languages-v3#supported-target
               for the supported language list.
   
       Returns:
           a list of translated text.
       """
       location = "<your location>"
       parent = f"projects/{project}/locations/{location}"
       # Call the Translation API, passing a list of values and the target language
       response = translate_client.translate_text(
           request={
               "parent": parent,
               "contents": calls,
               "target_language_code": target_language_code,
               "mime_type": "text/plain",
           },
           retry=Retry(),
       )
       # Convert the translated value to a list and return it
       return [translation.translated_text for translation in response.translations]
   
   

   Mettre <your location> à jour avec us-central1.

3. Dans la liste des fichiers, sélectionnez requirements.txt, puis collez le texte suivant :

   Flask==2.2.2
   functions-framework==3.5.0
   google-cloud-translate==3.11.1
   Werkzeug==2.3.7
   

4. Cliquez sur Déployer et attendez que la fonction soit déployée.

5. Cliquez sur l'onglet Déclencheur.

6. Copiez la valeur de l'URL du déclencheur et enregistrez-la pour une utilisation ultérieure. Vous devez utiliser cette URL lorsque vous créez une fonction distante BigQuery.

Créer un ensemble de données BigQuery

Créez un ensemble de données BigQuery qui contiendra la fonction distante. Lorsque vous créez l'ensemble de données, incluez les spécifications suivantes :

• Dans le champ ID de l'ensemble de données, saisissez remote_function_test.
• Dans le champ Type d'emplacement, sélectionnez Multirégional.
• Dans le champ Multirégional, sélectionnez US (plusieurs régions aux États-Unis).

Créer une connexion BigQuery et un compte de service

Créez une connexion BigQuery afin de pouvoir mettre en œuvre une fonction distante avec tous les langages compatibles avec Cloud Functions et Cloud Run. Lorsque vous créez une connexion, un compte de service est créé pour cette connexion.

1. Créez une connexion de ressource Google Cloud avec les spécifications suivantes :

   • Dans le champ Type de connexion, sélectionnez BigLake et fonctions distantes (ressource Cloud).
   • Dans le champ ID de connexion, saisissez remote-function-connection.
   • Dans le champ Type d'emplacement, sélectionnez Multirégional.
   • Dans le champ Multirégional, sélectionnez US (plusieurs régions aux États-Unis).

2. Ouvrez la liste Connexions externes, puis sélectionnez us.remote-function-connection.

3. Copiez l'ID du compte de service et enregistrez-le pour une utilisation ultérieure. Vous devrez accorder des autorisations à cet ID à l'étape suivante.

Accorder des autorisations au compte de service BigQuery

Le compte de service que vous avez créé à l'étape précédente doit être autorisé à utiliser Cloud Run pour que la fonction distante BigQuery puisse utiliser la fonction Cloud Functions. Pour accorder des autorisations au compte de service, procédez comme suit :

1. Accédez à la page Cloud Run

   Accédez à Cloud Run

2. Sélectionnez votre projet.

3. Cochez la case située à côté de translation-handler.

4. Dans le panneau Autorisations, cliquez sur Ajouter un compte principal.

5. Dans le champ Nouveaux comptes principaux, saisissez l'ID du compte de service que vous avez copié précédemment.

6. Dans la liste Attribuer des rôles, recherchez et sélectionnez Demandeur Cloud Run.

7. Cliquez sur Enregistrer.

Remarque : La prise en compte des nouvelles autorisations peut prendre jusqu'à une minute.

Créer une fonction distante BigQuery

Pour utiliser la fonction Cloud qui traduit du texte en espagnol avec une fonction distante BigQuery, procédez comme suit :

1. Dans la console Google Cloud, accédez à la page BigQuery.

   Accéder à BigQuery

2. Dans Query editor (éditeur de requête), saisissez la requête suivante :

   CREATE OR REPLACE FUNCTION `remote_function_test.translate_text`(x STRING)
   RETURNS
   STRING
       REMOTE WITH CONNECTION `us.remote-function-connection`
   OPTIONS (
       endpoint = 'TRIGGER_URL',
       max_batching_rows = 10);
   

   Remplacez TRIGGER_URL par l'URL du déclencheur que vous avez enregistrée lors de la création d'une fonction Cloud Functions.

3. Cliquez sur Exécuter. Un message de ce type s'affiche :

   This statement created a new function named
   your_project.remote_function_test.translate_text.
   

Remarque : Pour limiter le nombre de lignes incluses dans une requête HTTP, l'option max_batching_rows est définie sur 10. Lorsque vous ne spécifiez pas l'option max_batching_rows, BigQuery décide du nombre de lignes incluses dans une requête HTTP.

Appeler la fonction distante BigQuery

Après avoir créé votre fonction distante, testez-la pour vous assurer qu'elle est associée à la fonction Cloud Functions et qu'elle génère les résultats attendus en espagnol.

1. Dans l'éditeur de requête BigQuery, saisissez la requête suivante, puis cliquez sur Exécuter.

   SELECT
     remote_function_test.translate_text('This new feature is fantastic!')
       AS translated_text;
   

   Les résultats sont semblables aux suivants :

   +-------------------------------------------+
   | translated_text                           |
   +-------------------------------------------+
   | ¡Esta nueva característica es fantástica! |
   +-------------------------------------------+
   

2. Facultatif : Pour tester la fonction distante sur un ensemble de données public, saisissez la requête suivante, puis cliquez sur Exécuter. Pour limiter les résultats renvoyés, utilisez la clause LIMIT.

   SELECT
       text,
       remote_function_test.translate_text(text) AS translated_text
   FROM
       (SELECT text FROM `bigquery-public-data.hacker_news.full` LIMIT 3);
   

   Les résultats sont semblables aux suivants :

   +---------------------------------------------------------------------------+
   | text                            | translated_text                         |
   +---------------------------------------------------------------------------+
   | These benchmarks look good.     | Estos puntos de referencia se ven bien. |
   | Who is using Java?              | ¿Quién está usando Java?                |
   | You need more database storage. | Necesitas más almacenamiento.           |
   +---------------------------------------------------------------------------+
   

Supprimer les ressources

Si vous ne prévoyez pas d'utiliser ces fonctions dans ce projet, vous pouvez éviter de payer des coûts supplémentaires en supprimant votre projet. Toutes les ressources associées au projet seront définitivement supprimées.

Attention : La suppression d'un projet aura les effets suivants :

• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches de ce document, lorsque vous le supprimez, vous supprimez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

1. Dans la console Google Cloud, accédez à la page Gérer les ressources.

   Accéder à la page Gérer les ressources

2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Étapes suivantes

• Découvrez comment utiliser les fonctions distantes dans BigQuery.
• Découvrez Translation.
• Découvrez Cloud Functions.
• Découvrez Cloud Run.