Processamento em segundo plano com Python

Para muitos apps, é necessário fazer o processamento em segundo plano fora do contexto de uma solicitação da Web. Este tutorial cria um app da Web que permite aos usuários inserir texto para traduzir e, em seguida, exibe uma lista de traduções anteriores. A tradução é feita em um processo em segundo plano para evitar o bloqueio da solicitação do usuário.

O diagrama a seguir ilustra o processo de solicitação da tradução.

Aqui está a sequência de eventos sobre como o tutorial do app funciona:

1. Acesse a página da Web para ver uma lista de traduções anteriores armazenadas no Firestore.
2. Solicite uma tradução de texto inserindo um formulário HTML.
3. A solicitação de tradução é publicada no Pub/Sub.
4. Uma Função do Cloud inscrita nesse tópico do Pub/Sub é acionada.
5. A Função do Cloud usa o Cloud Translation para traduzir o texto.
6. A Função do Cloud armazena o resultado no Firestore.

Este tutorial se destina a qualquer pessoa interessada em aprender sobre o processamento em segundo plano com o Google Cloud. Nenhuma experiência anterior é necessária com Pub/Sub, Firestore, App Engine ou Cloud Functions. No entanto, para entender todo o código, é útil ter experiência com Python, JavaScript e HTML.

Objetivos

• Entenda e implante uma Função do Cloud.
• Entenda e implante um aplicativo do App Engine.
• Testar o app.

Custos

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

• App Engine
• Cloud Functions
• Firestore
• Pub/Sub
• 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.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

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. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

4. Enable the Firestore, Cloud Functions, Pub/Sub, and Cloud Translation 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. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

7. Enable the Firestore, Cloud Functions, Pub/Sub, and Cloud Translation APIs.

   Enable the APIs

8. No Console do Google Cloud, abra o app no Cloud Shell.

   Acessar o Cloud Shell

   O Cloud Shell oferece acesso por linha de comando aos seus recursos de nuvem diretamente no navegador. Abra o Cloud Shell no navegador e clique em Continuar para fazer o download do código de amostra e carregá-lo no diretório de app.

9. No Cloud Shell, configure a ferramenta gcloud para usar seu projeto do Google Cloud:

   # Configure gcloud for your project
   gcloud config set project YOUR_PROJECT_ID

Noções básicas sobre a Função do Cloud

• A função começa importando várias dependências, como Firestore e Translation.
  background/function/main.py

  Ver no GitHub
  import base64
  import hashlib
  import json
  
  from google.cloud import firestore
  from google.cloud import translate_v2 as translate

• Os clientes globais do Firestore e do Translation são inicializados para que possam ser reutilizados entre invocações de função. Dessa forma, não é necessário inicializar novos clientes para cada invocação de função, o que desacelera a execução.
  background/function/main.py

  Ver no GitHub
  # Get client objects once to reuse over multiple invocations.
  xlate = translate.Client()
  db = firestore.Client()

• A API Translation traduz a string para o idioma selecionado.
  background/function/main.py

  Ver no GitHub
  def translate_string(from_string, to_language):
      """ Translates a string to a specified language.
  
      from_string - the original string before translation
  
      to_language - the language to translate to, as a two-letter code (e.g.,
          'en' for english, 'de' for german)
  
      Returns the translated string and the code for original language
      """
      result = xlate.translate(from_string, target_language=to_language)
      return result['translatedText'], result['detectedSourceLanguage']

• A Função do Cloud começa analisando a mensagem do Pub/Sub para que o texto seja traduzido e o idioma de destino desejado.

  Em seguida, a função do Cloud traduz o texto e o armazena no Firestore usando uma transação para garantir que não haja traduções duplicadas.

  background/function/main.py

  Ver no GitHub
  def document_name(message):
      """ Messages are saved in a Firestore database with document IDs generated
          from the original string and destination language. If the exact same
          translation is requested a second time, the result will overwrite the
          prior result.
  
          message - a dictionary with fields named Language and Original, and
              optionally other fields with any names
  
          Returns a unique name that is an allowed Firestore document ID
      """
      key = '{}/{}'.format(message['Language'], message['Original'])
      hashed = hashlib.sha512(key.encode()).digest()
  
      # Note that document IDs should not contain the '/' character
      name = base64.b64encode(hashed, altchars=b'+-').decode('utf-8')
      return name
  
  @firestore.transactional
  def update_database(transaction, message):
      name = document_name(message)
      doc_ref = db.collection('translations').document(document_id=name)
  
      try:
          doc_ref.get(transaction=transaction)
      except firestore.NotFound:
          return  # Don't replace an existing translation
  
      transaction.set(doc_ref, message)
  
  def translate_message(event, context):
      """ Process a pubsub message requesting a translation
      """
      message_data = base64.b64decode(event['data']).decode('utf-8')
      message = json.loads(message_data)
  
      from_string = message['Original']
      to_language = message['Language']
  
      to_string, from_language = translate_string(from_string, to_language)
  
      message['Translated'] = to_string
      message['OriginalLanguage'] = from_language
  
      transaction = db.transaction()
      update_database(transaction, message)

