Procesamiento en segundo plano con Go

Muchas apps necesitan procesar en segundo plano fuera del contexto de una solicitud web. En este instructivo, se crea una app web que permite a los usuarios ingresar texto para traducir y, luego, muestra una lista de traducciones anteriores. La traducción se realiza en segundo plano para evitar que se bloquee la solicitud del usuario.

En el siguiente diagrama se ilustra el proceso de solicitud de traducción.

Diagrama de la arquitectura

Esta es la secuencia de eventos de cómo funciona la app del instructivo:

  1. Visita la página web para ver una lista de traducciones anteriores almacenadas en Firestore.
  2. Ingresa un formulario HTML para solicitar una traducción de texto.
  3. La solicitud de traducción se publica en Pub/Sub.
  4. Se activa una función de Cloud Functions suscrita a ese tema de Pub/Sub.
  5. La función de Cloud Functions usa Cloud Translation para traducir el texto.
  6. Esta función almacena el resultado en Firestore.

Este instructivo está dirigido a cualquier persona que desee aprender sobre el procesamiento en segundo plano con Google Cloud. No se requiere experiencia previa en el uso de Pub/Sub, Firestore, App Engine o Cloud Functions. Sin embargo, para comprender el código completo, resulta útil contar con cierta experiencia en Go, JavaScript y HTML.

Objetivos

  • Comprender y también implementar una función de Cloud Functions
  • Comprender y también implementar una app de App Engine
  • Probar la app

Costos

En este instructivo, se usan los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud sean aptos para obtener una prueba gratuita.

Cuando finalices este instructivo, podrás borrar los recursos creados para evitar que se te siga facturando. Para obtener más información, consulta cómo hacer una limpieza.

Antes de comenzar

  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. En la página de selección de proyectos de Cloud Console, selecciona o crea un proyecto de Cloud.

    Ir a la página Selector de proyectos

  3. Comprueba que la facturación esté habilitada en tu proyecto.

    Descubre cómo puedes habilitar la facturación

  4. Habilita las API de Firestore, Cloud Functions, Pub/Sub, and Cloud Translation.

    Habilita las API

  5. En Google Cloud Console, abre la app en Cloud Shell.

    Ir a Cloud Shell

    Cloud Shell brinda acceso de línea de comandos a los recursos en la nube directamente desde el navegador. Abre Cloud Shell en el navegador y haz clic en Continuar para descargar el código de muestra y pasar al directorio de la app.

  6. En Cloud Shell, usa el siguiente comando para configurar la herramienta de gcloud a fin de que use tu proyecto de Google Cloud:
    # Configure gcloud for your project
    gcloud config set project YOUR_PROJECT_ID

