Trigger Cloud Run functions using Cloud Tasks

Understanding the code

This section walks you through the app's code and explains how it works.

Creating the task

The index page is served using handlers in the app.yaml. The variables needed for task creation are passed in as environment variables.

runtime:nodejs16
env_variables:
QUEUE_NAME:"my-queue"
QUEUE_LOCATION:"us-central1"
FUNCTION_URL:"https://<region>-<project_id>.cloudfunctions.net/sendEmail"
SERVICE_ACCOUNT_EMAIL:"<member>@<project_id>.iam.gserviceaccount.com"
# Handlers for serving the index page.
handlers:
-url:/static
static_dir:static
-url:/
static_files:index.html
upload:index.html

This code creates the endpoint /send-email. This endpoint handles form submissions from the index page and passes that data to the task creation code.

app.post('/send-email',(req,res)=>{
// Set the task payload to the form submission.
const{to_name,from_name,to_email,date}=req.body;
constpayload={to_name,from_name,to_email};
createHttpTaskWithToken(
process.env.GOOGLE_CLOUD_PROJECT,
QUEUE_NAME,
QUEUE_LOCATION,
FUNCTION_URL,
SERVICE_ACCOUNT_EMAIL,
payload,
date
);
res.status(202).send('📫 Your postcard is in the mail! 💌');
});

This code actually creates the task and sends it on to the Cloud Tasks queue. The code builds the task by:

• Specifying the target type as HTTP Request.

• Specifying the HTTP method to be used and the URL of the target.

• Setting the Content-Type header to application/json so downstream applications can parse the structured payload.

• Adding a service account email so that Cloud Tasks can provide credentials to the request target, which requires authentication. The service account is created separately.

• Checking to make sure the user input for date is within the 30 days maximum and adding it to the request as field scheduleTime.

constMAX_SCHEDULE_LIMIT=30*60*60*24;// Represents 30 days in seconds.
constcreateHttpTaskWithToken=asyncfunction(
project='my-project-id',// Your GCP Project id
queue='my-queue',// Name of your Queue
location='us-central1',// The GCP region of your queue
url='https://example.com/taskhandler',// The full url path that the request will be sent to
email='<member>@<project-id>.iam.gserviceaccount.com',// Cloud IAM service account
payload='Hello, World!',// The task HTTP request body
date=newDate()// Intended date to schedule task
){
// Imports the Google Cloud Tasks library.
const{v2beta3}=require('@google-cloud/tasks');
// Instantiates a client.
constclient=newv2beta3.CloudTasksClient ();
// Construct the fully qualified queue name.
constparent=client.queuePath(project,location,queue);
// Convert message to buffer.
constconvertedPayload=JSON.stringify(payload);
constbody=Buffer.from(convertedPayload).toString('base64');
consttask={
httpRequest:{
httpMethod:'POST',
url,
oidcToken:{
serviceAccountEmail:email,
audience:url,
},
headers:{
'Content-Type':'application/json',
},
body,
},
};
constconvertedDate=newDate(date);
constcurrentDate=newDate();
// Schedule time can not be in the past.
if(convertedDate < currentDate){
console.error('Scheduled date in the past.');
}elseif(convertedDate > currentDate){
constdate_diff_in_seconds=(convertedDate-currentDate)/1000;
// Restrict schedule time to the 30 day maximum.
if(date_diff_in_seconds > MAX_SCHEDULE_LIMIT){
console.error('Schedule time is over 30 day maximum.');
}
// Construct future date in Unix time.
constdate_in_seconds=
Math.min(date_diff_in_seconds,MAX_SCHEDULE_LIMIT)+Date.now()/1000;
// Add schedule time to request in Unix time using Timestamp structure.
// https://googleapis.dev/nodejs/tasks/latest/google.protobuf.html#.Timestamp
task.scheduleTime={
seconds:date_in_seconds,
};
}
try{
// Send create task request.
const[response]=awaitclient.createTask({parent,task});
console.log(`Created task ${response.name}`);
returnresponse.name;
}catch(error){
// Construct error for Stackdriver Error Reporting
console.error(Error(error.message));
}
};
module.exports=createHttpTaskWithToken;

Creating the email

This code creates the Cloud Run function that is the target for the Cloud Tasks request. It uses the request body to construct an email and send it via the SendGrid API.

constsendgrid=require('@sendgrid/mail');
/**
 * Responds to an HTTP request from Cloud Tasks and sends an email using data
 * from the request body.
 *
 * @param {object} req Cloud Function request context.
 * @param {object} req.body The request payload.
 * @param {string} req.body.to_email Email address of the recipient.
 * @param {string} req.body.to_name Name of the recipient.
 * @param {string} req.body.from_name Name of the sender.
 * @param {object} res Cloud Function response context.
 */
