使用 .NET 進行背景處理

許多應用程式都需要在網路要求內容之外執行背景處理。本教學課程會建立一個網頁應用程式，讓使用者輸入要翻譯的文字，然後顯示先前翻譯的清單。翻譯是在背景程序中完成，以避免妨礙使用者的要求。

下圖說明要求翻譯的過程。

這是教學課程應用程式運作的事件順序：

前往網頁以查看 Firestore 儲存的先前翻譯清單。
輸入 HTML 表單以要求翻譯文字。
翻譯要求會發布至 Pub/Sub。
系統會觸發訂閱該 Pub/Sub 主題的 Cloud Run 服務。
Cloud Run 服務使用 Cloud Translation 翻譯文字。
Cloud Run 服務會將結果儲存在 Firestore 中。

本教學課程的適用對象為有興趣瞭解如何使用 Google Cloud進行背景處理的人員。您無須具備使用 Pub/Sub、Firestore、App Engine 或 Cloud Run functions 的經驗。不過，如要瞭解所有程式碼，具備一些 .NET、JavaScript 和 HTML 的使用經驗會有所幫助。

目標

瞭解及部署 Cloud Run 服務。
試用應用程式。

費用

在本文件中，您會使用下列 Google Cloud的計費元件：

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用期資格。

完成本文所述工作後，您可以刪除建立的資源，避免繼續計費，詳情請參閱「清除所用資源」。

事前準備

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

更新 gcloud 元件：
```
gcloud components update
```
準備開發環境。
設定 .NET 開發環境

準備應用程式

在終端機視窗中，將範例應用程式存放區複製到本機電腦：
```
git clone https://github.com/GoogleCloudPlatform/getting-started-dotnet.git
```
您也可以下載 zip 格式的範例檔案，然後將檔案解壓縮。
變更為包含背景工作範例程式碼的目錄：
```
cd getting-started-dotnet/BackgroundProcessing
```

瞭解 `TranslateWorker` 服務

這項服務會先匯入數個依附元件，例如 Firestore 和 Translation。
```
using Google.Cloud.Firestore;
using Google.Cloud.Translation.V2;
```

Firestore 和 Translation 用戶端已初始化，因此可以在處理常式叫用之間重複使用。如此一來，您就不必為每次叫用初始化新的用戶端，可避免降低執行速度。

public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<FirestoreDb>(provider =>
        FirestoreDb.Create(GetFirestoreProjectId()));
    services.AddSingleton<TranslationClient>(
        TranslationClient.Create());
    services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}

Translation API 將字串轉換為您選擇的語言。

var result = await _translator.TranslateTextAsync(sourceText, "es");

控制器的建構函式會接收 Firestore 和 Pub/Sub 用戶端。

Post 方法會剖析 Pub/Sub 訊息，以取得要翻譯的文字。這項服務會使用訊息 ID 做為翻譯要求的專屬名稱，確保不會儲存任何重複翻譯。

using Google.Cloud.Firestore;
using Google.Cloud.Translation.V2;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using System;
using System.Collections.Generic;
using System.Text;
using System.Threading.Tasks;

namespace TranslateWorker.Controllers
{
    /// <summary>
    /// The message Pubsub posts to our controller.
    /// </summary>
    public class PostMessage
    {
        public PubsubMessage message { get; set; }
        public string subscription { get; set; }
    }

    /// <summary>
    /// Pubsub's inner message.
    /// </summary>
    public class PubsubMessage
    {
        public string data { get; set; }
        public string messageId { get; set; }
        public Dictionary<string, string> attributes { get; set; }
    }


    [Route("api/[controller]")]
    [ApiController]
    public class TranslateController : ControllerBase
    {
        private readonly ILogger<TranslateController> _logger;
        private readonly FirestoreDb _firestore;
        private readonly TranslationClient _translator;
        // The Firestore collection where we store translations.
        private readonly CollectionReference _translations;

