Tutorial sobre funciones remotas y la API Translation

En este tutorial se describe cómo crear una función remota de BigQuery, invocar la API Cloud Translation y traducir contenido de cualquier idioma al español con SQL y Python.

Entre los usos de esta función se incluyen los siguientes:

• Traducir comentarios de usuarios en un sitio web a un idioma local
• Traducir las solicitudes de asistencia de muchos idiomas a un idioma común para los agentes de asistencia

Objetivos

• Asigna los roles necesarios a tu cuenta.
• Crea una función de Cloud Run Functions.
• Crea un conjunto de datos de BigQuery.
• Crea una conexión de BigQuery y una cuenta de servicio.
• Conceda permisos a la cuenta de servicio de BigQuery.
• Crea una función remota de BigQuery.
• Llama a la función remota de BigQuery.

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

• BigQuery
• Cloud Run functions
• Cloud Translation

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Antes de empezar

Te recomendamos que crees un proyecto de Google Cloud para este tutorial. Además, asegúrate de que tienes los roles necesarios para completar este tutorial.

Configurar un Google Cloud proyecto

Para configurar un Google Cloud proyecto para este tutorial, sigue estos pasos:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection, Cloud Translation, Cloud Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery, BigQuery Connection, Cloud Translation, Cloud Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Roles necesarios para tu cuenta

Para obtener los permisos que necesitas para realizar las tareas de este tutorial, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

• Propietario de datos de BigQuery (roles/bigquery.dataOwner)
• Administrador de conexiones de BigQuery (roles/bigquery.connectionAdmin)
• Desarrollador de Cloud Functions (roles/cloudfunctions.developer)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para realizar las tareas de este tutorial. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

Para realizar las tareas de este tutorial, se necesitan los siguientes permisos:

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

También puedes obtener estos permisos con roles personalizados u otros roles predefinidos.

Roles necesarios para la cuenta de servicio predeterminada de Compute Engine

Cuando habilitaste la API para las funciones de Cloud Run, se creó una cuenta de servicio predeterminada de Compute Engine. Para completar este tutorial, debes asignar el rol Usuario de la API Cloud Translation a esta cuenta de servicio predeterminada.

1. Obtén el ID asignado al proyecto.

2. Copia tu cuenta de servicio predeterminada de Compute Engine. Tu cuenta de servicio predeterminada tiene este aspecto:

   [e-mail]
   

   Sustituye PROJECT_NUMBER por el ID del proyecto.

3. En la consola, ve a la página Gestión de identidades y accesos. Google Cloud

   Ir a Gestión de identidades y accesos

4. Selecciona el proyecto.

5. Haz clic en Conceder acceso y, a continuación, en el campo Nuevos principales, pega la cuenta de servicio predeterminada de Compute Engine que has copiado antes.

6. En la lista Asignar roles, busca y selecciona Usuario de la API Cloud Translation.

7. Haz clic en Guardar.

Crear una función de Cloud Run Functions

Crea una función que traduzca el texto introducido al español mediante funciones de Cloud Run.

1. Crea una función de Cloud Run Functions con las siguientes especificaciones:

   • En Entorno, selecciona 2.ª gen..
   • En Nombre de la función, escribe translation-handler.
   • En Región, selecciona us-central1.

   • En Número máximo de instancias, introduce 10.

     Este ajuste se encuentra en la sección Ajustes de tiempo de ejecución, compilación, conexiones y seguridad.

     En este tutorial, usamos un valor inferior al predeterminado para controlar la frecuencia de las solicitudes enviadas a Translation.

   • En Tiempo de ejecución, selecciona Python 3.10.

   • En Punto de entrada, escribe handle_translation.

2. En la lista de archivos, selecciona main.py y pega el siguiente código.

   Antes de probar este ejemplo, sigue las Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.

   Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

   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]
   
   

   Actualiza <your location> con us-central1.

3. En la lista de archivos, selecciona requirements.txt y pega el siguiente texto:

   Flask==2.2.2
   functions-framework==3.9.2
   google-cloud-translate==3.18.0
   Werkzeug==2.3.8
   

4. Haga clic en Desplegar y espere a que se despliegue la función.

5. Haga clic en la pestaña Activador.

6. Copia el valor de URL de activación y guárdalo para más adelante. Debe usar esta URL cuando cree una función remota de BigQuery.

Crear un conjunto de datos de BigQuery

Crea un conjunto de datos de BigQuery que contenga la función remota. Cuando cree el conjunto de datos, incluya estas especificaciones:

