Usa Cloud Tasks para activar Cloud Functions

En este instructivo, se muestra cómo usar Cloud Tasks dentro de una aplicación de Google App Engine para activar una función de Cloud Functions y enviar un correo electrónico programado.

Objetivos

• Comprender el código en cada uno de los componentes
• Crear una cuenta de SendGrid
• Descargue el código fuente
• Implementa una función de Cloud para recibir solicitudes de Cloud Tasks y enviar un correo electrónico a través de la API de SendGrid.
• Crea una cola de Cloud Tasks.
• Crea una cuenta de servicio para autenticar tus solicitudes de Cloud Tasks.
• Implementa el código de cliente que permite que un usuario envíe un correo electrónico.

Costos

Cloud Tasks, Cloud Functions y App Engine tienen un nivel gratuito, por lo que, siempre que ejecutes el instructivo dentro del nivel gratuito de los productos determinados, no deberías generar costos adicionales. Para obtener más información, consulta Precios.

Antes de comenzar

1. Selecciona o crea un proyecto de GCP.

   Nota: Si no planeas conservar los recursos creados durante este procedimiento, crea un proyecto en lugar de seleccionar un proyecto existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir a la página App Engine

2. Inicializa una aplicación de App Engine en tu proyecto:

   1. En la página Bienvenido a App Engine, haz clic en Crear aplicación.

   2. Selecciona una región para tu aplicación. Esta ubicación servirá como parámetro LOCATION_ID para tus solicitudes de Cloud Tasks, así que anótala. Ten en cuenta que hay dos ubicaciones, llamadas europe-west y us-central en los comandos de App Engine, que se llaman europe-west1 y us-central1 en los comandos de Cloud Tasks.

   3. Selecciona Node.js para el lenguaje y Estándar para el entorno.

   4. Si aparece la ventana emergente Habilitar facturación, selecciona tu cuenta de facturación. Si no tienes una cuenta de facturación, haz clic en Crear cuenta de facturación y sigue los pasos del asistente.

   5. En la página Comenzar, haz clic en Siguiente. Abordarás esto más adelante.

3. Habilita las API de Cloud Functions y Cloud Tasks.

   Habilita las API

4. Instala e inicializa la CLI de gcloud.

Comprende el código

En esta sección, se explica el código de la app y su funcionamiento.

Crea la tarea

La página de índice se entrega mediante controladores en app.yaml. Las variables necesarias para la creación de la tarea se pasan como variables de entorno.

cloud-task/app/app.yaml

Ver en GitHub

runtime: nodejs14

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

Este código crea el extremo /send-email. Este extremo controla los envíos de formularios desde la página de índice y pasa esos datos al código de creación de la tarea.

cloud-tasks/app/index.js

Ver en GitHub

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! 💌');
});

Este código en realidad crea la tarea y la envía a la cola de Cloud Tasks. El código compila la tarea de la siguiente manera:

• Especifica el tipo de destino como HTTP Request.

• Especifica el HTTP method que se usará y el URL del destino.

• Configurar el encabezado Content-Type como application/json para que las aplicaciones descendentes puedan analizar la carga útil estructurada

• Agregar un correo electrónico de la cuenta de servicio para que Cloud Tasks pueda proporcionar credenciales al destino de la solicitud, lo que requiere autenticación La cuenta de servicio se crea por separado.

• Verifica que la entrada del usuario para la fecha esté dentro del máximo de 30 días y agrega a la solicitud como campo scheduleTime.

cloud-tasks/app/createTask.js

Ver en GitHub

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: new URL(url).origin,
      },
      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;

Crea el correo electrónico

Este código crea la función de Cloud Functions que es el destino de la solicitud de Cloud Task. Usa el cuerpo de la solicitud para construir un correo electrónico y enviarlo a través de la API de SendGrid.

cloud-tareas/función/índice.js

Ver en GitHub

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: '[e-mail]',
    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);
  }
};

Prepara la aplicación

Configura SendGrid

1. Crear una cuenta de SendGrid

   • Puedes hacerlo de manera manual a través del sitio web de SendGrid.
   • o puedes usar Google Cloud Launcher, que creará una cuenta para ti e integrará la facturación. Consulta Crea una cuenta de SendGrid con Cloud Launcher.

2. Crea una clave de API de SendGrid:

   1. Accede a tu cuenta de SendGrid.

   2. En la barra de navegación izquierda, abre Configuración y haz clic en Claves de API.

   3. Haz clic en Crear clave de API y selecciona el acceso restringido. En el encabezado Enviar correo electrónico, selecciona Acceso completo.

   4. Copia la clave de API cuando se muestre (solo verás esto una vez, asegúrate de pegarla en algún lugar para poder usarla más adelante).

Descarga el código fuente

1. Clona el repositorio de la app de muestra en tu máquina local:

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

2. Ve al directorio que contiene el código de muestra:

   cd cloud-tasks/
   

Implementa la función de Cloud Functions

1. Navega al directorio function/.

   cd function/
   

