Tutorial sulle funzioni remote e sull'API Translation

Puoi combinare le funzioni remote di BigQuery con l'API Cloud Translation per eseguire la traduzione dei contenuti da qualsiasi lingua direttamente utilizzando SQL e Python. La traduzione dei dati all'interno di BigQuery ti consente di tradurre i commenti degli utenti del sito web o di consolidare le richieste di assistenza multilingue in una lingua comune per i tuoi operatori.

Obiettivi

• Assegna i ruoli necessari al tuo account.
• Crea una funzione Cloud Run Functions.
• Creare un set di dati BigQuery.
• Crea una connessione BigQuery e account di servizio.
• Concedi le autorizzazioni al account di servizio BigQuery.
• Crea una funzione remota BigQuery.
• Chiama la funzione remota di BigQuery.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

• BigQuery
• Cloud Run functions
• Cloud Translation

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova senza costi.

Prima di iniziare

Ti consigliamo di creare un progetto Google Cloud per questo tutorial. Inoltre, assicurati di disporre dei ruoli richiesti per completare questo tutorial.

Configura un progetto Google Cloud

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

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

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 role (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, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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 role (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, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Ruoli obbligatori per il tuo account

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

• BigQuery Data Owner (roles/bigquery.dataOwner)
• BigQuery Connection Admin (roles/bigquery.connectionAdmin)
• Cloud Functions Developer (roles/cloudfunctions.developer)

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

Questi ruoli predefiniti contengono le autorizzazioni necessarie per eseguire le attività di questo tutorial. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

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

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

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Ruoli obbligatori per il account di servizio predefinito di Compute Engine

Quando hai abilitato l'API per Cloud Run Functions, è stato creato un service account predefinito di Compute Engine. Per completare questo tutorial, devi assegnare a questo account di servizio predefinito il ruolo Utente API Cloud Translation.

1. Recupera l'ID assegnato al progetto.

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

   [e-mail]
   

   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, quindi nel campo Nuove entità, incolla il 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.

Crea una funzione Cloud Run Functions

Utilizzando Cloud Run Functions, crea una funzione che traduca il testo di input in spagnolo.

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

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

   • In Numero massimo di istanze, inserisci 10.

     Questa impostazione si trova nella sezione Impostazioni di runtime, build, connessioni e sicurezza.

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

   • In Runtime, seleziona Python 3.10.

   • In Entry point, inserisci handle_translation.

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

   Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

   Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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, quindi incolla il seguente testo:

   Flask==3.1.3; python_version >= '3.9'
   functions-framework==3.9.2
   google-cloud-translate==3.18.0
   Werkzeug==3.1.9; python_version >= '3.10'
   

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

5. Fai clic sulla scheda Trigger.

6. Copia il valore di Trigger URL (URL trigger) e salvalo per un secondo momento. Devi utilizzare questo URL quando crei una funzione remota di 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.
• Per Tipo di località, seleziona Multiregione.
• Per Multi-regione, seleziona Stati Uniti (più regioni negli Stati Uniti).

Crea una connessione BigQuery e account di servizio

Crea una connessione BigQuery in modo da poter implementare una funzione remota con qualsiasi linguaggio supportato in Cloud Run Functions e 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:

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

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

3. Copia l'ID del account di servizio e salvalo per utilizzarlo in un secondo momento. Nel passaggio successivo, devi concedere le autorizzazioni a questo ID.

Concedi le autorizzazioni al account di servizio BigQuery

Il account di servizio creato nel passaggio precedente deve disporre dell'autorizzazione per utilizzare Cloud Run in modo che la funzione remota di BigQuery possa utilizzare la funzione Cloud Run Functions. Per concedere le autorizzazioni al 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 del account di servizio che hai copiato in precedenza.

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

7. Fai clic su Salva.

Nota: l'applicazione delle nuove autorizzazioni può richiedere fino a un minuto.

Crea una funzione remota BigQuery

Per utilizzare la funzione Cloud Run Functions che traduce il testo in spagnolo con una funzione remota di 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 del trigger che hai salvato in precedenza durante la creazione di una funzione Cloud Run Functions.

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.
   

Nota: per limitare il numero di righe incluse in una richiesta HTTP, l'opzione max_batching_rows è impostata su 10. Se non specifichi l'opzione max_batching_rows, BigQuery decide quante righe includere in una richiesta HTTP.

Chiama la funzione remota di BigQuery

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

1. Nell'editor di query di BigQuery, inserisci la query seguente e poi 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 la seguente query e fai clic su Esegui. Per limitare i risultati restituiti, utilizza 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. In questo modo, tutte le risorse associate al progetto vengono eliminate definitivamente.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per, le attività descritte in questo documento, eliminerai anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

1. Nella console Google Cloud , vai alla pagina Gestisci risorse.

   Vai a Gestisci risorse

2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
3. Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.

Passaggi successivi

• Scopri come utilizzare le funzioni remote in BigQuery.
• Scopri di più sulla traduzione.
• Scopri di più su Cloud Run Functions.
• Scopri di più su Cloud Run.