Trigger Cloud Run functions using Cloud Tasks

This tutorial shows you how to use Cloud Tasks within an App Engine application to trigger a Cloud Run function and send a scheduled email.

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;
  const payload = {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.

const MAX_SCHEDULE_LIMIT = 30 * 60 * 60 * 24; // Represents 30 days in seconds.

const createHttpTaskWithToken = async function (
  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 = new Date() // Intended date to schedule task
) {
  // Imports the Google Cloud Tasks library.
  const {v2beta3} = require('@google-cloud/tasks');

  // Instantiates a client.
  const client = new v2beta3.CloudTasksClient();

  // Construct the fully qualified queue name.
  const parent = client.queuePath(project, location, queue);

  // Convert message to buffer.
  const convertedPayload = JSON.stringify(payload);
  const body = Buffer.from(convertedPayload).toString('base64');

  const task = {
    httpRequest: {
      httpMethod: 'POST',
      url,
      oidcToken: {
        serviceAccountEmail: email,
        audience: url,
      },
      headers: {
        'Content-Type': 'application/json',
      },
      body,
    },
  };

  const convertedDate = new Date(date);
  const currentDate = new Date();

  // Schedule time can not be in the past.
  if (convertedDate < currentDate) {
    console.error('Scheduled date in the past.');
  } else if (convertedDate > currentDate) {
    const date_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.
    const date_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] = await client.createTask({parent, task});
    console.log(`Created task ${response.name}`);
    return response.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.

const sendgrid = 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.
  const key = process.env.SENDGRID_API_KEY;
  if (!key) {
    const error = new Error(
      'SENDGRID_API_KEY was not provided as environment variable.'
    );
    error.code = 401;
    throw error;
  }
  sendgrid.setApiKey(key);

  // Get the body from the Cloud Task request.
  const {to_email, to_name, from_name} = req.body;
  if (!to_email) {
    const error = new Error('Email address not provided.');
    error.code = 400;
    throw error;
  } else if (!to_name) {
    const error = new Error('Recipient name not provided.');
    error.code = 400;
    throw error;
  } else if (!from_name) {
    const error = new Error('Sender name not provided.');
    error.code = 400;
    throw error;
  }

  // Construct the email request.
  const msg = {
    to: to_email,
    from: 'postcard@example.com',
    subject: 'A Postcard Just for You!',
    html: postcardHTML(to_name, from_name),
  };

  try {
    await sendgrid.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

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.
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

Clone the sample app repository to your local machine:

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

Change to the directory that contains the sample code:
```
cd cloud-tasks/
```

Deploying the Cloud Run function

Navigate to the function/ directory:
```
cd function/
```
Deploy the function:
```
gcloud functions deploy sendEmail --runtime nodejs14 --trigger-http \
  --no-allow-unauthenticated \
  --set-env-vars SENDGRID_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
Note: You can manage Cloud Run functions from both the Firebase and Google Cloud console. Writing and deploying from the FirebaseUI can be replicated; however the function code needs to match the Firebase functions framework. Learn more about getting started with Firebase functions and HTTP triggers.
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

Create a queue using the following gcloud command:
```
gcloud tasks queues create my-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.
Verify that it was created successfully:
```
gcloud tasks queues describe my-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.

In the Service accounts UI, click +CREATE SERVICE ACCOUNT.
Add a service account name(friendly display name) and select create.
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
Select Done.

Deploying the endpoint and the task creator to App Engine

Navigate to app/ directory:
```
cd ../app/
```

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:

gcloud tasks queues describe my-queue --location=LOCATION

Replace LOCATION with the location of the queue.

To find your function URL, use the following command:

gcloud functions describe sendEmail

Deploy the application to the App Engine standard environment, using the following command:
```
gcloud app deploy
```
Open the application to send a postcard as an email:
```
gcloud app browse
```