2. Para implementar la función, reemplaza sendgrid_api_key por la clave:

   gcloud functions deploy sendEmail --runtime nodejs14 --trigger-http --set-env-vars SENDGRID_API_KEY=sendgrid_api_key
   

   En este comando, se usan marcas:

   • --trigger-http para especificar el tipo de activador de Cloud Functions

   • --set-env-var para configurar tus credenciales de SendGrid

   Nota: Puedes administrar Cloud Functions desde Firebase y GCP Console. Se puede replicar la escritura y la implementación desde la IU de Firebase. Sin embargo, el código de la función debe coincidir con el marco de trabajo de las funciones de Firebase. Obtén más información sobre cómo comenzar con las funciones de Firebase y los activadores HTTP.

3. Configura el control de acceso para que la función solo permita usuarios autenticados.

   1. Selecciona la función sendEmail en la IU de Cloud Functions.

   2. Si no ves la información de permisos para sendEmail, haz clic en MOSTRAR PANEL DE INFORMACIÓN en la esquina superior derecha.

   3. En el encabezado Invocador de Cloud Functions, borra el allUsers principal.

   4. Haga clic en el botón Agregar principales que se encuentra más arriba.

   5. Establece Nuevos principales en allAuthenticatedUsers.

   6. Establece la función en Cloud Function Invoker.

   7. Haz clic en GUARDAR.

Crea una cola de Cloud Tasks

1. Crea una cola con el siguiente comando de gcloud:

   gcloud tasks queues create my-queue
   

2. Verifica que se haya creado correctamente:

   gcloud tasks queues describe my-queue
   

Crea una cuenta de servicio

La solicitud de Cloud Tasks debe proporcionar credenciales en el encabezado Authorization para que Cloud Function autentique la solicitud. Esta cuenta de servicio permite que Cloud Tasks cree y agregue un token OIDC para ese fin.

1. En IAM y administración | IU de cuentas de servicio, haz clic en + CREAR CUENTA DE SERVICIO.

2. Agrega un nombre de cuenta de servicio (nombre visible descriptivo) y selecciona Crear.

3. Selecciona la función Invocador de Cloud Functions y haz clic en Continuar.

4. Seleccione Listo.

Implementa el extremo y el creador de tareas en App Engine

1. Navega al directorio app/:

   cd ../app/
   

2. Actualiza las variables de app.yaml con tus valores:

   cloud-task/app/app.yaml

   Ver en GitHub

   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"

   Para encontrar la ubicación de tu cola, usa el siguiente comando:

   gcloud tasks queues describe my-queue
   

   Para encontrar la URL de tu función, usa el siguiente comando:

   gcloud functions describe sendEmail
   

3. Implemente la aplicación en el entorno estándar de App Engine mediante el siguiente comando:

   gcloud app deploy
   

4. Abre la aplicación para enviar una postal como un correo electrónico:

   gcloud app browse
   

Limpia

Una vez que completes el instructivo, puedes limpiar los recursos que creaste para que dejen de usar la cuota y generar cargos. En las siguientes secciones, se describe cómo borrar o desactivar estos recursos.

Borrar recursos

Una vez que completes el instructivo, puedes limpiar los recursos que creaste en GCP para que no consuman tu cuota y no se facturen en el futuro. En las secciones siguientes, se describe cómo borrar o desactivar estos recursos.

Nota:La única forma de borrar la versión predeterminada de tu aplicación de App Engine es mediante la eliminación del proyecto.

Borra la función de Cloud Functions

1. Vaya a la página Cloud Functions en Cloud Console.

   Ir a la página de Cloud Functions

2. Haz clic en las casillas de verificación junto a tus funciones.

3. Haz clic en el botón Borrar en la parte superior de la página y confirma la eliminación.

Borra la cola de Cloud Task

1. Abre la página de listas de tareas en cola de Cloud Tasks en Console.

   Ir a la página de listas de tareas en cola de Cloud Tasks

2. Selecciona la cola que deseas borrar y haz clic en Borrar cola.

3. Confirma la acción.

   Nota: Si borras una cola de Cloud Console, debes esperar 7 días antes de volver a crearla con el mismo nombre.

Borra el proyecto

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

Para borrar el proyecto, sigue estos pasos:

Precaución: Borrar un proyecto tiene estas consecuencias:

• Se borra todo en el proyecto. Si utilizaste un proyecto existente para este instructivo, cuando lo borres, también borrarás cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los ID personalizados de proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID del proyecto personalizado que desees utilizar en el futuro. Para conservar las URL que utilizan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto en lugar de borrar todo el proyecto.

Si planeas explorar varios instructivos y guías de inicio rápido, la reutilización de proyectos puede ayudarte a evitar exceder los límites de las cuotas del proyecto.

1. En la consola de Google Cloud, ve a la página Administrar recursos.

   Ir a Administrar recursos

2. En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

¿Qué sigue?

• Obtén más información sobre cómo crear tareas de destino HTTP.
• Obtén más información sobre cómo configurar tu cola de Cloud Tasks.