Comprende la función de Cloud Functions

  • Primero, la función importa varias dependencias, como Firestore y Translation. También tiene algunos tipos y variables globales.
    
    // Package background contains a Cloud Function to translate text.
    // The function listens to Pub/Sub, does the translations, and stores the
    // result in Firestore.
    package background
    
    import (
    	"context"
    	"crypto/sha512"
    	"encoding/base64"
    	"encoding/json"
    	"fmt"
    	"os"
    	"strings"
    
    	"cloud.google.com/go/firestore"
    	"cloud.google.com/go/translate"
    	"golang.org/x/text/language"
    	"google.golang.org/grpc/codes"
    	"google.golang.org/grpc/status"
    )
    
    // A Translation contains the original and translated text.
    type Translation struct {
    	Original         string `json:"original"`
    	Translated       string `json:"translated"`
    	OriginalLanguage string `json:"original_language"`
    	Language         string `json:"language"`
    }
    
    // Clients reused between function invocations.
    var (
    	translateClient *translate.Client
    	firestoreClient *firestore.Client
    )
    
    // PubSubMessage is the payload of a Pub/Sub event.
    // See https://cloud.google.com/functions/docs/calling/pubsub.
    type PubSubMessage struct {
    	Data []byte `json:"data"`
    }
    
  • Los clientes globales de Firestore y Translation se inicializan para que puedan reutilizarse entre las invocaciones de funciones. De esta manera, no es necesario inicializar a los clientes nuevos en cada invocación de funciones, lo que ralentizaría la ejecución.
    
    // initializeClients creates translateClient and firestoreClient if they haven't
    // been created yet.
    func initializeClients() error {
    	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
    	if projectID == "" {
    		return fmt.Errorf("GOOGLE_CLOUD_PROJECT must be set")
    	}
    
    	if translateClient == nil {
    		// Pre-declare err to avoid shadowing translateClient.
    		var err error
    		// Use context.Background() so the client can be reused.
    		translateClient, err = translate.NewClient(context.Background())
    		if err != nil {
    			return fmt.Errorf("translate.NewClient: %v", err)
    		}
    	}
    	if firestoreClient == nil {
    		// Pre-declare err to avoid shadowing firestoreClient.
    		var err error
    		// Use context.Background() so the client can be reused.
    		firestoreClient, err = firestore.NewClient(context.Background(), projectID)
    		if err != nil {
    			return fmt.Errorf("firestore.NewClient: %v", err)
    		}
    	}
    	return nil
    }
    
  • La API de Translation traduce la string al idioma que seleccionaste.
    
    // translateString translates text to lang, returning:
    // * the translated text,
    // * the automatically detected source language, and
    // * an error.
    func translateString(ctx context.Context, text string, lang string) (translated string, originalLang string, err error) {
    	l, err := language.Parse(lang)
    	if err != nil {
    		return "", "", fmt.Errorf("language.Parse: %v", err)
    	}
    
    	outs, err := translateClient.Translate(ctx, []string{text}, l, nil)
    	if err != nil {
    		return "", "", fmt.Errorf("Translate: %v", err)
    	}
    
    	if len(outs) < 1 {
    		return "", "", fmt.Errorf("Translate got %d translations, need at least 1", len(outs))
    	}
    
    	return outs[0].Text, outs[0].Source.String(), nil
    }
    
  • La función de Cloud Functions comienza con la inicialización de los clientes de Firestore y Pub/Sub. Luego, analiza el mensaje de Pub/Sub para captar el texto que se traducirá y el idioma objetivo deseado.

    Después la app asigna un nombre único para la solicitud de traducción a fin de garantizar que no se almacenen traducciones duplicadas. Luego, realiza la traducción en una transacción de Firestore para garantizar que, durante las ejecuciones simultáneas, no ejecute la misma traducción dos veces por accidente.

    
    // Translate translates the given message and stores the result in Firestore.
    func Translate(ctx context.Context, m PubSubMessage) error {
    	initializeClients()
    
    	t := Translation{}
    	if err := json.Unmarshal(m.Data, &t); err != nil {
    		return fmt.Errorf("json.Unmarshal: %v", err)
    	}
    
    	// Use a unique document name to prevent duplicate translations.
    	key := fmt.Sprintf("%s/%s", t.Language, t.Original)
    	sum := sha512.Sum512([]byte(key))
    	// Base64 encode the sum to make a nice string. The [:] converts the byte
    	// array to a byte slice.
    	docName := base64.StdEncoding.EncodeToString(sum[:])
    	// The document name cannot contain "/".
    	docName = strings.Replace(docName, "/", "-", -1)
    	ref := firestoreClient.Collection("translations").Doc(docName)
    
    	// Run in a transation to prevent concurrent duplicate translations.
    	err := firestoreClient.RunTransaction(ctx, func(ctx context.Context, tx *firestore.Transaction) error {
    		doc, err := tx.Get(ref)
    		if err != nil && status.Code(err) != codes.NotFound {
    			return fmt.Errorf("Get: %v", err)
    		}
    		// Do nothing if the document already exists.
    		if doc.Exists() {
    			return nil
    		}
    
    		translated, originalLang, err := translateString(ctx, t.Original, t.Language)
    		if err != nil {
    			return fmt.Errorf("translateString: %v", err)
    		}
    		t.Translated = translated
    		t.OriginalLanguage = originalLang
    
    		if err := tx.Set(ref, t); err != nil {
    			return fmt.Errorf("Set: %v", err)
    		}
    		return nil
    	})
    
    	if err != nil {
    		return fmt.Errorf("RunTransaction: %v", err)
    	}
    	return nil
    }
    

