Tutorial de funções remotas e API Translation

Neste tutorial, descrevemos como criar uma função remota do BigQuery, invocar a API Cloud Translation e realizar a tradução de conteúdo de qualquer idioma para o espanhol usando SQL e Python.

Os casos de uso dessa função incluem o seguinte:

• Traduzir comentários de usuários em um site para um idioma local
• Traduzir solicitações de suporte de vários idiomas para um comum para workers do caso de suporte

Objetivos

• Atribuir as funções necessárias à sua conta.
• Crie uma função das funções do Cloud Run.
• Crie um conjunto de dados do BigQuery.
• Criar uma conexão e uma conta de serviço do BigQuery.
• Conceder permissões à conta de serviço do BigQuery.
• Criar uma função remota do BigQuery.
• Chamar a função remota do BigQuery.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

• BigQuery
• Cloud Run functions
• Cloud Translation

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Antes de começar

Recomendamos que você crie um projeto do Google Cloud para este tutorial. Além disso, verifique se você tem os papéis necessários para concluir este tutorial.

Configure um projeto do Google Cloud

Para configurar um projeto do Google Cloud para este tutorial, conclua estas etapas:

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

   Enable the APIs

Papéis necessários para sua conta

Para receber as permissões necessárias para executar as tarefas neste tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

• Proprietário de dados do BigQuery (roles/bigquery.dataOwner)
• Administrador de conexão do BigQuery (roles/bigquery.connectionAdmin)
• Desenvolvedor do Cloud Functions (roles/cloudfunctions.developer)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para executar as tarefas neste tutorial. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para executar as tarefas deste tutorial:

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

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Papéis necessários para a conta de serviço padrão do Compute Engine

Quando você ativa a API para as funções do Cloud Run, uma conta de serviço padrão do Compute Engine é criada. Para concluir este tutorial, conceda a essa conta de serviço padrão o papel de usuário da API Cloud Translation.

1. Receba o código atribuído ao projeto.

2. Copie a conta de serviço padrão do Compute Engine. A conta de serviço padrão é assim:

   [e-mail]
   

   Substitua PROJECT_NUMBER pela ID do seu projeto.

3. No console do Google Cloud, abra a página IAM.

   Acesse IAM

4. Selecione o projeto.

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

6. Na lista Atribuir papéis, pesquise e selecione Usuário da API Cloud Translation.

7. Clique em Salvar.

Criar uma função das funções do Cloud Run

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

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

   • Em Ambiente, selecione segunda geração.
   • Em Nome da função, insira translation-handler.
   • Em Região, selecione us-central1.

   • Em Número máximo de instâncias, insira 10.

     Essa configuração está na seção Ambiente de execução, build, conexões e configurações de segurança.

     Neste tutorial, usamos um valor menor que o padrão para controlar a taxa de solicitação enviada ao Translation.

   • Em Ambiente de execução, selecione Python 3.10.

   • Em Ponto de entrada, digite handle_translation.

2. Na lista de arquivos, selecione main.py e cole o código a seguir.

   Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

   Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar 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]
   
   

   Atualizar <your location> com us-central1.

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

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

4. Clique em Implantar e aguarde a implantação da função.

5. Clique na guia Acionador.

6. Copie e salve o valor de URL do acionador para uso posterior. Use esse URL ao criar uma função remota do BigQuery.

Criar um conjunto de dados do BigQuery

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

• Para o código do conjunto de dados, insira remote_function_test.
• Em Tipo de local, selecione Multirregional.
• Em Multirregião, selecione EUA (várias regiões nos Estados Unidos).

Criar uma conexão e uma conta de serviço do BigQuery

Crie uma conexão do BigQuery para implementar uma função remota com qualquer linguagem compatível nas funções do Cloud Run e no Cloud Run. Ao criar uma conexão, é criada uma conta de serviço para ela.

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

   • Em Tipo de conexão, selecione BigLake e funções remotas (Cloud Resource).
   • Em ID da conexão, insira remote-function-connection.
   • Em Tipo de local, selecione Multirregional.
   • Em Multirregião, selecione EUA (várias regiões nos Estados Unidos).

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

3. Copie o ID da conta de serviço e salve-o para mais tarde. É necessário conceder permissões a esse ID na próxima etapa.

Conceder permissões à conta de serviço do BigQuery

A conta de serviço que você criou na etapa anterior precisa de permissão para usar o Cloud Run. Assim, a função remota do BigQuery pode usar a função das funções do Cloud Run. Para conceder permissões à conta de serviço, siga estas etapas:

1. Acessar a página Cloud Run

   Acesse o Cloud Run

2. Selecione o projeto.

3. Marque a caixa de seleção ao lado de translation-handler.

4. No painel Permissões, clique em Adicionar participantes.

5. No campo Novos principais, digite o ID da conta de serviço que você copiou anteriormente.

6. Na lista Atribuir papéis, pesquise e selecione Invocador do Cloud Run.

7. Clique em Salvar.

Observação: pode levar até um minuto para que as novas permissões entrem em vigor.

Criar uma função remota do BigQuery

Para usar a função das funções do Cloud Run que traduz texto em espanhol com uma função remota do BigQuery, conclua as etapas a seguir.

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No Editor de consultas, insira 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 gatilho que você salvou anteriormente ao criar uma função das funções do Cloud Run.

3. Clique em Executar. Uma mensagem semelhante a esta será exibida:

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

Observação: para limitar o número de linhas incluídas em uma solicitação HTTP, a opção max_batching_rows está definida como 10. Quando você não especifica a opção max_batching_rows, o BigQuery decide quantas linhas são incluídas em uma solicitação HTTP.

Chamar a função remota do BigQuery

Depois de criar a função remota, teste se ela está vinculada à função das funções do Cloud Run e produz os resultados esperados em espanhol.

1. No editor de consultas do BigQuery, insira a consulta a seguir e clique em Executar.

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

   Os resultados são semelhantes às seguintes:

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

2. Opcional: para testar a função remota em um conjunto de dados público, insira a consulta a seguir e clique em Executar. Para limitar os resultados retornados, 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 às 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.           |
   +---------------------------------------------------------------------------+
   

Excluir os recursos

Se você não pretende usar essas funções neste projeto, exclua seu projeto para evitar custos adicionais. Isso exclui permanentemente todos os recursos associados ao projeto.

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

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.

A seguir

• Saiba como usar as 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.