Esta página foi traduzida pela API Cloud Translation.

Implante uma versão básica do "Google Tradutor" App no Cloud Functions para Python 3

1. Visão geral

Esta série de codelabs (tutoriais práticos e autoguiados) tem como objetivo ajudar os desenvolvedores a entender as várias opções disponíveis ao implantar aplicativos. Neste codelab, você vai aprender a usar a API Google Cloud Translation com Python e executar localmente ou implantar em uma plataforma de computação sem servidor do Cloud (App Engine, Cloud Functions ou Cloud Run). O app de exemplo encontrado no repo do tutorial pode ser implantado de oito maneiras diferentes com apenas pequenas mudanças de configuração:

Servidor Flask local (Python 2)
Servidor Flask local (Python 3)
App Engine (Python 2)
App Engine (Python 3)
Cloud Functions (Python 3)
Cloud Run (Python 2 via Docker)
Cloud Run (Python 3 via Docker)
Cloud Run (Python 3 usando os Cloud Buildpacks)

Este codelab se concentra no provisionamento do app para as plataformas em negrito acima.

Você aprenderá como realizar as seguintes tarefas:

Use as APIs do Google Cloud, especificamente a API Cloud Translation (avançada/v3).
Executar um aplicativo da Web básico localmente ou implantar em uma plataforma de computação sem servidor do Cloud

O que é necessário

Um projeto do Google Cloud com uma conta ativa do Cloud Billing
Flask instalado para execução local ou uma plataforma de computação sem servidor do Cloud ativada para implantações baseadas na nuvem
Habilidades básicas em Python
Conhecimento prático de comandos básicos do sistema operacional

Pesquisa

Como você usará este tutorial?

Ler e fazer os exercícios

Apenas leitura

Como você classificaria sua experiência com Python?

Iniciante

Intermediário

Proficiente

Como você classificaria sua experiência de uso dos serviços do Google Cloud?

Iniciante

Intermediário

Proficiente

2. Configuração e requisitos

Configuração de ambiente autoguiada

Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

O Nome do projeto é o nome de exibição para os participantes do projeto. Ele é uma string de caracteres que não é usada pelas APIs do Google e pode ser atualizada a qualquer momento.
O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser alterado após a definição. O Console do Cloud gera automaticamente uma string única, geralmente não importa o que seja. Na maioria dos codelabs, você precisará fazer referência ao ID do projeto, que geralmente é identificado como PROJECT_ID. Então, se você não gostar dele, gere outro ID aleatório ou crie um próprio e veja se ele está disponível. Em seguida, ele fica "congelado" depois que o projeto é criado.
Há um terceiro valor, um Número de projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Em seguida, você precisará ativar o faturamento no Console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não será muito cara, se tiver algum custo. Para encerrar os recursos e não gerar cobranças além deste tutorial, siga as instruções de "limpeza" encontradas no final do codelab. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

3. Ativar a API Translation

Nesta seção, você vai aprender a ativar as APIs do Google em geral. No app de exemplo, você vai ativar a API Cloud Translation e o serviço Cloud Functions.

Introdução

Independentemente da API do Google que você quer usar no seu app, ela precisa ser ativada. O exemplo a seguir mostra duas maneiras de ativar a API Cloud Vision. Depois de aprender a ativar uma API do Cloud, você poderá ativar outras APIs porque o processo é semelhante.

Opção 1: no Cloud Shell ou na interface de linha de comando

Embora a ativação de APIs no console do Cloud seja mais comum, alguns desenvolvedores preferem fazer tudo na linha de comando. Para isso, você precisa procurar o "nome do serviço" de uma API. Ele se parece com um URL: SERVICE_NAME.googleapis.com. Confira essas informações no gráfico de produtos compatíveis ou faça uma consulta programática com a API Google Discovery.

Com essas informações, use o Cloud Shell (ou seu ambiente de desenvolvimento local com a ferramenta de linha de comando gcloud instalada) para ativar uma API da seguinte maneira:

gcloud services enable SERVICE_NAME.googleapis.com

Por exemplo, este comando ativa a API Cloud Vision:

gcloud services enable vision.googleapis.com

Esse comando ativa o App Engine:

gcloud services enable appengine.googleapis.com

Também é possível ativar várias APIs com uma solicitação. Por exemplo, esta linha de comando ativa o Cloud Run, o Cloud Artifact Registry e a API Cloud Translation:

gcloud services enable artifactregistry.googleapis.com run.googleapis.com translate.googleapis.com

Opção 2: no console do Cloud

