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:

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. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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

    Go to project selector

  3. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

  4. Habilita las API de BigQuery, BigQuery Connection, Cloud Translation, Cloud Functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin.

    Habilita las API

    5.

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

    Go to project selector

  6. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

  7. Habilita las API de BigQuery, BigQuery Connection, Cloud Translation, Cloud Functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin.

    Habilita las API

    8.

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:

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:

    PROJECT_NUMBER[email protected]

    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.

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.

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.

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

    Ir a Administrar recursos

  2. En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
  3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

¿Qué sigue?