Pemrosesan latar belakang dengan .NET

Banyak aplikasi perlu melakukan pemrosesan di latar belakang di luar konteks permintaan web. Tutorial ini membuat aplikasi web yang memungkinkan pengguna memasukkan teks untuk diterjemahkan, lalu menampilkan daftar terjemahan sebelumnya. Terjemahan dilakukan dalam proses latar belakang untuk menghindari pemblokiran permintaan pengguna.

Diagram berikut menggambarkan proses permintaan terjemahan.

Berikut urutan peristiwa cara kerja aplikasi tutorial:

1. Buka halaman web untuk melihat daftar terjemahan sebelumnya, yang disimpan di Firestore.
2. Minta terjemahan teks dengan memasukkan formulir HTML.
3. Permintaan terjemahan dipublikasikan ke Pub/Sub.
4. Layanan Cloud Run yang berlangganan topik Pub/Sub tersebut akan dipicu.
5. Layanan Cloud Run menggunakan Cloud Translation untuk menerjemahkan teks.
6. Layanan Cloud Run menyimpan hasilnya di Firestore.

Tutorial ini ditujukan bagi siapa saja yang tertarik untuk mempelajari pemrosesan di latar belakang dengan Google Cloud. Anda tidak memerlukan pengalaman sebelumnya dengan Pub/Sub, Firestore, App Engine, atau fungsi Cloud Run. Namun, untuk memahami semua kode, pengalaman dengan .NET, JavaScript, dan HTML akan sangat membantu.

Tujuan

• Pahami dan deploy layanan Cloud Run.
• Coba aplikasi.

Biaya

Dalam dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

• Cloud Run
• Firestore
• Pub/Sub
• Cloud Translation

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Setelah menyelesaikan tugas yang dijelaskan dalam dokumen ini, Anda dapat menghindari penagihan berkelanjutan dengan menghapus resource yang Anda buat. Untuk mengetahui informasi selengkapnya, baca bagian Pembersihan.

Sebelum memulai

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

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.

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

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

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

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.

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

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

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

1. Perbarui komponen gcloud:

   gcloud components update

2. Siapkan lingkungan pengembangan Anda.

   Menyiapkan lingkungan pengembangan .NET

Menyiapkan aplikasi

1. Di jendela terminal, clone repositori aplikasi contoh ke komputer lokal Anda:

   git clone https://github.com/GoogleCloudPlatform/getting-started-dotnet.git

   Atau, Anda dapat mendownload contoh dalam file ZIP dan mengekstraknya.

2. Ubah ke direktori yang berisi kode contoh tugas latar belakang:

   cd getting-started-dotnet/BackgroundProcessing

Memahami layanan TranslateWorker

• Layanan dimulai dengan mengimpor beberapa dependensi seperti Firestore dan Translation.

  using Google.Cloud.Firestore;
  using Google.Cloud.Translation.V2;
  

• Klien Firestore dan Translation diinisialisasi sehingga dapat digunakan kembali di antara pemanggilan handler. Dengan begitu, Anda tidak perlu menginisialisasi klien baru untuk setiap pemanggilan, yang akan memperlambat eksekusi.

  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 menerjemahkan string ke bahasa yang Anda pilih.

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

• Konstruktor pengontrol menerima klien Firestore dan Pub/Sub.

  Metode Post mengurai pesan Pub/Sub untuk mendapatkan teks yang akan diterjemahkan. Menggunakan ID pesan sebagai nama unik untuk permintaan terjemahan guna memastikan tidak menyimpan terjemahan duplikat.

  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...");
          }
      }
  }
  

Men-deploy layanan TranslateWorker

• Di direktori BackgroundProcessing, jalankan skrip PowerShell untuk membangun dan men-deploy layanan ke Cloud Run:

  PublishTo-CloudRun.ps1

Memahami skrip PublishTo-CloudRun.ps1

Skrip PublishTo-CloudRun.ps1 memublikasikan layanan ke Cloud Run, dan melindungi layanan TranslateWorker dari penyalahgunaan. Jika layanan mengizinkan semua koneksi masuk, siapa pun dapat memposting permintaan terjemahan ke pengontrol dan dengan demikian menimbulkan biaya. Oleh karena itu, Anda menyiapkan layanan agar hanya menerima permintaan POST dari Pub/Sub.

Skrip tersebut akan melakukan hal berikut:

