Instructivo de la API de Translation y las funciones remotas

En este instructivo, se describe cómo crear una función remota de BigQuery, invocar la API de Cloud Translation y realizar la traducción de contenido desde cualquier idioma a español mediante SQL y Python.

Estos son algunos casos de uso de esta función:

• Traducir los comentarios de los usuarios en un sitio web a un idioma local
• Traducir solicitudes de asistencia de muchos idiomas a un idioma común para trabajadores que atienden casos de asistencia

Objetivos

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

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• BigQuery
• Cloud Functions
• Cloud Translation

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud califiquen para obtener una prueba gratuita.

Antes de comenzar

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

Configura un proyecto de Google Cloud

Si deseas configurar un proyecto de Google Cloud para este instructivo, completa estos pasos:

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

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

   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

3. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

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

   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

6. Make sure that billing is enabled for your Google Cloud project.

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

   Enable the APIs

Roles necesarios para su cuenta

A fin de obtener los permisos que necesitas para realizar las tareas de este instructivo, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

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

Si quieres obtener más información para otorgar roles, consulta Administra el acceso.

Estos roles predefinidos contienen los permisos necesarios para realizar las tareas de este instructivo. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para realizar las tareas de este instructivo:

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

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

Funciones necesarias para la cuenta de servicio predeterminada de Compute Engine

Cuando habilitaste la API para Cloud Functions, se creó una cuenta de servicio predeterminada de Compute Engine. Para completar este instructivo, debes otorgar a esta cuenta de servicio predeterminada la función de usuario de la API de Cloud Translation.

1. Obtén el ID asignado al proyecto.

2. Copia tu cuenta de servicio predeterminada de Compute Engine. La cuenta de servicio predeterminada se ve de la siguiente manera:

   [e-mail]
   

   Reemplaza PROJECT_NUMBER con el ID del proyecto.

3. En la consola de Google Cloud, ve a la página IAM.

   Ir a IAM

4. Selecciona tu proyecto.

5. Haz clic en Otorgar acceso y, luego, en el campo Principales nuevos, pega la cuenta de servicio predeterminada de Compute Engine que copiaste antes.

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

7. Haz clic en Guardar.

Crea una función de Cloud Functions

Con Cloud Functions, crea una función que traduzca el texto de entrada al español.

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

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

   • En Cantidad máxima de instancias, ingresa 10.

     Esta configuración se encuentra en la sección Configuración del entorno de ejecución, la compilación, las conexiones y la seguridad.

     En este instructivo, usamos un valor menor que el predeterminado para controlar el porcentaje de solicitudes enviadas a Translation.

   • Para Entorno de ejecución, selecciona Python 3.10.

   • En Punto de entrada, ingresa handle_translation.

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

   Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

   Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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, luego, pega el siguiente texto:

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

4. Haz clic en Implementar y espera a que la función se implemente.

5. Haz clic en la pestaña Activador.

6. Copia el valor de la URL del activador y guárdalo para usarlo más adelante. Debes usar esta URL cuando crees una función remota de BigQuery.

Crea un conjunto de datos de BigQuery

Crea un conjunto de datos de BigQuery que contendrá la función remota. Cuando crees el conjunto de datos, incluye estas especificaciones:

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

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

Crea una conexión de BigQuery para poder implementar una función remota con cualquier lenguaje compatible en Cloud Functions y Cloud Run. Cuando creas una conexión, se crea una cuenta de servicio para esa conexión.

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

   • En Tipo de conexión, selecciona BigLake y funciones remotas (Cloud Resource)
   • En ID de conexión, ingresa remote-function-connection.
   • En Tipo de ubicación, selecciona Multirregión.
   • En Multirregión, selecciona EE.UU. (varias regiones en 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 usarlo más adelante. Debes otorgar permisos a este ID en el paso siguiente.

Otorga permisos a la cuenta de servicio de BigQuery

La cuenta de servicio que creaste en el paso anterior necesita permiso para usar Cloud Run a fin de que la función remota de BigQuery pueda usar la función de Cloud Functions. Para otorgar permisos a la cuenta de servicio, completa los siguientes pasos:

1. Ir a la página Cloud Run.

   Ir a Cloud Run

2. Selecciona tu proyecto.

3. Selecciona la casilla de verificación junto a translation-handler.

4. En el panel Permisos, haz clic en Agregar principal.

5. En el campo Principales nuevas (New principals), ingresa el ID de la cuenta de servicio que copiaste antes.

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

7. Haz clic en Guardar.

Nota: Puede pasar hasta un minuto hasta que se apliquen los permisos nuevos.

Crea una función remota de BigQuery

Para usar la función de Cloud Functions que traduce texto en español con una función remota de BigQuery, completa los siguientes pasos.

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

   Ir a BigQuery

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

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

   Reemplaza TRIGGER_URL por la URL del activador que guardaste antes cuando creaste una función de Cloud Functions.

3. Haga clic en Ejecutar. Aparecerá un mensaje similar al que figura a continuación:

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

Nota: Para limitar la cantidad de filas que se incluyen en una solicitud HTTP, la opción max_batching_rows se configura como 10. Cuando no especificas la opción max_batching_rows, BigQuery decide cuántas filas se incluyen en una solicitud HTTP.

Llama a la función remota de BigQuery

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

1. En el editor de consultas de BigQuery, ingresa la siguiente consulta y, luego, haz clic en Ejecutar.

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

   Las políticas son similares a las siguientes:

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

2. Opcional: Para probar la función remota en un conjunto de datos públicos, ingresa la siguiente consulta y, luego, haz clic en Ejecutar. Para limitar los resultados que se muestran, 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);
   

   Las políticas son similares a las 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.           |
   +---------------------------------------------------------------------------+
   

Borra recursos

Si no planeas usar estas funciones en este proyecto, puedes borrar los proyectos para evitar costos adicionales. Esto borra de forma permanente todos los recursos asociados con el proyecto.

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo en el proyecto. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los ID personalizados de proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URL que utilizan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto en lugar de borrar todo el proyecto.

Si planeas explorar varias infraestructuras, instructivos y guías de inicio rápido la reutilización de proyectos puede ayudarte a evitar exceder los límites de las cuotas del proyecto.

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.

¿Qué sigue?

• Aprende a usar las funciones remotas en BigQuery.
• Obtén más información sobre Translation.
• Obtén información sobre Cloud Functions.
• Obtener información sobre Cloud Run.