Você também pode ativar a API Vision no Gerenciador de APIs. No console do Cloud, acesse o Gerenciador de APIs e selecione Biblioteca.

Se você quiser ativar a API Cloud Vision, comece a digitar "vision" na barra de pesquisa, e tudo que corresponder ao que você digitou até agora vai aparecer:

Selecione a API que você quer ativar e clique em Ativar:

Custo

Muitas APIs do Google podem ser usadas sem taxas, mas o uso de produtos e APIs do Google Cloud não é sem custo financeiro. Ao ativar as APIs do Cloud, você pode precisar de uma conta de faturamento ativa. No entanto, é importante observar que alguns produtos do Google Cloud têm um nível "Sempre sem custo financeiro" (diário/mensal) que você precisa exceder para incorrer em cobranças. Caso contrário, seu cartão de crédito (ou instrumento de faturamento especificado) não será cobrado.

Os usuários precisam consultar as informações de preços de qualquer API antes da ativação, especialmente se ela tem um nível sem custo financeiro e, em caso afirmativo, qual é. Se você estiver ativando a API Cloud Vision, consulte a página Informações de preços. O Cloud Vision tem uma cota sem custo financeiro, e, desde que você permaneça dentro dos limites agregados (em cada mês), não haverá cobranças.

Os preços e os níveis sem custo financeiro variam entre as APIs do Google. Exemplos:

Google Cloud/GCP: cada produto é faturado de maneira diferente e geralmente é pago por ciclo de vCPU, consumidor de armazenamento, uso de memória ou pagamento por uso. Consulte as informações do nível sem custo financeiro acima.
Google Maps: oferece um pacote de APIs e disponibiliza aos usuários um crédito mensal sem custo financeiro de US$200.
APIs do Google Workspace (antigo G Suite): oferecem uso sem custo financeiro (até determinados limites) coberto por uma taxa de assinatura mensal do Workspace. Portanto, não há cobrança direta para o uso das APIs Gmail, Google Drive, Agenda, Documentos, Planilhas e Apresentações.

Diferentes produtos do Google são cobrados de maneira diferente. Portanto, consulte a documentação da sua API para obter essa informação.

Resumo

Agora que você já sabe como ativar as APIs do Google em geral, acesse o API Manager e ative a API Cloud Translation e o serviço Cloud Functions (se ainda não tiver feito isso). O último será usado pelo nosso aplicativo, e o primeiro porque você está implantando uma função do Cloud. Se preferir fazer isso na linha de comando, emita este comando:

gcloud services enable cloudfunctions.googleapis.com translate.googleapis.com

Embora a cota mensal não esteja listada na página de resumo do nível "Sempre sem custo financeiro", a página de preços da API Translation informa que todos os usuários recebem uma quantidade fixa de caracteres traduzidos por mês. Você não vai receber cobranças da API se ficar abaixo desse limite. Se houver outras cobranças relacionadas ao Google Cloud, elas serão discutidas no final da seção "Limpeza".

4. Fazer o download do código do app de exemplo

Clone o código no repositório localmente ou no Cloud Shell (usando o comando git clone) ou faça o download do arquivo ZIP no botão verde Code, conforme mostrado na captura de tela a seguir:

Agora que você tem tudo, crie uma cópia completa da pasta para fazer este tutorial específico, porque provavelmente ele envolve a exclusão ou alteração dos arquivos. Se você quiser fazer uma implantação diferente, copie o original para não precisar clonar ou fazer o download novamente.

5. Tour do app de exemplo

O app de exemplo é um derivado simples do Google Tradutor que solicita que os usuários insiram texto em inglês e recebem a tradução equivalente desse texto em espanhol. Agora abra o arquivo main.py para conferir como ele funciona. Omitindo as linhas comentadas sobre licenciamento, a parte de cima e de baixo fica assim:

from flask import Flask, render_template, request
import google.auth
from google.cloud import translate

app = Flask(__name__)
_, PROJECT_ID = google.auth.default()
TRANSLATE = translate.TranslationServiceClient()
PARENT = 'projects/{}'.format(PROJECT_ID)
SOURCE, TARGET = ('en', 'English'), ('es', 'Spanish')

# . . . [translate() function definition] . . .

if __name__ == '__main__':
    import os
    app.run(debug=True, threaded=True, host='0.0.0.0',
            port=int(os.environ.get('PORT', 8080)))