• En ID del conjunto de datos, introduce remote_function_test.
• En Tipo de ubicación, selecciona Multirregión.
• En Multirregión, selecciona Estados Unidos (varias regiones de Estados Unidos).

Crear una conexión de BigQuery y una cuenta de servicio

Crea una conexión de BigQuery para poder implementar una función remota con cualquiera de los lenguajes admitidos en las funciones y en Cloud Run. Cuando creas una conexión, se crea una cuenta de servicio para esa conexión.

1. Crea una Google Cloud conexión de recursos con las siguientes especificaciones:

   • En Tipo de conexión, selecciona Funciones remotas y de BigLake (recurso de Cloud).
   • En Connection ID (ID de conexión), introduce remote-function-connection.
   • En Tipo de ubicación, selecciona Multirregión.
   • En Multirregión, selecciona Estados Unidos (varias regiones de Estados Unidos).

2. Abre la lista Conexiones externas y selecciona us.remote-function-connection.

3. Copia el ID de la cuenta de servicio y guárdalo para más adelante. En el siguiente paso, debe conceder permisos a este ID.

Conceder permisos a la cuenta de servicio de BigQuery

La cuenta de servicio que has creado en el paso anterior necesita permiso para usar Cloud Run, de forma que la función remota de BigQuery pueda usar la función de Cloud Run. Para conceder permisos a la cuenta de servicio, sigue estos pasos:

1. Ve a la página Cloud Run.

   Ir a Cloud Run

2. Selecciona el proyecto.

3. Selecciona la casilla situada junto a translation-handler.

4. En el panel Permisos, haz clic en Añadir principal.

5. En el campo Nuevos principales, introduce el ID de la cuenta de servicio que has copiado anteriormente.

6. En la lista Asignar roles, busca y selecciona Invocador de Cloud Run.

7. Haz clic en Guardar.

Nota: Los nuevos permisos pueden tardar hasta un minuto en aplicarse.

Crear una función remota de BigQuery

Para usar la función de Cloud Run Functions que traduce texto al español con una función remota de BigQuery, sigue estos pasos.

1. En la Google Cloud consola, ve a la página BigQuery.

   Ir a BigQuery

2. En el editor de consultas, escribe la siguiente consulta:

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

   Sustituye TRIGGER_URL por la URL del activador que guardaste anteriormente al crear una función de Cloud Run Functions.

3. Haz clic en Ejecutar. Se muestra un mensaje similar al siguiente:

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

Nota: Para limitar el número de filas que se incluyen en una solicitud HTTP, la opción max_batching_rows se define como 10 . Si no especificas la opción max_batching_rows, BigQuery decide cuántas filas se incluyen en una solicitud HTTP.

Llamar a la función remota de BigQuery

Después de crear la función remota, pruébala para asegurarte de que está vinculada a la función de Cloud Run Functions y de que produce los resultados esperados en español.

1. En el editor de consultas de BigQuery, introduce la siguiente consulta y, a continuación, haz clic en Ejecutar.

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

   Los resultados son similares a los siguientes:

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

2. Opcional: Para probar la función remota en un conjunto de datos público, introduce la siguiente consulta y haz clic en Ejecutar. Para limitar los resultados devueltos, usa la cláusula LIMIT.

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

   Los resultados son similares a los siguientes:

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

Eliminar los recursos

Si no tienes previsto usar estas funciones en este proyecto, puedes evitar costes adicionales eliminándolo. De esta forma, se eliminarán permanentemente todos los recursos asociados al proyecto.

Precaución: Eliminar un proyecto tiene los siguientes efectos:

• Se elimina todo el contenido del proyecto. Si has usado un proyecto que ya existía para las tareas de este documento, cuando lo elimines, también se eliminará cualquier otro trabajo que hayas realizado en él.
• Se pierden los IDs de proyecto personalizados. Cuando creaste este proyecto, es posible que hayas creado un ID de proyecto personalizado que quieras usar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, elimina los recursos seleccionados dentro del proyecto en lugar de eliminar todo el proyecto.

Si tienes previsto consultar varias arquitecturas, tutoriales o guías de inicio rápido, reutilizar los proyectos puede ayudarte a no superar los límites de cuota de proyectos.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

Siguientes pasos

• Consulta cómo usar funciones remotas en BigQuery.
• Consulta información sobre la traducción.
• Consulta información sobre Cloud Run Functions.
• Consulta información sobre Cloud Run.