1. Membangun aplikasi secara lokal menggunakan dotnet publish.
2. Membangun container yang menjalankan aplikasi menggunakan Cloud Build.
3. Men-deploy aplikasi ke Cloud Run.
4. Mengizinkan project membuat token autentikasi Pub/Sub.
5. Membuat akun layanan untuk merepresentasikan identitas langganan Pub/Sub.
6. Memberi akun layanan izin untuk memanggil layanan TranslateWorker.

7. Membuat topik dan langganan 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-$[e-mail] `
        --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
   }
   
   

Memahami layanan TranslateUI

Layanan TranslateUI merender halaman web yang menampilkan terjemahan terbaru, dan menerima permintaan terjemahan baru.

• Class StartUp mengonfigurasi aplikasi ASP.NET dan membuat klien Pub/Sub dan 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?}");
              });
          }
  
      }
  }
  

• Handler indeks Index mendapatkan semua terjemahan yang ada dari Firestore dan mengisi ViewModel dengan daftar:

  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 });
          }
      }
  }

• Terjemahan baru diminta dengan mengirimkan formulir HTML. Penanganan terjemahan permintaan memvalidasi permintaan, dan memublikasikan pesan ke Pub/Sub:

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

Men-deploy layanan TranslateUI

• Di direktori BackgroundProcessing, jalankan skrip PowerShell untuk membangun dan men-deploy layanan ke Cloud Run:

  ./PublishTo-CloudRun.ps1

Memahami skrip PublishTo-CloudRun.ps1

Skrip PublishTo-CloudRun.ps1 memublikasikan aplikasi ke Cloud Run.

Skrip tersebut akan melakukan hal berikut:

1. Membangun aplikasi secara lokal menggunakan dotnet publish.
2. Membangun container yang menjalankan aplikasi menggunakan Cloud Build.

3. Men-deploy aplikasi ke 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
   
   

Menguji aplikasi

Setelah berhasil menjalankan skrip PublishTo-CloudRun.ps1, coba minta terjemahan.

1. Perintah terakhir dalam skrip PublishTo-CloudRun.ps1 memberi tahu Anda URL untuk layanan UI Anda. Di jendela terminal, temukan URL untuk layanan TranslateUI:

   gcloud beta run services describe translate-ui --region $region --format="get(status.address.hostname)"

2. Di browser Anda, buka URL yang Anda dapatkan dari langkah sebelumnya.

   Ada halaman dengan daftar terjemahan kosong dan formulir untuk meminta terjemahan baru.

3. Di kolom Text to translate, masukkan beberapa teks yang akan diterjemahkan, misalnya, Hello, World.

4. Klik Kirim.

5. Untuk memuat ulang halaman, klik Muat ulang . Ada baris baru dalam daftar terjemahan. Jika Anda tidak melihat terjemahan, tunggu beberapa detik lagi, lalu coba lagi. Jika Anda masih tidak melihat terjemahan, lihat bagian berikutnya tentang men-debug aplikasi.

Men-debug aplikasi

Jika Anda tidak dapat terhubung ke layanan Cloud Run atau tidak melihat terjemahan baru, periksa hal berikut:

• Periksa apakah skrip PublishTo-CloudRun.ps1 berhasil diselesaikan dan tidak menghasilkan error apa pun. Jika ada error (misalnya, message=Build failed), perbaiki, lalu coba jalankan lagi.

• Periksa error dalam log:

  1. Di konsol Google Cloud , buka halaman Cloud Run.

     Buka halaman Cloud Run

  2. Klik nama layanan, translate-ui.

  3. Klik Logs.

Pembersihan

Agar tidak perlu membayar biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, hapus project yang berisi resource tersebut, atau simpan project dan hapus setiap resource.

Menghapus Google Cloud project

Perhatian: Penghapusan project memiliki efek berikut:
• Semua hal dalam project akan dihapus. Jika Anda menggunakan project yang ada untuk mengerjakan tugas di dokumen ini, saat Anda menghapusnya, pekerjaan lain dalam project tersebut juga akan dihapus.
• Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin juga membuat project ID kustom yang masih ingin digunakan pada masa mendatang. Agar tidak kehilangan URL yang menggunakan project ID tersebut, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.
1. Di Konsol Google Cloud , buka halaman Manage resources.

   Buka Kelola resource

2. Pada daftar project, pilih project yang ingin Anda hapus, lalu klik Delete.
3. Pada dialog, ketik project ID, lalu klik Shut down untuk menghapus project.

Menghapus layanan Cloud Run.

• Hapus layanan Cloud Run yang Anda buat dalam tutorial ini:

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

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

Langkah berikutnya

• Pelajari lebih lanjut Cloud Run.