As importações trazem a funcionalidade do Flask, o módulo google.auth e a biblioteca de cliente da API Cloud Translation.
As variáveis globais representam o app Flask, o ID do projeto do Cloud, o cliente da API Translation, o "caminho de local" pai para chamadas da API Translation e os idiomas de origem e de destino. Nesse caso, são o inglês (en) e o espanhol (es), mas você pode mudar esses valores para outros códigos de idioma compatíveis com a API Cloud Translation.
O grande bloco if na parte de baixo é usado no tutorial para executar este app localmente. Ele utiliza o servidor de desenvolvimento do Flask para disponibilizar nosso app. Esta seção também está aqui para os tutoriais de implantação do Cloud Run caso o servidor da Web não esteja incluído no contêiner. Você precisa ativar o agrupamento do servidor no contêiner, mas, caso você esqueça, o código do app volta a usar o servidor de desenvolvimento do Flask. Isso não é um problema com o App Engine ou o Cloud Functions, porque essas são plataformas baseadas em origem, ou seja, o Google Cloud fornece e executa um servidor da Web padrão.

Por fim, no meio de main.py está o coração do aplicativo, a função translate():

@app.route('/', methods=['GET', 'POST'])
def translate(gcf_request=None):
    """
    main handler - show form and possibly previous translation
    """

    # Flask Request object passed in for Cloud Functions
    # (use gcf_request for GCF but flask.request otherwise)
    local_request = gcf_request if gcf_request else request

    # reset all variables (GET)
    text = translated = None

    # if there is data to process (POST)
    if local_request.method == 'POST':
        text = local_request.form['text']
        data = {
            'contents': [text],
            'parent': PARENT,
            'target_language_code': TARGET[0],
        }
        # handle older call for backwards-compatibility
        try:
            rsp = TRANSLATE.translate_text(request=data)
        except TypeError:
            rsp = TRANSLATE.translate_text(**data)
        translated = rsp.translations[0].translated_text

    # create context & render template
    context = {
        'orig':  {'text': text, 'lc': SOURCE},
        'trans': {'text': translated, 'lc': TARGET},
    }
    return render_template('index.html', **context)

A função principal faz o trabalho de receber a entrada do usuário e chamar a API Translation para fazer o trabalho pesado. Vamos aos detalhes:

Verifique se as solicitações estão vindo do Cloud Functions usando a variável local_request. O Cloud Functions envia o próprio objeto de solicitação do Flask, enquanto todos os outros (executados localmente ou implantados no App Engine ou no Cloud Run) recebem o objeto de solicitação diretamente do Flask.
Redefina as variáveis básicas do formulário. Isso é principalmente para solicitações GET, já que as solicitações POST têm dados que substituem essas informações.
Se for um POST, pegue o texto a ser traduzido e crie uma estrutura JSON que represente o requisito de metadados da API. Em seguida, chame a API, voltando para uma versão anterior se o usuário estiver usando uma biblioteca mais antiga.
De qualquer forma, formate os resultados reais (POST) ou sem dados (GET) no contexto do modelo e renderize.

A parte visual do aplicativo está no arquivo index.html do modelo. Ele mostra os resultados traduzidos anteriormente (em branco, caso contrário) seguidos pelo formulário que pede algo para traduzir:

<!doctype html>
<html><head><title>My Google Translate 1990s</title><body>
<h2>My Google Translate (1990s edition)</h2>

{% if trans['text'] %}
    <h4>Previous translation</h4>
    <li><b>Original</b>:   {{ orig['text'] }}  (<i>{{ orig['lc'][0] }}</i>)</li>
    <li><b>Translated</b>: {{ trans['text'] }} (<i>{{ trans['lc'][0] }}</i>)</li>
{% endif %}

<h4>Enter <i>{{ orig['lc'][1] }}</i> text to translate to <i>{{ trans['lc'][1] }}</i>:</h4>
<form method="POST"><input name="text"><input type="submit"></form>
</body></html>

6. Implante o serviço

Para implantar seu serviço de tradução no Cloud Functions (Python 3), execute este comando:

gcloud functions deploy translate --runtime python37 --trigger-http --allow-unauthenticated

A saída vai ser parecida com esta e vai fornecer algumas instruções para as próximas etapas:

$ gcloud functions deploy translate --runtime python37 --trigger-http --allow-unauthenticated
Deploying function (may take a while - up to 2 minutes)...⠹
For Cloud Build Stackdriver Logs, visit: https://console.cloud.google.com/logs/viewer?project=PROJECT_ID&advancedFilter=resource.type%3Dbuild%0Aresource.labels.build_id%3D7e32429d-ec36-422c-8a8b-43c4d661a15c%0AlogName%3Dprojects%2FPROJECT_ID%2Flogs%2Fcloudbuild
Deploying function (may take a while - up to 2 minutes)...done.
availableMemoryMb: 256
buildId: 7e32429d-ec36-422c-8a8b-43c4d661a15
entryPoint: translate
httpsTrigger:
  securityLevel: SECURE_OPTIONAL
  url: https://REGION-PROJECT_ID.cloudfunctions.net/translate