Como implantar o Cloud Function

• No Cloud Shell, no diretório function, implante a Função do Cloud com um acionamento do Pub/Sub:

  gcloud functions deploy Translate --runtime=python37 \
  --entry-point=translate_message --trigger-topic=translate \
  --set-env-vars GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT

  em que YOUR_GOOGLE_CLOUD_PROJECT é o ID do projeto no Google Cloud.

Noções básicas sobre o app

Há dois componentes principais para o app da Web:

• Um servidor Python HTTP para gerenciar solicitações da Web. O servidor tem os dois endpoints a seguir:
  • /: lista todas as traduções existentes e mostra um formulário que os usuários podem enviar para solicitar novas traduções.
  • /request-translation: os envios de formulários são enviados para este endpoint, que publica a solicitação para que o Pub/Sub seja traduzido de forma assíncrona.
• Um modelo HTML que é preenchido com as traduções existentes pelo servidor Python.

O servidor HTTP

• No diretório app, main.py começa importando dependências, criando um app Flask, inicializando clientes do Firestore e do Translation e definindo uma lista de idiomas compatíveis:

  background/app/main.py

  Ver no GitHub
  import json
  import os
  
  from flask import Flask, redirect, render_template, request
  from google.cloud import firestore
  from google.cloud import pubsub
  
  app = Flask(__name__)
  
  # Get client objects to reuse over multiple invocations
  db = firestore.Client()
  publisher = pubsub.PublisherClient()
  
  # Keep this list of supported languages up to date
  ACCEPTABLE_LANGUAGES = ("de", "en", "es", "fr", "ja", "sw")

• O gerenciador de índice (/) obtém todas as traduções existentes do Firestore e preenche um modelo de HTML com a lista:

  background/app/main.py

  Ver no GitHub
  @app.route("/", methods=["GET"])
  def index():
      """The home page has a list of prior translations and a form to
      ask for a new translation.
      """
  
      doc_list = []
      docs = db.collection("translations").stream()
      for doc in docs:
          doc_list.append(doc.to_dict())
  
      return render_template("index.html", translations=doc_list)
  
  

• Novas traduções são solicitadas através do envio de um formulário HTML. O gerenciador de tradução de solicitação, registrado em /request-translation, analisa o envio do formulário, valida a solicitação e publica uma mensagem no Pub/Sub:

  background/app/main.py

  Ver no GitHub
  @app.route("/request-translation", methods=["POST"])
  def translate():
      """Handle a request to translate a string (form field 'v') to a given
      language (form field 'lang'), by sending a PubSub message to a topic.
      """
      source_string = request.form.get("v", "")
      to_language = request.form.get("lang", "")
  
      if source_string == "":
          error_message = "Empty value"
          return error_message, 400
  
      if to_language not in ACCEPTABLE_LANGUAGES:
          error_message = "Unsupported language: {}".format(to_language)
          return error_message, 400
  
      message = {
          "Original": source_string,
          "Language": to_language,
          "Translated": "",
          "OriginalLanguage": "",
      }
  
      topic_name = "projects/{}/topics/{}".format(
          os.getenv("GOOGLE_CLOUD_PROJECT"), "translate"
      )
      publisher.publish(
          topic=topic_name, data=json.dumps(message).encode("utf8")
      )
      return redirect("/")
  
  

Modelo HTML

O modelo HTML é a base da página HTML exibida ao usuário para que ele possa ver as traduções anteriores e solicitar novas. O modelo é preenchido pelo servidor HTTP com a lista de traduções existentes.