Implementa la función de Cloud Functions

  • En Cloud Shell, en el directorio en el que está el archivo translate.go, implementa la función de Cloud Functions con un activador de Pub/Sub:

    gcloud functions deploy Translate --runtime go111 \
    --trigger-topic=translate --set-env-vars GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_CLOUD_PROJECT
    

    En el ejemplo anterior, YOUR_GOOGLE_CLOUD_PROJECT es el ID del proyecto de Google Cloud.

Conoce la app

La app web tiene dos componentes principales:

  • Un servidor HTTP de Go para procesar solicitudes web. El servidor tiene los siguientes dos extremos:
    • /: enumera todas las traducciones existentes y un formulario que pueden enviar los usuarios para solicitar traducciones nuevas.
    • /request-translation: los formularios se envían a este extremo, que publica la solicitud en Pub/Sub para que se traduzca de manera asíncrona.
  • Una plantilla HTML que el servidor de Go completa con las traducciones existentes.

El servidor HTTP

  • En el directorio index, main.go primero configura la app y registra los controladores de HTTP:

    
    // Command index is an HTTP app that displays all previous translations
    // (stored in Firestore) and has a form to request new translations. On form
    // submission, the request is sent to Pub/Sub to be processed in the background.
    package main
    
    import (
    	"context"
    	"encoding/json"
    	"fmt"
    	"html/template"
    	"log"
    	"net/http"
    	"os"
    	"path/filepath"
    
    	"cloud.google.com/go/firestore"
    	"cloud.google.com/go/pubsub"
    	"github.com/GoogleCloudPlatform/golang-samples/getting-started/background"
    )
    
    // topicName is the Pub/Sub topic to publish requests to. The Cloud Function to
    // process translation requests should be subscribed to this topic.
    const topicName = "translate"
    
    // An app holds the clients and parsed templates that can be reused between
    // requests.
    type app struct {
    	pubsubClient    *pubsub.Client
    	pubsubTopic     *pubsub.Topic
    	firestoreClient *firestore.Client
    	tmpl            *template.Template
    }
    
    func main() {
    	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
    	if projectID == "" {
    		log.Fatalf("GOOGLE_CLOUD_PROJECT must be set")
    	}
    
    	a, err := newApp(projectID, "index")
    	if err != nil {
    		log.Fatalf("newApp: %v", err)
    	}
    
    	http.HandleFunc("/", a.index)
    	http.HandleFunc("/request-translation", a.requestTranslation)
    
    	port := os.Getenv("PORT")
    	if port == "" {
    		port = "8080"
    	}
    
    	log.Printf("Listening on localhost:%v", port)
    	if err := http.ListenAndServe(":"+port, nil); err != nil {
    		log.Fatal(err)
    	}
    }
    
    // newApp creates a new app.
    func newApp(projectID, templateDir string) (*app, error) {
    	ctx := context.Background()
    
    	pubsubClient, err := pubsub.NewClient(ctx, projectID)
    	if err != nil {
    		return nil, fmt.Errorf("pubsub.NewClient: %v", err)
    	}
    
    	pubsubTopic := pubsubClient.Topic(topicName)
    
    	firestoreClient, err := firestore.NewClient(ctx, projectID)
    	if err != nil {
    		return nil, fmt.Errorf("firestore.NewClient: %v", err)
    	}
    
    	// Template referenced relative to the module/app root.
    	tmpl, err := template.ParseFiles(filepath.Join(templateDir, "index.html"))
    	if err != nil {
    		return nil, fmt.Errorf("template.New: %v", err)
    	}
    
    	return &app{
    		pubsubClient: pubsubClient,
    		pubsubTopic:  pubsubTopic,
    
    		firestoreClient: firestoreClient,
    		tmpl:            tmpl,
    	}, nil
    }
    
  • El controlador de índices (/) accede a todas las traducciones existentes de Firestore y completa una plantilla HTML con la lista:

    
    // index lists the current translations.
    func (a *app) index(w http.ResponseWriter, r *http.Request) {
    	docs, err := a.firestoreClient.Collection("translations").Documents(r.Context()).GetAll()
    	if err != nil {
    		log.Printf("GetAll: %v", err)
    		http.Error(w, fmt.Sprintf("Error getting translations: %v", err), http.StatusInternalServerError)
    		return
    	}
    
    	var translations []background.Translation
    	for _, d := range docs {
    		t := background.Translation{}
    		if err := d.DataTo(&t); err != nil {
    			log.Printf("DataTo: %v", err)
    			http.Error(w, "Error reading translations", http.StatusInternalServerError)
    			return
    		}
    		translations = append(translations, t)
    	}
    
    	if err := a.tmpl.Execute(w, translations); err != nil {
    		log.Printf("tmpl.Execute: %v", err)
    		http.Error(w, "Error writing response", http.StatusInternalServerError)
    		return
    	}
    }
    
  • Para solicitar una traducción nueva, se debe enviar un formulario HTML. El controlador de solicitudes de traducción, registrado en /request-translation, analiza el envío del formulario, valida la solicitud y publica un mensaje en Pub/Sub:

    
    // requestTranslation parses the request, validates it, and sends it to Pub/Sub.
    func (a *app) requestTranslation(w http.ResponseWriter, r *http.Request) {
    	if err := r.ParseForm(); err != nil {
    		log.Printf("ParseForm: %v", err)
    		http.Error(w, "Bad request", http.StatusBadRequest)
    		return
    	}
    	v := r.PostFormValue("v")
    	if v == "" {
    		log.Printf("Empty value")
    		http.Error(w, "Empty value", http.StatusBadRequest)
    		return
    	}
    	acceptableLanguages := map[string]bool{
    		"de": true,
    		"en": true,
    		"es": true,
    		"fr": true,
    		"ja": true,
    		"sw": true,
    	}
    	lang := r.PostFormValue("lang")
    	if !acceptableLanguages[lang] {
    		log.Printf("Unsupported language: %v", lang)
    		http.Error(w, fmt.Sprintf("Unsupported language: %v", lang), http.StatusBadRequest)
    		return
    	}
    
    	log.Printf("Translation requested: %q -> %s", v, lang)
    
    	t := background.Translation{
    		Original: v,
    		Language: lang,
    	}
    	msg, err := json.Marshal(t)
    	if err != nil {
    		log.Printf("json.Marshal: %v", err)
    		http.Error(w, "Error requesting translation", http.StatusInternalServerError)
    		return
    	}
    
    	res := a.pubsubTopic.Publish(r.Context(), &pubsub.Message{Data: msg})
    	if _, err := res.Get(r.Context()); err != nil {
    		log.Printf("Publish.Get: %v", err)
    		http.Error(w, "Error requesting translation", http.StatusInternalServerError)
    		return
    	}
    }
    

