Tutorial sulle funzioni remote e sull'API Translation

Questo tutorial descrive come creare una funzione remota BigQuery, richiamare l'API Cloud Translation e eseguire la traduzione dei contenuti da qualsiasi lingua allo spagnolo utilizzando SQL e Python.

Ecco alcuni casi d'uso per questa funzione:

  • Tradurre i commenti degli utenti su un sito web nella lingua locale
  • Traduci le richieste di assistenza da più lingue in un'unica lingua comune per operatori delle richieste di assistenza

Obiettivi

  • Assegna i ruoli necessari al tuo account.
  • Creare una funzione di funzioni di Cloud Run.
  • Creare un set di dati BigQuery.
  • Creare una connessione BigQuery e un account di servizio.
  • Concedi le autorizzazioni all'account di servizio BigQuery.
  • Creare una funzione remota BigQuery.
  • Chiamare la funzione remota di BigQuery.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud potrebbero essere idonei per una prova gratuita.

Prima di iniziare

Ti consigliamo di creare un progetto Google Cloud per questo tutorial. Assicurati inoltre di disporre dei ruoli richiesti per completare questo tutorial.

Configura un progetto Google Cloud

Per configurare un progetto Google Cloud per questo tutorial, segui questi passaggi:

  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.

    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 Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs.

    Enable the APIs

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud 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 Run functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry, and Cloud Run Admin APIs.

    Enable the APIs

    8.

Ruoli richiesti per il tuo account

Per ottenere le autorizzazioni necessarie per eseguire le attività descritte in questo tutorial, chiedi all'amministratore di concederti i seguenti ruoli IAM sul tuo progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per eseguire le attività in questo tutorial. Per vedere le autorizzazioni esatte obbligatorie, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per eseguire le attività descritte in questo tutorial sono necessarie le seguenti autorizzazioni:

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

Potresti anche riuscire a ottenere queste autorizzazioni con ruoli personalizzati e altri ruoli predefiniti.

Ruoli obbligatori per l'account di servizio predefinito di Compute Engine

Quando hai abilitato l'API per le funzioni Cloud Run, viene eseguita una Account di servizio predefinito Compute Engine è stata creata. Per completare questo tutorial, devi dare a questo il ruolo Utente API Cloud Translation.

  1. Ottieni l'ID assegnato al progetto.

  2. Copia il tuo account di servizio predefinito di Compute Engine. Valore predefinito Questo account di servizio ha il seguente aspetto:

    PROJECT_NUMBER-compute@developer.gserviceaccount.com

    Sostituisci PROJECT_NUMBER con l'ID progetto.

  3. Nella console Google Cloud, vai alla pagina IAM.

    Vai a IAM

  4. Seleziona il progetto.

  5. Fai clic su Concedi l'accesso e nel campo Nuove entità incolla Account di servizio predefinito di Compute Engine che hai copiato in precedenza.

  6. Nell'elenco Assegna ruoli, cerca e seleziona Utente API Cloud Translation.

  7. Fai clic su Salva.

Creare una funzione Cloud Run

Utilizzando le funzioni Cloud Run, crea una funzione che traduca il testo inserito in spagnolo.

  1. Crea una funzione Functions di Cloud Run con le seguenti specifiche:

    • Per Ambiente, seleziona 2a generazione.
    • In Nome funzione, inserisci translation-handler.
    • In Regione, seleziona us-central1.

    • In Numero massimo di istanze, inserisci 10.

      Questa impostazione si trova nella sezione Runtime, build, connessioni e sicurezza impostazioni.

      In questo tutorial viene utilizzato un valore inferiore a quello predefinito per controllare tasso di richieste inviate a Translation.

    • Per Runtime, seleziona Python 3.10.

    • In Punto di ingresso, inserisci handle_translation.

  2. Nell'elenco dei file, seleziona main.py e incolla il seguente codice.

    Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Python BigQuery documentazione di riferimento.

    Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client. 

    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]

    Aggiorna <your location> con us-central1.

  3. Nell'elenco dei file, seleziona requirements.txt e incolla il seguente testo:

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

  4. Fai clic su Esegui il deployment e attendi il deployment della funzione.

  5. Fai clic sulla scheda Trigger.

  6. Copia il valore dell'URL attivatore e salvalo per un secondo momento. Devi usare questo URL quando crei una funzione remota BigQuery.