• O elemento <head> do modelo HTML inclui metadados, folhas de estilo e JavaScript da página:
  background/app/templates/index.html

  Ver no GitHub
  <html>
  
  <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Translations</title>
  
      <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
      <link rel="stylesheet" href="https://code.getmdl.io/1.3.0/material.indigo-pink.min.css">
      <script defer src="https://code.getmdl.io/1.3.0/material.min.js"></script>
      <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
      <script>
          $(document).ready(function() {
              $("#translate-form").submit(function(e) {
                  e.preventDefault();
                  // Get value, make sure it's not empty.
                  if ($("#v").val() == "") {
                      return;
                  }
                  $.ajax({
                      type: "POST",
                      url: "/request-translation",
                      data: $(this).serialize(),
                      success: function(data) {
                          // Show snackbar.
                          console.log(data);
                          var notification = document.querySelector('.mdl-js-snackbar');
                          $("#snackbar").removeClass("mdl-color--red-100");
                          $("#snackbar").addClass("mdl-color--green-100");
                          notification.MaterialSnackbar.showSnackbar({
                              message: 'Translation requested'
                          });
                      },
                      error: function(data) {
                          // Show snackbar.
                          console.log("Error requesting translation");
                          var notification = document.querySelector('.mdl-js-snackbar');
                          $("#snackbar").removeClass("mdl-color--green-100");
                          $("#snackbar").addClass("mdl-color--red-100");
                          notification.MaterialSnackbar.showSnackbar({
                              message: 'Translation request failed'
                          });
                      }
                  });
              });
          });
      </script>
      <style>
          .lang {
              width: 50px;
          }
          .translate-form {
              display: inline;
          }
      </style>
  </head>

  A página extrai recursos Material Design Lite (MDL) CSS e JavaScript. A MDL permite que você adicione uma aparência Material Design aos seus sites.

  A página usa JQuery para aguardar o carregamento do documento e definir um gerenciador de envio de formulário. Sempre que o formulário de solicitação de tradução é enviado, a página faz uma validação de formulário mínima para verificar se o valor não está vazio e envia uma solicitação assíncrona ao endpoint /request-translation.

  Por fim, um snackbar MDL aparece para indicar se a solicitação foi bem-sucedida ou se encontrou um erro.

• O corpo HTML da página usa um layout MDL e vários componentes MDL para exibir uma lista de traduções e um formulário para solicitar outras traduções:
  background/app/templates/index.html

  Ver no GitHub
  <body>
      <div class="mdl-layout mdl-js-layout mdl-layout--fixed-header">
          <header class="mdl-layout__header">
              <div class="mdl-layout__header-row">
                  <!-- Title -->
                  <span class="mdl-layout-title">Translate with Background Processing</span>
              </div>
          </header>
          <main class="mdl-layout__content">
              <div class="page-content">
                  <div class="mdl-grid">
                  <div class="mdl-cell mdl-cell--1-col"></div>
                      <div class="mdl-cell mdl-cell--3-col">
                          <form id="translate-form" class="translate-form">
                              <div class="mdl-textfield mdl-js-textfield mdl-textfield--floating-label">
                                  <input class="mdl-textfield__input" type="text" id="v" name="v">
                                  <label class="mdl-textfield__label" for="v">Text to translate...</label>
                              </div>
                              <select class="mdl-textfield__input lang" name="lang">
                                  <option value="de">de</option>
                                  <option value="en">en</option>
                                  <option value="es">es</option>
                                  <option value="fr">fr</option>
                                  <option value="ja">ja</option>
                                  <option value="sw">sw</option>
                              </select>
                              <button class="mdl-button mdl-js-button mdl-button--raised mdl-button--accent" type="submit"
                                  name="submit">Submit</button>
                          </form>
                      </div>
                      <div class="mdl-cell mdl-cell--8-col">
                          <table class="mdl-data-table mdl-js-data-table mdl-shadow--2dp">
                              <thead>
                                  <tr>
                                      <th class="mdl-data-table__cell--non-numeric"><strong>Original</strong></th>
                                      <th class="mdl-data-table__cell--non-numeric"><strong>Translation</strong></th>
                                  </tr>
                              </thead>
                              <tbody>
                              {% for translation in translations %}
                                  <tr>
                                      <td class="mdl-data-table__cell--non-numeric">
                                          <span class="mdl-chip mdl-color--primary">
                                              <span class="mdl-chip__text mdl-color-text--white">{{ translation['OriginalLanguage'] }} </span>
                                          </span>
                                      {{ translation['Original'] }}
                                      </td>
                                      <td class="mdl-data-table__cell--non-numeric">
                                          <span class="mdl-chip mdl-color--accent">
                                              <span class="mdl-chip__text mdl-color-text--white">{{ translation['Language'] }} </span>
                                          </span>
                                          {{ translation['Translated'] }}
                                      </td>
                                  </tr>
                              {% endfor %}
                              </tbody>
                          </table>
                          <br/>
                          <button class="mdl-button mdl-js-button mdl-button--raised" type="button" onClick="window.location.reload();">
                              Refresh
                          </button>
                      </div>
                  </div>
              </div>
              <div aria-live="assertive" aria-atomic="true" aria-relevant="text" class="mdl-snackbar mdl-js-snackbar" id="snackbar">
                  <div class="mdl-snackbar__text mdl-color-text--black"></div>
                  <button type="button" class="mdl-snackbar__action"></button>
              </div>
          </main>
      </div>
  </body>
  
  </html>

