Go を使用したバックグラウンド処理

多くのアプリでは、ウェブ リクエストのコンテキストの外部でバックグラウンド処理を行う必要があります。このチュートリアルでは、ユーザーが翻訳するテキストを入力した後、以前の翻訳のリストを表示するウェブアプリを作成します。翻訳は、ユーザーのリクエストをブロックしないようにバックグラウンド プロセスで行われます。

次の図は、翻訳リクエストのプロセスを示しています。

アーキテクチャの図

チュートリアル アプリが動作する際のイベントの順序は次のとおりです。

  1. ウェブページにアクセスすると、Firestore に保存されている以前の翻訳のリストが表示されます。
  2. HTML フォームに入力してテキストの翻訳をリクエストします。
  3. 翻訳リクエストは Pub/Sub にパブリッシュされます。
  4. その Pub/Sub トピックに登録されている Cloud Run 関数が起動されます。
  5. Cloud Run 関数は、Cloud Translation を使用してテキストを翻訳します。
  6. Cloud Run 関数は、その結果を Firestore に保存します。

このチュートリアルは、Google Cloud でのバックグラウンド処理の詳細に関心をお持ちの方を対象としています。Pub/Sub、Firestore、App Engine、Cloud Run 関数についての経験は必須要件ではありません。ただし、Go、JavaScript、HTML の経験をお持ちであれば、すべてのコードを理解するうえで役立ちます。

目標

  • Cloud Run 関数を理解し、デプロイする。
  • App Engine アプリを理解し、デプロイします。
  • アプリを試してみます。

費用

このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。 新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

  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.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Firestore, Cloud Run functions, Pub/Sub, and Cloud Translation APIs.

    Enable the APIs

    5.

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

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

    Enable the APIs

    8.

  8. Google Cloud Console から、Cloud Shell でアプリを開きます。

    Cloud Shell に移動

    Cloud Shell を使用すると、ブラウザからコマンドラインで直接クラウド リソースにアクセスできます。ブラウザで Cloud Shell を開き、[続行] をクリックしてサンプルコードをダウンロードし、アプリ ディレクトリに移動します。

  9. Cloud Shell で、gcloud ツールを構成して Google Cloud プロジェクトを使用します。 
    # Configure gcloud for your project
gcloud config set project YOUR_PROJECT_ID

Cloud Run 関数について

  • この関数は、Firestore や Translation のようないくつかの依存関係をインポートすることから始まります。また、この関数では、複数のグローバル変数と型が使用されます。 
    
// 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"`
}
  • グローバル Firestore クライアントと Translation クライアントは、関数呼び出し間で再利用できるように初期化されます。これにより、実行速度の低下の要因となる、関数の呼び出しごとに新しいクライアントを初期化することが必要なくなります。 
    
// 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: %w", 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: %w", err)
		}
	}
	return nil
}
  • 翻訳 API は、選択した言語に文字列を翻訳します。 
    
// 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: %w", err)
	}

	outs, err := translateClient.Translate(ctx, []string{text}, l, nil)
	if err != nil {
		return "", "", fmt.Errorf("Translate: %w", 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
}

  • Cloud Run 関数は、Firestore クライアントと Pub/Sub クライアントを初期化することにより起動します。次に、Pub/Sub メッセージを解析して、翻訳するテキストとターゲット言語を取得します。

    次に、重複した訳文が保存されないようにするために、翻訳リクエストに一意の名前を付けます。その後、同時実行によってアプリが同じ翻訳を誤って 2 回実行しないように、Firestore トランザクションで翻訳を行います。

    
// 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: %w", 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: %w", 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: %w", err)
		}
		t.Translated = translated
		t.OriginalLanguage = originalLang

		if err := tx.Set(ref, t); err != nil {
			return fmt.Errorf("Set: %w", err)
		}
		return nil
	})

	if err != nil {
		return fmt.Errorf("RunTransaction: %w", err)
	}
	return nil
}

Cloud Run 関数のデプロイ

  • Cloud Shell では、Pub/Sub トリガーを使用して translate.go ファイルと同じディレクトリに Cloud Run 関数をデプロイします。

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

    ここで YOUR_GOOGLE_CLOUD_PROJECT Google Cloud プロジェクト ID です。

アプリについて

ウェブアプリには主に次の 2 つのコンポーネントがあります。

  • ウェブ リクエストを処理するための Go HTTP サーバー。サーバーには、次の 2 つのエンドポイントがあります。
    • /: 既存のすべての翻訳を一覧表示し、ユーザーが新しい翻訳をリクエストする際に送信できるフォームを表示します。
    • /request-translation: フォーム送信はこのエンドポイントに送信され、Pub/Sub へのリクエストがパブリッシュされ、翻訳は非同期で処理されます。
  • Go サーバーによって既存の翻訳が入力された HTML テンプレート。

HTTP サーバー

  • index ディレクトリ内で、アプリの設定と HTTP ハンドラの登録により main.go を開始します。

    
