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.
  • Criar uma função do Cloud Functions.
  • Criar 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:

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. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

  2. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  4. Ative as APIs BigQuery, BigQuery Connection, Cloud Translation, Cloud Functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry e Administrador do Cloud Run.

    Ative as APIs

    5.

  5. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  6. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  7. Ative as APIs BigQuery, BigQuery Connection, Cloud Translation, Cloud Functions, Cloud Build, Cloud Logging, Cloud Pub/Sub, Artifact Registry e Administrador do Cloud Run.

    Ative as APIs

    8.

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:

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

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 papéis personalizados 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 o Cloud Functions, 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:

    PROJECT_NUMBER[email protected]

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

Criar uma função do Cloud Functions

Usando o Cloud Functions, crie uma função que traduza o texto de entrada em espanhol.

  1. Crie uma função do Cloud Functions 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.11.1
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 no Cloud Functions 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 do Cloud Functions. 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 Save.

Criar uma função remota do BigQuery

Para usar a função do Cloud Functions 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 do Cloud Functions.

  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.

Chamar a função remota do BigQuery

Depois de criar a função remota, teste se ela está vinculada à função do Cloud Functions 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.

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

    Acessar "Gerenciar recursos"

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
  3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

A seguir