Elaborazione in background con .NET

Molte app devono eseguire l'elaborazione in background al di fuori del contesto di una richiesta web. Questo tutorial crea un'app web che consente agli utenti di inserire il testo da tradurre e poi visualizza un elenco delle traduzioni precedenti. La traduzione viene eseguita in un processo in background per evitare di bloccare la richiesta dell'utente.

Il seguente diagramma illustra il processo di richiesta di traduzione.

Ecco la sequenza di eventi che descrive il funzionamento dell'app tutorial:

Visita la pagina web per visualizzare un elenco delle traduzioni precedenti, archiviate in Firestore.
Richiedi la traduzione di un testo inserendo un modulo HTML.
La richiesta di traduzione viene pubblicata su Pub/Sub.
Viene attivato un servizio Cloud Run sottoscritto a quell'argomento Pub/Sub.
Il servizio Cloud Run utilizza Cloud Translation per tradurre il testo.
Il servizio Cloud Run archivia il risultato in Firestore.

Questo tutorial è rivolto a chiunque sia interessato a scoprire di più sull'elaborazione in background con Google Cloud. Non è richiesta alcuna esperienza pregressa con Pub/Sub, Firestore, App Engine o Cloud Run Functions. Tuttavia, per comprendere tutto il codice, è utile avere una certa esperienza con .NET, JavaScript e HTML.

Obiettivi

Comprendere ed eseguire il deployment dei servizi Cloud Run.
Prova l'app.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova senza costi.

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per saperne di più, consulta Esegui la pulizia.

Prima di iniziare

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei 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.

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

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

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

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Aggiorna i componenti di gcloud:
```
gcloud components update
```
Prepara l'ambiente di sviluppo.
Configurazione di un ambiente di sviluppo .NET

Preparazione dell'app

Nella finestra del terminale, clona il repository dell'app di esempio sulla tua macchina locale:
```
git clone https://github.com/GoogleCloudPlatform/getting-started-dotnet.git
```
In alternativa puoi scaricare l'esempio come file ZIP ed estrarlo.
Passa alla directory che contiene il codice campione dell'attività in background:
```
cd getting-started-dotnet/BackgroundProcessing
```

Informazioni sul servizio `TranslateWorker`

Il servizio inizia importando diverse dipendenze come Firestore e Translation.
```
using Google.Cloud.Firestore;
using Google.Cloud.Translation.V2;
```

I client Firestore e Translation vengono inizializzati in modo da poter essere riutilizzati tra le invocazioni del gestore. In questo modo, non devi inizializzare nuovi client per ogni chiamata, il che rallenterebbe l'esecuzione.

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

L'API Translation traduce la stringa nella lingua che hai selezionato.

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

Il costruttore del controller riceve i client Firestore e Pub/Sub.

Il metodo Post analizza il messaggio Pub/Sub per ottenere il testo da tradurre. Utilizza l'ID messaggio come nome univoco per la richiesta di traduzione per assicurarsi di non memorizzare traduzioni duplicate.

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

Deployment del servizio `TranslateWorker`

Nella directory BackgroundProcessing, esegui lo script PowerShell per creare ed eseguire il deployment del servizio su Cloud Run:
```
PublishTo-CloudRun.ps1
```

Comprendere lo script `PublishTo-CloudRun.ps1`

Lo script PublishTo-CloudRun.ps1 pubblica il servizio su Cloud Run e protegge il servizio TranslateWorker da abusi. Se il servizio consentisse tutte le connessioni in entrata, chiunque potrebbe pubblicare richieste di traduzione nel controller e quindi sostenere costi. Pertanto, configuri il servizio in modo che accetti solo richieste POST da Pub/Sub.

Lo script esegue le seguenti operazioni:

Crea l'app localmente utilizzando dotnet publish.
Crea un container che esegue l'app utilizzando Cloud Build.
Esegue il deployment dell'app in Cloud Run.
Consente al progetto di creare token di autenticazione Pub/Sub.
Crea un account di servizio per rappresentare l'identità della sottoscrizione Pub/Sub.
Concede al account di servizio l'autorizzazione per richiamare il servizio TranslateWorker.

Crea un argomento e una sottoscrizione 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
}

Informazioni sul servizio `TranslateUI`

