Tutorial sobre as funções remotas e a API Translation

Este tutorial descreve como criar uma função remota do BigQuery, invocar a API Cloud Translation e fazer a tradução de conteúdo de qualquer idioma para espanhol através de SQL e Python.

Seguem-se alguns exemplos de utilização desta função:

• Traduza os comentários dos utilizadores num Website para um idioma local
• Traduzir pedidos de apoio técnico de vários idiomas para um idioma comum para os operadores de apoio técnico

Objetivos

• Atribua as funções necessárias à sua conta.
• Crie uma função do Cloud Run Functions.
• Crie um conjunto de dados do BigQuery.
• Crie uma ligação do BigQuery e uma conta de serviço.
• Conceda autorizações à conta de serviço do BigQuery.
• Crie uma função remota do BigQuery.
• Chame a função remota do BigQuery.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• BigQuery
• Cloud Run functions
• Cloud Translation

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Antes de começar

Recomendamos que crie um Google Cloud projeto para este tutorial. Além disso, certifique-se de que tem as funções necessárias para concluir este tutorial.

Configure um Google Cloud projeto

Para configurar um Google Cloud projeto para este tutorial, conclua estes passos:

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

Funções necessárias para a sua conta

Para receber as autorizações de que precisa para realizar as tarefas neste tutorial, peça ao seu administrador que lhe conceda as seguintes funções da IAM no seu projeto:

• Proprietário de dados do BigQuery (roles/bigquery.dataOwner)
• Administrador da ligação do BigQuery (roles/bigquery.connectionAdmin)
• Programador de Cloud Functions (roles/cloudfunctions.developer)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Estas funções predefinidas contêm as autorizações necessárias para realizar as tarefas neste tutorial. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para realizar as tarefas neste tutorial:

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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Funções necessárias para a conta de serviço predefinida do Compute Engine

Quando ativou a API para funções do Cloud Run, foi criada uma conta de serviço predefinida do Compute Engine. Para concluir este tutorial, tem de atribuir à conta de serviço predefinida a função de utilizador da API Cloud Translation.

1. Obtenha o ID atribuído ao projeto.

2. Copie a conta de serviço predefinida do Compute Engine. A sua conta de serviço predefinida tem o seguinte aspeto:

   [e-mail]
   

   Substitua PROJECT_NUMBER pelo ID do seu projeto.

3. Na Google Cloud consola, aceda à página IAM.

   Aceda ao IAM

4. Selecione o seu projeto.

5. Clique em Conceder acesso e, de seguida, no campo Novos principais, cole a conta de serviço predefinida do Compute Engine que copiou anteriormente.

6. Na lista Atribuir funções, pesquise e selecione Utilizador da Cloud Translation API.

7. Clique em Guardar.

Crie uma função do Cloud Run Functions

Usando funções do Cloud Run, crie uma função que traduza o texto de entrada para espanhol.

1. Crie uma função das funções do Cloud Run com as seguintes especificações:

   • Para Ambiente, selecione 2.ª geração.
   • Em Nome da função, introduza translation-handler.
   • Para Região, selecione us-central1.

   • Para Número máximo de instâncias, introduza 10.

     Esta definição encontra-se na secção Definições de tempo de execução, compilação, ligações e segurança.

     Neste tutorial, usamos um valor inferior ao predefinido para controlar a taxa de pedidos enviados para o serviço de tradução.

   • Para Tempo de execução, selecione Python 3.10.

   • Para Entry point, introduza handle_translation.

2. Na lista de ficheiros, selecione main.py e, de seguida, cole o seguinte código.

   Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

   Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação 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]
   
   

   Atualize o <your location> com us-central1.

3. Na lista de ficheiros, selecione requirements.txt e, de seguida, cole o seguinte texto:

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

4. Clique em Implementar e aguarde que a função seja implementada.

5. Clique no separador Acionador.

6. Copie o valor do URL do acionador e guarde-o para mais tarde. Tem de usar este URL quando criar uma função remota do BigQuery.

Crie um conjunto de dados do BigQuery

Crie um conjunto de dados do BigQuery que vai conter a função remota. Quando criar o conjunto de dados, inclua estas especificações:

• Para o ID do conjunto de dados, introduza remote_function_test.
• Para Tipo de localização, selecione Várias regiões.
• Para Várias regiões, selecione EUA (várias regiões nos Estados Unidos).

Crie uma ligação do BigQuery e uma conta de serviço

Crie uma ligação ao BigQuery para poder implementar uma função remota com quaisquer idiomas suportados nas funções do Cloud Run e no Cloud Run. Quando cria uma associação, é criada uma conta de serviço para essa associação.

1. Crie uma Google Cloud associação de recursos com as seguintes especificações:

   • Em Tipo de ligação, selecione BigLake e funções remotas (recurso da nuvem)
   • Para o ID da ligação, introduza remote-function-connection.
   • Para Tipo de localização, selecione Várias regiões.
   • Para Várias regiões, selecione EUA (várias regiões nos Estados Unidos).

2. Abra a lista Ligações externas e selecione us.remote-function-connection.

3. Copie o ID da conta de serviço e guarde-o para mais tarde. Tem de conceder autorizações a este ID no passo seguinte.

Conceda autorizações à conta de serviço do BigQuery

A conta de serviço que criou no passo anterior precisa de autorização para usar o Cloud Run, para que a função remota do BigQuery possa usar a função de funções do Cloud Run. Para conceder autorizações à conta de serviço, conclua os passos seguintes:

1. Aceda à página Cloud Run.

   Aceda ao Cloud Run

2. Selecione o seu projeto.

3. Selecione a caixa de verificação junto a translation-handler.

4. No painel Autorizações, clique em Adicionar principal.

5. No campo Novos membros, introduza o ID da conta de serviço que copiou anteriormente.

6. Na lista Atribuir funções, pesquise e selecione Cloud Run Invoker.

7. Clique em Guardar.

Nota: pode demorar até um minuto para que as novas autorizações entrem em vigor.

Crie uma função remota do BigQuery

Para usar a função do Cloud Run que traduz texto para espanhol com uma função remota do BigQuery, conclua os seguintes passos.

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte 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);
   

   Substitua TRIGGER_URL pelo URL do acionador que guardou anteriormente quando criou uma função do Cloud Run Functions.

3. Clique em Executar. É apresentada uma mensagem semelhante à seguinte:

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

Nota: para limitar o número de linhas incluídas num pedido HTTP, a opção max_batching_rows está definida como 10 . Quando não especifica a opção max_batching_rows, o BigQuery decide quantas linhas são incluídas num pedido HTTP.

Chame a função remota do BigQuery

Depois de criar a função remota, teste-a para se certificar de que está associada à função do Cloud Run e produz os resultados esperados em espanhol.

1. No editor de consultas do BigQuery, introduza a seguinte consulta e, em seguida, clique em Executar.

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

   Os resultados são semelhantes aos seguintes:

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

2. Opcional: para testar a função remota num conjunto de dados público, introduza a seguinte consulta e, de seguida, clique em Executar. Para limitar os resultados devolvidos, use a 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);
   

   Os resultados são semelhantes aos seguintes:

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

Elimine os recursos

Se não planeia usar estas funções neste projeto, pode evitar custos adicionais eliminando o projeto. Esta ação elimina permanentemente todos os recursos associados ao projeto.

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

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.

O que se segue?

• Saiba como usar funções remotas no BigQuery.
• Saiba mais sobre a tradução.
• Saiba mais sobre as funções do Cloud Run.
• Saiba mais sobre o Cloud Run.