ingressSettings: ALLOW_ALL
labels:
  deployment-tool: cli-gcloud
name: projects/PROJECT_ID/locations/REGION/functions/translate
runtime: python37
serviceAccountEmail: PROJECT_ID@appspot.gserviceaccount.com
sourceUploadUrl: https://storage.googleapis.com/gcf-upload-REGION-873f8448-838f-4eb2-beda-3e200a1420d/cb1cbdca-34eb-41d0-88d6-c276d5205fb.zip?GoogleAccessId=service-104690130103@gcf-admin-robot.iam.gserviceaccount.com&Expires=1619139674
status: ACTIVE
timeout: 60s
updateTime: '2021-04-23T00:32:58.065Z'
versionId: '3'

Agora que o app está disponível em todo o mundo, ele pode ser acessado no URL que contém o ID do projeto, conforme mostrado na saída da implantação. O URL deve ser parecido com este: https://REGION-PROJECT_ID.cloudfunctions.net/translate, que varia de acordo com a região selecionada e o ID do projeto do Cloud.

Tradução de algo para ver como funciona.

7. Conclusão

Parabéns! Você aprendeu a ativar a API Cloud Translation, receber as credenciais necessárias e implantar um app da Web simples no Cloud Functions. Saiba mais sobre essa implantação nesta tabela no repositório.

Limpar

A API Cloud Translation permite executar um volume fixo de caracteres traduzidos por mês sem custo. O App Engine também tem uma cota sem custo financeiro, assim como o Cloud Functions e o Cloud Run. Você vai receber cobranças se exceder um dos limites. Se você planeja continuar para o próximo codelab, não é necessário encerrar o app.

No entanto, se você ainda não estiver pronto para passar para o próximo tutorial ou se estiver preocupado com a possibilidade de a Internet descobrir o app que você acabou de implantar, desative o app do App Engine, exclua o Cloud Function ou desative o serviço do Cloud Run para evitar cobranças. Quando estiver pronto para passar para o próximo codelab, você poderá reativá-lo. Por outro lado, se você não quiser continuar com este aplicativo ou outros codelabs e quiser excluir tudo completamente, encerrar o projeto.

Além disso, a implantação em uma plataforma de computação sem servidor do Google Cloud gera custos de criação e armazenamento menores. O Cloud Build tem uma cota sem custo financeiro, assim como o Cloud Storage. Para maior transparência, o Cloud Build cria a imagem do aplicativo, que é armazenada no Cloud Container Registry ou no Artifact Registry, seu sucessor. O armazenamento dessa imagem usa parte dessa cota, assim como a saída de rede ao transferir essa imagem para o serviço. No entanto, talvez você more em uma região que não tem esse nível sem custo financeiro. Portanto, fique atento ao uso de armazenamento para minimizar os custos.

8. Outros recursos

Nas seções a seguir, você encontra mais material de leitura e exercícios recomendados para ampliar o conhecimento adquirido com a conclusão deste tutorial.

Outro estudo

Agora que você já tem alguma experiência com a API Translation, vamos fazer alguns exercícios para desenvolver ainda mais suas habilidades. Para continuar seu aprendizado, modifique nosso app de exemplo para fazer o seguinte:

Conclua todas as outras edições deste codelab para execução local ou implantação em plataformas de computação sem servidor do Google Cloud (consulte o README do repositório).
Conclua este tutorial usando outra linguagem de programação.
Mude esse app para oferecer suporte a diferentes idiomas de origem ou de destino.
Faça upgrade do aplicativo para que ele possa traduzir texto em mais de um idioma. Mude o arquivo de modelo para ter um menu suspenso com os idiomas de destino compatíveis.

Saiba mais

Google App Engine

Google Cloud Functions

Google Cloud Run

Buildpacks do Google Cloud, Container Registry e Artifact Registry

Google Cloud Translation e Kit de ML do Google

Outros produtos/páginas do Google Cloud

Python e Flask

Flask

Licença

Este tutorial está licenciado sob a Licença Atribuição 2.0 Genérica da Creative Commons, e o código-fonte no repositório está licenciado sob a Licença Apache 2.