// 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: %w", err)
	}

	pubsubTopic := pubsubClient.Topic(topicName)

	firestoreClient, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		return nil, fmt.Errorf("firestore.NewClient: %w", 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: %w", err)
	}

	return &app{
		pubsubClient: pubsubClient,
		pubsubTopic:  pubsubTopic,

		firestoreClient: firestoreClient,
		tmpl:            tmpl,
	}, nil
}

  • インデックス ハンドラ（/）は、Firestore から既存の翻訳をすべて取得し、リストを使用して HTML テンプレートへの入力を行います。

    
// 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
	}
}

  • 新しい翻訳をリクエストするには、HTML フォームを送信します。/request-translation に登録されているリクエスト翻訳ハンドラは、フォーム送信を解析してリクエストを検証し、メッセージを 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
	}
}

HTML テンプレート

HTML テンプレートはユーザーに表示される HTML ページの基礎となり、以前の翻訳を表示して新しい翻訳をリクエストできます。HTTP サーバーは、既存の翻訳のリストを使用してテンプレートへの入力を行います。

  • HTML テンプレートの <head> 要素には、ページのメタデータ、スタイルシート、JavaScript が含まれます。 
    <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>

    このページでは、Material Design Lite（MDL）の CSS アセットと JavaScript アセットを取得します。MDL によって、ウェブサイトに Material Design の外観を追加できます。

    ページは JQuery を使用してドキュメントの読み込みが完了するのを待ち、フォーム送信ハンドラを設定します。翻訳のリクエスト フォームが送信されるたびに、ページは最小限のフォームの検証を行い値が空でないことを確認してから、非同期リクエストを /request-translation エンドポイントに送信します。

    最後に、リクエストが成功したか、またはエラーが発生したかを示す MDL スナックバーが表示されます。

  • ページの HTML 本文は、MDL レイアウトといくつかの MDL コンポーネントを使用して、翻訳のリストと追加の翻訳をリクエストするフォームを表示します。 
    <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>

アプリのビルド

  • ウェブアプリをデプロイする前にアプリをビルドして、アプリが正しくコンパイルされることと、すべての依存関係が機能していることを確認します。 
    go build -o start ./index

    何も出力されずに start ファイルが作成されれば、ビルドは成功しています。

ウェブアプリのデプロイ

App Engine スタンダード環境を使用すると、高負荷で大量のデータが存在する状況でも確実に動作するアプリをビルドしてデプロイできます。

このチュートリアルでは、App Engine スタンダード環境を使用して HTTP フロントエンドをデプロイします。

app.yaml は App Engine アプリを構成します。

runtime: go111
main: index
  • app.yaml ファイルと同じディレクトリから、App Engine スタンダード環境にアプリをデプロイします。 
    gcloud app deploy

アプリをテストする

Cloud Run 関数と App Engine アプリをデプロイしたら、翻訳のリクエストを試行します。

  1. ブラウザでアプリを表示するには、次の URL を入力します。

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

    以下を置き換えます。

    翻訳に関する空のリストと新しい翻訳をリクエストするためのフォームを掲載したページがあります。

  2. [翻訳するテキスト] フィールドに、翻訳するテキスト（Hello, World など）を入力します。
  3. テキストを翻訳する対象言語をプルダウン リストから選択します。
  4. [送信] をクリックします。
  5. ページを更新するには、[Refresh]（更新）をクリックします。翻訳リストに新しい行が追加されます。翻訳が表示されない場合は、数秒待ってからもう一度お試しください。それでも翻訳が表示されない場合は、アプリのデバッグに関する次のセクションをご覧ください。

アプリのデバッグ

App Engine アプリに接続できない場合や、新しい翻訳が表示されない場合は、次の点をご確認ください。

  1. gcloud デプロイ コマンドが正常に終了して、エラーを出力しなかったことを確認します。エラーが発生した場合は、それらを修正してから、もう一度 Cloud Run 関数のデプロイと App Engine アプリを試みます。

  2. Google Cloud コンソールで、ログビューア ページに移動します。

    [ログビューア] ページに移動
    1. [最近選択したリソース] プルダウン リストで [GAE アプリケーション] をクリックし、[All module_id] をクリックします。アプリにアクセスした以降のリクエストのリストが表示されます。リクエストのリストが表示されない場合は、プルダウン リストで [All module_id ] が選択されていることを確認します。エラー メッセージが Google Cloud コンソールに出力された場合は、アプリのコードがアプリの理解に関するセクション内のコードと一致することを確認します。
    2. [最近選択したリソース] プルダウン リストで、[Cloud Function] をクリックしてから、[すべての関数名] をクリックします。リクエストされた翻訳ごとに関数が表示されます。表示されない場合は、Cloud Run 関数と App Engine アプリが同じ Pub/Sub トピックを使用していることを確認します。
      • background/index/main.go ファイルで、topicName 定数が "translate" になっているか確認します。
      • Cloud Run 関数をデプロイする場合は、必ず --trigger-topic=translate フラグを含める必要があります。

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

Google Cloud プロジェクトを削除する

  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.

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.
  3. アプリのバージョンを削除するには、[削除] をクリックします。

Cloud Run 関数を削除する

  • このチュートリアルで作成した Cloud Run 関数を削除します。 
    gcloud functions delete Translate

次のステップ