exports.sendEmail=async(req,res)=>{
// Get the SendGrid API key from the environment variable.
constkey=process.env.SENDGRID_API_KEY;
if(!key){
consterror=newError(
'SENDGRID_API_KEY was not provided as environment variable.'
);
error.code=401;
throwerror;
}
sendgrid.setApiKey(key);
// Get the body from the Cloud Task request.
const{to_email,to_name,from_name}=req.body;
if(!to_email){
consterror=newError('Email address not provided.');
error.code=400;
throwerror;
}elseif(!to_name){
consterror=newError('Recipient name not provided.');
error.code=400;
throwerror;
}elseif(!from_name){
consterror=newError('Sender name not provided.');
error.code=400;
throwerror;
}
// Construct the email request.
constmsg={
to:to_email,
from:'postcard@example.com',
subject:'A Postcard Just for You!',
html:postcardHTML(to_name,from_name),
};
try{
awaitsendgrid.send(msg);
// Send OK to Cloud Task queue to delete task.
res.status(200).send('Postcard Sent!');
}catch(error){
// Any status code other than 2xx or 503 will trigger the task to retry.
res.status(error.code).send(error.message);
}
};

Preparing the application

Setting up SendGrid

1. Create a SendGrid account.

   • You can either do this manually via the SendGrid website
   • or you can use the Google Cloud Launcher, which will create an account for you and integrate billing. See Creating a SendGrid account using Cloud Launcher.

2. Create a SendGrid API key:

   1. Log in to your SendGrid account.

   2. In the left hand navigation open Settings and click API Keys.

   3. Click Create API Key and select restricted access. Under the Mail Send header, select Full Access.

   4. Copy the API Key when it is displayed (you will only see this once, make sure you paste it somewhere so you can use it later on).

Downloading the source code

1. Clone the sample app repository to your local machine:

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
   

2. Change to the directory that contains the sample code:

   cd cloud-tasks/
   

Deploying the Cloud Run function

1. Navigate to the function/ directory:

   cd function/
   

2. Deploy the function:

   gcloudfunctionsdeploysendEmail--runtimenodejs14--trigger-http\
   --no-allow-unauthenticated\
   --set-env-varsSENDGRID_API_KEY=SENDGRID_API_KEY\

   Replace SENDGRID_API_KEY with your API key.

   This command uses flags:

   • --trigger-http to specify the Cloud Run functions trigger type.

   • --no-allow-unauthenticated to specify the function invocation requires authentication.

   • --set-env-var to set your SendGrid credentials

3. Set access control for the function to only allow authenticated users.

   1. Select the sendEmail function in the Cloud Run functions UI.

   2. If you don't see permissions info for sendEmail, click SHOW INFO PANEL in the upper right hand corner.

   3. Click the Add principals button above.

   4. Set New principals to allAuthenticatedUsers.

   5. Set the Role.

      • First generation (1st gen) functions: set the role to Cloud Function Invoker
      • Second generation (2nd gen) functions: set the role to Cloud Run Invoker

   6. Click SAVE.

Creating a Cloud Tasks queue

1. Create a queue using the following gcloud command:

   gcloudtasksqueuescreatemy-queue--location=LOCATION

   Replace LOCATION with your preferred location for the queue, for example, us-west2. If you do not specify the location, the gcloud CLI picks the default.

2. Verify that it was created successfully:

   gcloudtasksqueuesdescribemy-queue--location=LOCATION

   Replace LOCATION with the location of the queue.

Creating a service account

The Cloud Tasks request must provide credentials in the Authorization header for the Cloud Run function to authenticate the request. This service account allows Cloud Tasks to create and add an OIDC token for that purpose.

1. In the Service accounts UI, click +CREATE SERVICE ACCOUNT.

2. Add a service account name(friendly display name) and select create.

3. Set the Role and click Continue.

   • First generation (1st gen) functions: set the role to Cloud Function Invoker
   • Second generation (2nd gen) functions: set the role to Cloud Run Invoker

4. Select Done.

Deploying the endpoint and the task creator to App Engine

1. Navigate to app/ directory:

   cd ../app/
   

2. Update variables in the app.yaml with your values:

   env_variables:
   QUEUE_NAME:"my-queue"
   QUEUE_LOCATION:"us-central1"
   FUNCTION_URL:"https://<region>-<project_id>.cloudfunctions.net/sendEmail"
   SERVICE_ACCOUNT_EMAIL:"<member>@<project_id>.iam.gserviceaccount.com"

   To find your queue location, use the following command:

   gcloudtasksqueuesdescribemy-queue--location=LOCATION

   Replace LOCATION with the location of the queue.

   To find your function URL, use the following command:

   gcloudfunctionsdescribesendEmail

3. Deploy the application to the App Engine standard environment, using the following command:

   gcloudappdeploy

4. Open the application to send a postcard as an email:

   gcloudappbrowse