        public TranslateController(ILogger<TranslateController> logger,
            FirestoreDb firestore,
            TranslationClient translator)
        {
            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
            _firestore = firestore ?? throw new ArgumentNullException(
                nameof(firestore));
            _translator = translator ?? throw new ArgumentNullException(
                nameof(translator));
            _translations = _firestore.Collection("Translations");
        }

        /// <summary>
        /// Handle a posted message from Pubsub.
        /// </summary>
        /// <param name="request">The message Pubsub posts to this process.</param>
        /// <returns>NoContent on success.</returns>
        [HttpPost]
        public async Task<IActionResult> Post([FromBody] PostMessage request)
        {
            // Unpack the message from Pubsub.
            string sourceText;
            try
            {
                byte[] data = Convert.FromBase64String(request.message.data);
                sourceText = Encoding.UTF8.GetString(data);
            }
            catch (Exception e)
            {
                _logger.LogError(1, e, "Bad request");
                return BadRequest();
            }
            // Translate the source text.
            _logger.LogDebug(2, "Translating {0} to Spanish.", sourceText);
            var result = await _translator.TranslateTextAsync(sourceText, "es");
            // Store the result in Firestore.
            Translation translation = new Translation()
            {
                TimeStamp = DateTime.UtcNow,
                SourceText = sourceText,
                TranslatedText = result.TranslatedText
            };
            _logger.LogDebug(3, "Saving translation {0} to {1}.",
                translation.TranslatedText, _translations.Path);
            await _translations.Document(request.message.messageId)
                .SetAsync(translation);
            // Return a success code.
            return NoContent();
        }

        /// <summary>
        /// Serve a root page so Cloud Run knows this process is healthy.
        /// </summary>
        [Route("/")]
        public IActionResult Index()
        {
            return Content("Serving translate requests...");
        }
    }
}

部署 `TranslateWorker` 服務

在 BackgroundProcessing 目錄中，執行 PowerShell 指令碼，建構服務並部署至 Cloud Run：
```
PublishTo-CloudRun.ps1
```

瞭解 `PublishTo-CloudRun.ps1` 指令碼

PublishTo-CloudRun.ps1 指令碼會將服務發布至 Cloud Run，並防止 TranslateWorker 服務遭到濫用。如果服務允許所有連入連線，任何人都可以將翻譯要求發布至控制器，進而產生費用。因此，您將服務設為只接受來自 Pub/Sub 的 POST 要求。

指令碼會執行下列作業：

使用 dotnet publish 在本機建構應用程式。
使用 Cloud Build 建構執行應用程式的容器。
將應用程式部署至 Cloud Run。
啟用專案，建立 Pub/Sub 驗證權杖。
建立服務帳戶，代表 Pub/Sub 訂閱身分。
授予服務帳戶叫用 TranslateWorker 服務的權限。

建立 Pub/Sub 主題和訂閱項目。

# 1. Build the application locally.
dotnet publish -c Release

# Collect some details about the project that we'll need later.
$projectId = gcloud config get-value project
$projectNumber = gcloud projects describe $projectId --format="get(projectNumber)"
$region = "us-central1"

# 2. Use Google Cloud Build to build the worker's container and publish to Google
# Container Registry.
gcloud builds submit --tag gcr.io/$projectId/translate-worker `
    TranslateWorker/bin/Release/netcoreapp2.1/publish

# 3. Run the container with Google Cloud Run.
gcloud beta run deploy translate-worker --region $region --platform managed `
    --image gcr.io/$projectId/translate-worker --no-allow-unauthenticated
$url = gcloud beta run services describe translate-worker --platform managed `
    --region $region --format="get(status.address.hostname)"

# 4. Enable the project to create pubsub authentication tokens.
gcloud projects add-iam-policy-binding $projectId `
     --member=serviceAccount:service-$projectNumber@gcp-sa-pubsub.iam.gserviceaccount.com `
     --role=roles/iam.serviceAccountTokenCreator

# 5. Create a service account to represent the Cloud Pub/Sub subscription identity.
$serviceAccountExists = gcloud iam service-accounts describe `
    cloud-run-pubsub-invoker@$projectId.iam.gserviceaccount.com 2> $null
