Many apps need to do background processing outside of the context of a web request. This tutorial creates a web app that lets users input text to translate, and then displays a list of previous translations. The translation is done in a background process to avoid blocking the user's request.
The following diagram illustrates the translation request process.
Here is the sequence of events for how the tutorial app works:
- Visit the web page to see a list of previous translations, stored in Firestore.
- Request a translation of text by entering an HTML form.
- The translation request is published to Pub/Sub.
- A Cloud Run service subscribed to that Pub/Sub topic is triggered.
- The Cloud Run service uses Cloud Translation to translate the text.
- The Cloud Run service stores the result in Firestore.
This tutorial is intended for anyone who is interested in learning about background processing with Google Cloud. No prior experience is required with Pub/Sub, Firestore, App Engine, or Cloud Run functions. However, to understand all of the code, some experience with .NET, JavaScript, and HTML is helpful.
Objectives
- Understand and deploy Cloud Run services.
- Try the app.
Costs
In this document, you use the following billable components of Google Cloud:
To generate a cost estimate based on your projected usage,
use the pricing calculator.
When you finish the tasks that are described in this document, you can avoid continued billing by deleting the resources that you created. For more information, see Clean up.
Before you begin
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Firestore, Cloud Run, Pub/Sub, and Cloud Translation APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Firestore, Cloud Run, Pub/Sub, and Cloud Translation APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
Update
gcloud
components:gcloud components update
- Prepare your development environment.
Preparing the app
In your terminal window, clone the sample app repository to your local machine:
git clone https://github.com/GoogleCloudPlatform/getting-started-dotnet.git
Alternatively, you can download the sample as a zip file and extract it.
Change to the directory that contains the background task sample code:
cd getting-started-dotnet/BackgroundProcessing
Understanding the TranslateWorker
service
The service starts by importing several dependencies like Firestore and Translation.
The Firestore and Translation clients are initialized so they can be reused between handler invocations. That way, you don't have to initialize new clients for every invocation, which would slow down execution.
The Translation API translates the string to the language you selected.
The controller's constructor receives the Firestore and Pub/Sub clients.
The
Post
method parses the Pub/Sub message to get the text to translate. It uses the message ID as a unique name for the translation request to make sure it doesn't store any duplicate translations.
Deploying the TranslateWorker
service
In the
BackgroundProcessing
directory, run the PowerShell script to build and deploy the service to Cloud Run:PublishTo-CloudRun.ps1
Understanding the PublishTo-CloudRun.ps1
script
The PublishTo-CloudRun.ps1
script publishes the service to Cloud Run, and
protects the TranslateWorker service from being abused. If the service permitted all
incoming connections, then anyone could post translate requests to the controller
and thereby incur costs. Therefore, you set up the service to only accept
POST
requests from Pub/Sub.
The script does the following:
- Builds the app locally using
dotnet publish
. - Builds a container that runs the app using Cloud Build.
- Deploys the app to Cloud Run.
- Enables the project to create Pub/Sub authentication tokens.
- Creates a service account to represent the Pub/Sub subscription identity.
- Gives the service account permission to invoke
TranslateWorker
service. Creates a Pub/Sub topic and subscription.
Understanding the TranslateUI
service
The TranslateUI
service renders a web page that displays recent translations,
and accepts requests for new translations.
The
StartUp
class configures an ASP.NET app and creates Pub/Sub and Firestore clients.The index handler
Index
gets all existing translations from Firestore and fills aViewModel
with the list:New translations are requested by submitting an HTML form. The request translation handler validates the request, and publishes a message to Pub/Sub:
Deploying the TranslateUI
service
In the
BackgroundProcessing
directory, run the PowerShell script to build and deploy the service to Cloud Run:./PublishTo-CloudRun.ps1
Understanding the PublishTo-CloudRun.ps1
script
The PublishTo-CloudRun.ps1
script publishes the app to Cloud Run.
The script does the following:
- Builds the app locally using
dotnet publish
. - Builds a container that runs the app by using Cloud Build.
Deploys the app to Cloud Run.
Testing the app
After successfully running the PublishTo-CloudRun.ps1
script, try
requesting a translation.
The final command in the
PublishTo-CloudRun.ps1
script tells you the URL for your UI service. In your terminal window, find the URL for theTranslateUI
service:gcloud beta run services describe translate-ui --region $region --format="get(status.address.hostname)"
In your browser, go to the URL that you got from the previous step.
There is a page with an empty list of translations and a form to request new translations.
In the Text to translate field, enter some text to translate, for example,
Hello, World.
Click Submit.
To refresh the page, click Refresh refresh. There is a new row in the translation list. If you don't see a translation, wait a few more seconds and try again. If you still don't see a translation, see the next section about debugging the app.
Debugging the app
If you cannot connect to your Cloud Run service or don't see new translations, check the following:
Check that the
PublishTo-CloudRun.ps1
script successfully completed and didn't output any errors. If there were errors (for example,message=Build failed
), fix them, and try running again.Check for errors in the logs:
In the Google Cloud console, go to the Cloud Run page.
Click the service name,
translate-ui
.Click Logs.
Clean up
To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.
Delete the Google Cloud project
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Delete the Cloud Run services.
Delete the Cloud Run services you created in this tutorial:
gcloud beta run services delete --region=$region translate-ui
gcloud beta run services delete --region=$region translate-worker