Como implantar o app da Web

É possível usar o ambiente padrão do App Engine para criar e implantar um aplicativo que será executado de maneira confiável, sob grande carga e com uma grande quantidade de dados.

Este tutorial usa o ambiente padrão do App Engine para implantar o front-end HTTP.

O app.yaml configura o aplicativo do App Engine:

background/app/app.yaml

Ver no GitHub

runtime: python37

• No mesmo diretório do arquivo app.yaml, implante o aplicativo no ambiente padrão do App Engine:

  gcloud app deploy

Como testar o app

Depois de implantar a função do Cloud e o aplicativo do App Engine, tente solicitar uma tradução.

1. Para ver o aplicativo no navegador,digite o seguinte URL:

   https://PROJECT_ID.REGION_ID.r.appspot.com

   Substitua:

   • PROJECT_ID: é o ID do projeto do Google Cloud.
   • REGION_ID: Um código que o App Engine atribui ao seu app

   Há uma página com uma lista vazia de traduções e um formulário para solicitar novas traduções.

2. No campo Texto a ser traduzido, insira algum texto a ser traduzido, por exemplo, Hello, World.
3. Selecione o idioma na lista suspensa para o qual você quer traduzir o texto.
4. Clique em Enviar.
5. Para atualizar a página, clique em Atualizar . Há uma nova linha na lista de tradução. Se você não ver uma tradução, aguarde mais alguns segundos e tente novamente. Caso você ainda não veja uma tradução, consulte a próxima seção sobre como depurar o app.

Como depurar o aplicativo

Se você não conseguir se conectar ao seu aplicativo do App Engine ou não vir novas traduções, verifique o seguinte:

1. Verifique se os comandos de implantação gcloud foram concluídos com êxito e não geraram erros. Se houver erros, corrija-os e tente implantar o Cloud Function e o aplicativo do App Engine novamente.

2. No Console do Google Cloud, acesse a página do visualizador de registros.

   Acessar a página Visualizador de registros
   1. Na lista suspensa Recursos selecionados recentemente, clique em Aplicação do GAE e, em seguida, clique em Todos os module_id. Você verá uma lista de solicitações de quando visitou seu app. Caso contrário, verifique se você selecionou Todos os module_id na lista suspensa. Se você vir mensagens de erro impressas no Console do Cloud, verifique se o código do seu app corresponde ao código na seção sobre como entender o app.
   2. Na lista suspensa Recursos selecionados recentemente, clique em Função do Cloud e, em seguida, clique em Todos os nomes de função. Você verá uma função listada para cada tradução solicitada. Caso contrário, verifique se o app da Função do Cloud e do App Engine estão usando o mesmo tópico do Pub/Sub:
      • No arquivo background/main.py, verifique se o topic_name é "translate".
      • Quando você implantar a Função do Cloud, não se esqueça de incluir a sinalização --trigger-topic=translate.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Excluir o projeto do Cloud

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

Excluir a instância do App Engine

1. In the Google Cloud console, go to the Versions page for App Engine.

   Go to Versions

2. Select the checkbox for the non-default app version that you want to delete.
   Observação: A única maneira de excluir a versão padrão do seu aplicativo do App Engine é excluir o projeto. No entanto, é possível interromper a versão padrão no Console do Google Cloud. Isso encerra todas as instâncias associadas à versão. Você pode reiniciar essas instâncias posteriormente, se necessário.

   No ambiente padrão do App Engine, apenas será possível interromper a versão padrão se o aplicativo tiver uma escala manual ou básica.

3. Para excluir a versão do app, clique em Excluir.

Excluir a Função do Cloud

• Exclua a função do Cloud criada neste tutorial:

  gcloud functions delete Translate

A seguir

• Veja outros tutoriais do Cloud Functions.
• Saiba mais sobre o App Engine.
• Teste o Cloud Run, que permite executar contêineres sem estado em um ambiente totalmente gerenciado ou em seu próprio cluster do Google Kubernetes Engine.