Crea un set di dati BigQuery

Crea un set di dati BigQuery che conterrà la funzione remota. Quando crei il set di dati, includi queste specifiche:

  • In ID set di dati, inserisci remote_function_test.
  • In Tipo di località, seleziona Più regioni.
  • Per Più regioni, seleziona USA (più regioni negli Stati Uniti).

Crea una connessione e un account di servizio BigQuery

Crea una connessione BigQuery in modo da poter implementare un funzione remota con qualsiasi linguaggio supportato nelle funzioni di Cloud Run e in Cloud Run. Quando crei una connessione, viene creato un account di servizio per quella connessione.

  1. Crea una connessione alle risorse Google Cloud con le seguenti specifiche:

    • Per Tipo di connessione, seleziona BigLake e funzioni remote (risorsa Cloud)
    • In ID connessione, inserisci remote-function-connection.
    • In Tipo di località, seleziona Più regioni.
    • Per Più regioni, seleziona USA (più regioni negli Stati Uniti).

  2. Apri l'elenco Connessioni esterne e seleziona us.remote-function-connection.

  3. Copia l'ID account di servizio e salvalo per un secondo momento. Devi concedere autorizzazioni a questo ID nel passaggio successivo.

Concedi le autorizzazioni all'account di servizio BigQuery

L'account di servizio che hai creato nel passaggio precedente deve disporre dell'autorizzazione per utilizzare Cloud Run in modo che la funzione remota BigQuery possa utilizzare la funzione delle funzioni Cloud Run. Per concedere le autorizzazioni all'account di servizio, completa i seguenti passaggi:

  1. Vai alla pagina Cloud Run.

    Vai a Cloud Run

  2. Seleziona il progetto.

  3. Seleziona la casella di controllo accanto a translation-handler.

  4. Nel riquadro Autorizzazioni, fai clic su Aggiungi entità.

  5. Nel campo Nuove entità, inserisci l'ID account di servizio che hai copiato in precedenza.

  6. Nell'elenco Assegna ruoli, cerca e seleziona Invoker di Cloud Run.

  7. Fai clic su Salva.

Creare una funzione remota BigQuery

Per utilizzare la funzione Cloud Run che traduce il testo in spagnolo con una funzione remota BigQuery, completa i seguenti passaggi.

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery

  2. Nell'editor di query, inserisci la seguente query:

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

    Sostituisci TRIGGER_URL con l'URL di attivazione che hai salvate in precedenza, quando hai creato una funzione di Cloud Run.

  3. Fai clic su Esegui. Viene visualizzato un messaggio simile al seguente:

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

chiama la funzione remota BigQuery

Dopo aver creato la funzione remota, testala per assicurarti che sia collegata alla funzione Functions di Cloud Run e produce i risultati previsti in spagnolo.

  1. Nell'editor query di BigQuery, inserisci la query seguente, quindi fai clic su Esegui.

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

    I risultati sono simili ai seguenti:

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

  2. (Facoltativo) Per testare la funzione remota su un set di dati pubblico, inserisci il seguente e poi fai clic su Esegui. Per limitare i risultati restituiti, usa la clausola LIMIT.

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

    I risultati sono simili ai seguenti:

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

Elimina le risorse

Se non prevedi di utilizzare queste funzioni in questo progetto, puoi evitare costi aggiuntivi eliminando il progetto. Questa azione eliminerà definitivamente tutti associate al progetto.

  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.

Passaggi successivi