Il servizio TranslateUI esegue il rendering di una pagina web che mostra le traduzioni recenti e accetta richieste di nuove traduzioni.

La classe StartUp configura un'app ASP.NET e crea client Pub/Sub e 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?}");
            });
        }

    }
}

Il gestore dell'indice Index recupera tutte le traduzioni esistenti da Firestore e riempie un ViewModel con l'elenco:

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

Le nuove traduzioni vengono richieste inviando un modulo HTML. Il gestore di traduzione delle richieste convalida la richiesta e pubblica un messaggio su Pub/Sub:
```
// Submit a new translation request.
await _publisher.PublishAsync(new PubsubMessage()
{
    Data = ByteString.CopyFromUtf8(SourceText)
});
```

Deployment del servizio `TranslateUI`

Nella directory BackgroundProcessing, esegui lo script PowerShell per creare ed eseguire il deployment del servizio su Cloud Run:
```
./PublishTo-CloudRun.ps1
```

Comprendere lo script `PublishTo-CloudRun.ps1`

Lo script PublishTo-CloudRun.ps1 pubblica l'app su Cloud Run.

Lo script esegue le seguenti operazioni:

Crea l'app localmente utilizzando dotnet publish.
Crea un container che esegue l'app utilizzando Cloud Build.

Esegue il deployment dell'app in 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

Testare l'app

Dopo aver eseguito correttamente lo script PublishTo-CloudRun.ps1, prova a richiedere una traduzione.

L'ultimo comando nello script PublishTo-CloudRun.ps1 indica l'URL del servizio UI. Nella finestra del terminale, trova l'URL del servizio TranslateUI:
```
gcloud beta run services describe translate-ui --region $region --format="get(status.address.hostname)"
```
Nel browser, vai all'URL che hai ottenuto nel passaggio precedente.

C'è una pagina con un elenco vuoto di traduzioni e un modulo per richiedere nuove traduzioni.
Nel campo Testo da tradurre, inserisci un testo da tradurre, ad esempio Hello, World..
Fai clic su Invia.
Per aggiornare la pagina, fai clic su Aggiorna . Nella lista di traduzioni è presente una nuova riga. Se non vedi una traduzione, attendi qualche altro secondo e riprova. Se ancora non vedi una traduzione, consulta la sezione successiva sulla risoluzione dei problemi dell'app.

Esecuzione del debug dell'app

Se non riesci a connetterti al servizio Cloud Run o non vedi nuove traduzioni, controlla quanto segue:

Verifica che lo script PublishTo-CloudRun.ps1 sia stato completato correttamente e non abbia generato errori. Se sono stati rilevati errori (ad esempio, message=Build failed), correggili e riprova a eseguire il comando.
Controlla la presenza di errori nei log:
1. Nella console Google Cloud , vai alla pagina Cloud Run.
  
  Vai alla pagina Cloud Run
2. Fai clic sul nome del servizio, translate-ui.
3. Fai clic su Log.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto Google Cloud

Nella console Google Cloud , vai alla pagina Gestisci risorse.
Vai a Gestisci risorse
Nell'elenco dei progetti, seleziona quello che vuoi eliminare, quindi fai clic su Elimina.
Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

Elimina i servizi Cloud Run.

Elimina i servizi Cloud Run che hai creato in questo tutorial:

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

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

Passaggi successivi

Scopri di più su Cloud Run.

Elaborazione in background con .NET Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Obiettivi

Costi

Prima di iniziare

Preparazione dell'app

Informazioni sul servizio TranslateWorker

Deployment del servizio TranslateWorker

Comprendere lo script PublishTo-CloudRun.ps1

Informazioni sul servizio TranslateUI

Deployment del servizio TranslateUI

Comprendere lo script PublishTo-CloudRun.ps1

Testare l'app

Esecuzione del debug dell'app

Esegui la pulizia

Elimina il progetto Google Cloud

Elimina i servizi Cloud Run.

Passaggi successivi

Elaborazione in background con .NET

Informazioni sul servizio `TranslateWorker`

Deployment del servizio `TranslateWorker`

Comprendere lo script `PublishTo-CloudRun.ps1`

Informazioni sul servizio `TranslateUI`

Deployment del servizio `TranslateUI`

Comprendere lo script `PublishTo-CloudRun.ps1`