if (-not $serviceAccountExists) {
    gcloud iam service-accounts create cloud-run-pubsub-invoker `
        --display-name "Cloud Run Pub/Sub Invoker"
}

# 6. For Cloud Run, give this service account permission to invoke 
# translate-worker service.
gcloud beta run services add-iam-policy-binding translate-worker `
     --member=serviceAccount:cloud-run-pubsub-invoker@$projectId.iam.gserviceaccount.com `
     --role=roles/run.invoker --region=$region

# 7. Create a pubsub topic and subscription, if they don't already exist.
$topicExists = gcloud pubsub topics describe translate-requests 2> $null 
if (-not $topicExists) {
    gcloud pubsub topics create translate-requests
}
$subscriptionExists = gcloud pubsub subscriptions describe translate-requests 2> $null
if ($subscriptionExists) {
    gcloud beta pubsub subscriptions modify-push-config translate-requests `
        --push-endpoint $url/api/translate `
        --push-auth-service-account cloud-run-pubsub-invoker@$projectId.iam.gserviceaccount.com
} else {
    gcloud beta pubsub subscriptions create translate-requests `
        --topic translate-requests --push-endpoint $url/api/translate `
        --push-auth-service-account cloud-run-pubsub-invoker@$projectId.iam.gserviceaccount.com
}

瞭解 `TranslateUI` 服務

TranslateUI 服務會顯示最近的翻譯內容，並接受新的翻譯要求。

StartUp 類別會設定 ASP.NET 應用程式，並建立 Pub/Sub 和 Firestore 用戶端。

using Google.Apis.Auth.OAuth2;
using Google.Cloud.Firestore;
using Google.Cloud.PubSub.V1;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using System;
using System.Net.Http;

namespace TranslateUI
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddSingleton<FirestoreDb>(
                provider => FirestoreDb.Create(GetFirestoreProjectId()));
            services.AddSingleton<PublisherClient>(
                provider => PublisherClient.CreateAsync(new TopicName(
                    GetProjectId(), GetTopicName())).Result);
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Home/Error");
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseStaticFiles();
            app.UseCookiePolicy();

            app.UseMvc(routes =>
            {
                routes.MapRoute(
                    name: "default",
                    template: "{controller=Home}/{action=Index}/{id?}");
            });
        }

    }
}

索引處理常式 Index 會從 Firestore 取得所有現有的譯文，並使用清單填入 ViewModel：

using Google.Cloud.Firestore;
using Google.Cloud.PubSub.V1;
using Google.Protobuf;
using Microsoft.AspNetCore.Mvc;
using System.Diagnostics;
using System.Linq;
using System.Threading.Tasks;
using TranslateUI.Models;

namespace TranslateUI.Controllers
{
    public class HomeController : Controller
    {
        private readonly FirestoreDb _firestore;
        private readonly PublisherClient _publisher;
        private CollectionReference _translations;

        public HomeController(FirestoreDb firestore, PublisherClient publisher)
        {
            _firestore = firestore;
            _publisher = publisher;
            _translations = _firestore.Collection("Translations");
        }

        [HttpPost]
        [HttpGet]
        public async Task<IActionResult> Index(string SourceText)
        {
            // Look up the most recent 20 translations.
            var query = _translations.OrderByDescending("TimeStamp")
                .Limit(20);
            var snapshotTask = query.GetSnapshotAsync();

            if (!string.IsNullOrWhiteSpace(SourceText))
            {
                // Submit a new translation request.
                await _publisher.PublishAsync(new PubsubMessage()
                {
                    Data = ByteString.CopyFromUtf8(SourceText)
                });
            }

            // Render the page.
            var model = new HomeViewModel()
            {
                Translations = (await snapshotTask).Documents.Select(
                    doc => doc.ConvertTo<Translation>()).ToList(),
                SourceText = SourceText
            };
            return View(model);
        }

        [ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
        public IActionResult Error()
        {
            return View(new ErrorViewModel { RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
        }
    }
}

如要要求新的翻譯，請提交 HTML 表單。翻譯要求處理常式會驗證要求，並向 Pub/Sub 發布訊息：

// Submit a new translation request.
await _publisher.PublishAsync(new PubsubMessage()
{
    Data = ByteString.CopyFromUtf8(SourceText)
});

部署 `TranslateUI` 服務

在 BackgroundProcessing 目錄中，執行 PowerShell 指令碼，建構服務並部署至 Cloud Run：
```
./PublishTo-CloudRun.ps1
```

瞭解 `PublishTo-CloudRun.ps1` 指令碼

PublishTo-CloudRun.ps1 指令碼會將應用程式發布至 Cloud Run。

指令碼會執行下列作業：

使用 dotnet publish 在本機建構應用程式。
使用 Cloud Build 建構容器，執行應用程式。

將應用程式部署至 Cloud Run。

# 1. Build the application locally.
dotnet publish -c Release
# 2. Use Google Cloud Build to build the UI's container and publish to Google
# Container Registry. 
gcloud builds submit --tag gcr.io/$projectId/translate-ui `
    TranslateUI/bin/Release/netcoreapp2.1/publish

# 3. Run the container with Google Cloud Run.
gcloud beta run deploy translate-ui --region $region --platform managed `
    --image gcr.io/$projectId/translate-ui --allow-unauthenticated

測試應用程式

成功執行 PublishTo-CloudRun.ps1 指令碼後，請嘗試要求翻譯。

PublishTo-CloudRun.ps1 指令碼中的最後一個指令會顯示 UI 服務的網址。在終端機視窗中，找出 TranslateUI 服務的網址：
```
gcloud beta run services describe translate-ui --region $region --format="get(status.address.hostname)"
```
在瀏覽器中前往上一個步驟取得的網址。

網頁上會包含空白翻譯清單及要求新翻譯的表單。
在「要翻譯的文字」欄位中，輸入一些要翻譯的文字，例如 Hello, World.
按一下「提交」。
如要重新整理頁面，請按一下「重新整理」圖示。翻譯清單中會新增一列。如果未看到譯文，請等待幾秒鐘，然後再試一次。如果還是沒看到譯文，請參閱下一節說明如何除錯應用程式。

應用程式偵錯

如果您無法連線至 Cloud Run 服務，或是沒有看到新的譯文，請檢查下列事項：

檢查 PublishTo-CloudRun.ps1 指令碼是否順利完成，且未輸出任何錯誤。如果發生錯誤 (例如 message=Build failed)，請修正錯誤，並再次嘗試執行。
檢查記錄中是否有錯誤：
1. 前往 Google Cloud 控制台的 Cloud Run 頁面。
  
  前往 Cloud Run 頁面
2. 按一下服務名稱 translate-ui。
3. 按一下「Logs」(記錄檔)。

清除所用資源

為避免因為本教學課程所用資源，導致系統向 Google Cloud 帳戶收取費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除 Google Cloud 專案

前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。
前往「Manage resources」(管理資源)
在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。

刪除 Cloud Run 服務。

刪除在本教學課程中建立的 Cloud Run 服務：

gcloud beta run services delete --region=$region translate-ui

gcloud beta run services delete --region=$region translate-worker

後續步驟

進一步瞭解 Cloud Run。

使用 .NET 進行背景處理 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

準備應用程式

瞭解 TranslateWorker 服務

部署 TranslateWorker 服務

瞭解 PublishTo-CloudRun.ps1 指令碼

瞭解 TranslateUI 服務

部署 TranslateUI 服務

瞭解 PublishTo-CloudRun.ps1 指令碼

測試應用程式

應用程式偵錯

清除所用資源

刪除 Google Cloud 專案

刪除 Cloud Run 服務。

後續步驟

使用 .NET 進行背景處理

瞭解 `TranslateWorker` 服務

部署 `TranslateWorker` 服務

瞭解 `PublishTo-CloudRun.ps1` 指令碼

瞭解 `TranslateUI` 服務

部署 `TranslateUI` 服務

瞭解 `PublishTo-CloudRun.ps1` 指令碼