La plantilla HTML

La plantilla HTML es la base de la página HTML que se muestra al usuario para que pueda ver las traducciones anteriores y solicitar otras nuevas. El servidor HTTP completa la plantilla con la lista de las traducciones existentes.

  • El elemento <head> de la plantilla HTML incluye metadatos, hojas de estilo y JavaScript para la página:
    <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>

    La página extrae elementos de JavaScript y CSS de Material Design Lite (MDL). MDL te permite dar un estilo de Material Design a los sitios web.

    En la página, se usa JQuery para establecer un controlador de envío de formularios una vez que el documento termina de cargarse. Cuando se envía el formulario de solicitud de traducción, la página realiza una validación mínima para comprobar que el valor no esté vacío y envía una solicitud asíncrona al extremo /request-translation.

    Por último, aparece una barra de notificaciones de MDL para indicar si la solicitud se realizó de forma correcta o si se experimentó un error.

  • En el cuerpo HTML de la página, se usa un diseño de MDL y varios componentes de MDL a fin de mostrar una lista de las traducciones y un formulario para solicitar traducciones adicionales:
    <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>
                                    {{range .}}
                                    <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">{{ .OriginalLanguage }} </span>
                                            </span>
                                        {{ .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">{{ .Language }} </span>
                                            </span>
                                            {{ .Translated }}
                                        </td>
                                    </tr>
                                    {{end}}
                                </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>

Compila la app

  • Antes de implementar la app web, debes compilarla para comprobar que no haya ningún problema con la compilación y que funcionan todas las dependencias.
    go build -o start ./index
    

    La compilación se realiza de forma correcta si no se imprime nada y se crea un archivo start.

Implementa la app web

Puedes usar el entorno estándar de App Engine para compilar y, luego, implementar una app que se ejecute de forma confiable incluso con cargas pesadas y grandes cantidades de datos.

En este instructivo, se usa el entorno estándar de App Engine para implementar el frontend de HTTP.

El app.yaml configura la app de App Engine:

runtime: go111
main: index
  • Desde el mismo directorio del archivo app.yaml, implementa la app en el entorno estándar de App Engine:
    gcloud app deploy

Prueba la app

Después de implementar la función de Cloud Functions y la app de App Engine, solicita una traducción.

  1. Para ver la app en el navegador, ingresa la siguiente URL:

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

    Reemplaza los siguientes elementos:

    Hay una página con una lista vacía de traducciones y un formulario para solicitar traducciones nuevas.

  2. En el campo Texto para traducir, ingresa el texto que desees traducir, por ejemplo, Hello, World.
  3. En la lista desplegable, selecciona el idioma al que desees que el texto se traduzca.
  4. Haga clic en Enviar.
  5. Para actualizar la página, haz clic en Actualizar . Aparece una fila nueva en la lista de traducciones. Si no ves la traducción, espera unos segundos y vuelve a intentarlo. Si la traducción sigue sin aparecer, consulta la siguiente sección sobre cómo depurar la app.

Depura la app

Si no puedes conectarte a la app de App Engine o no ves las traducciones nuevas, comprueba lo siguiente:

  1. Comprueba que los comandos de implementación de gcloud se hayan ejecutado de forma correcta y no hayan generado ningún error. Si hubo errores, corrígelos y, luego, vuelve a implementar la función de Cloud Functions y la app de App Engine.
  2. En Google Cloud Console, ve a la página Visor de registros.

    Ir a la página Visor de registros
    1. En la lista desplegable Recursos seleccionados recientemente, haz clic en Aplicación de GAE y, luego, en Todos los module_id. Verás una lista de las solicitudes de cuando visitaste la app. Si no la ves, asegúrate de haber seleccionado Todos los module_id en la lista desplegable. Si ves mensajes de error impresos en Cloud Console, comprueba que el código de la app coincida con el código de la sección para comprender la app web.
    2. En la lista desplegable Últimos recursos seleccionados, haz clic en Función de Cloud Functions y, luego, en Nombres de las funciones. Verás una función para cada traducción solicitada. Si esto no sucede, comprueba que la función de Cloud Functions y la app de App Engine usen el mismo tema de Pub/Sub:

Limpia

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud Platform por los recursos que usaste en este instructivo:

Borra el proyecto de Cloud

  1. En Cloud Console, ve a la página Administrar recursos.

    Ir a la página Administrar recursos

  2. En la lista de proyectos, selecciona el proyecto que deseas borrar y haz clic en Borrar .
  3. En el cuadro de diálogo, escribe el ID del proyecto y haz clic en Cerrar para borrar el proyecto.

Borra la instancia de App Engine

  1. En Cloud Console, ve a la página Versiones de App Engine.

    Ir a la página Versiones

  2. Selecciona la casilla de verificación de la versión no predeterminada de la app que deseas borrar.
  3. Haz clic en Borrar para borrar la versión de la app.

Borra la función de Cloud Functions

  • Borra la función de Cloud Functions que creaste en este instructivo:
    gcloud functions delete Translate

Próximos pasos