Se usó la API de Cloud Translation para traducir esta página.

Activa funciones de Cloud Run con Cloud Tasks

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

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 publica con controladores en app.yaml. Las variables necesarias para la creación de tareas se pasan como variables de entorno.

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

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

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 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 objetivo como HTTP Request.
Especificar el HTTP method que se usará y el URL del objetivo
Establece el encabezado Content-Type en application/json para que las aplicaciones posteriores puedan analizar la carga útil estructurada.
Agrega un correo electrónico de la cuenta de servicio para que Cloud Tasks pueda proporcionar credenciales al destino de la solicitud, 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.

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;

Crea el correo electrónico

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

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

Prepara la aplicación

Configura SendGrid

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

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

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

Dirígete al directorio que contiene el código de muestra:
```
cd cloud-tasks/
```

Implementa la Cloud Run Function

Navega al directorio function/:
```
cd function/
```
Sigue estos pasos para implementar la función:
```
gcloud functions deploy sendEmail --runtime nodejs14 --trigger-http \
  --no-allow-unauthenticated \
  --set-env-vars SENDGRID_API_KEY=SENDGRID_API_KEY \
```
Reemplaza SENDGRID_API_KEY por tu clave de API.

Este comando usa las siguientes marcas:
- --trigger-http para especificar el tipo de activador de Cloud Run Functions
- --no-allow-unauthenticated para especificar que la invocación de la función requiere autenticación.
- --set-env-var para configurar tus credenciales de SendGrid
Nota: Puedes administrar Cloud Run Functions desde Firebase y la Google Cloud consola. Se puede replicar la escritura y la implementación desde FirebaseUI. 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 para comenzar con las funciones de Firebase y los activadores HTTP.
Configura el control de acceso para la función de modo que solo permita usuarios autenticados.
1. Selecciona la función sendEmail en la IU de Cloud Run 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. Haz clic en el botón Agregar principales que se encuentra arriba.
4. Establece Principales nuevas en allAuthenticatedUsers.
5. Configura el Rol.
  - Funciones de primera generación (1ª gen.): Establece el rol en Cloud Function Invoker.
  - Funciones de segunda generación (2ª gen.): Establece el rol en Cloud Run Invoker.
6. Haz clic en GUARDAR.

Crea una cola de Cloud Tasks

Crea una cola con el siguiente comando de gcloud:
```
gcloud tasks queues create my-queue --location=LOCATION
```
Reemplaza LOCATION por la ubicación que prefieras para la fila, por ejemplo, us-west2. Si no especificas la ubicación, gcloud CLI elige la predeterminada.
Verifica que se haya creado correctamente:
```
gcloud tasks queues describe my-queue --location=LOCATION
```
Reemplaza LOCATION por la ubicación de la fila.

Crea una cuenta de servicio

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

En la IU de cuentas de servicio, haz clic en + CREAR CUENTA DE SERVICIO.
Agrega un nombre de cuenta de servicio (nombre visible descriptivo) y selecciona Crear.
Establece el Rol y haz clic en Continuar.
- Funciones de primera generación (1ª gen.): Establece el rol en Cloud Function Invoker.
- Funciones de segunda generación (2ª gen.): Establece el rol en Cloud Run Invoker.
Seleccione Listo.

Implementa el extremo y el creador de tareas en App Engine

Navega al directorio app/:
```
cd ../app/
```

Actualiza las variables en app.yaml con tus valores:

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 fila, usa el siguiente comando:

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

Reemplaza LOCATION por la ubicación de la fila.

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

gcloud functions describe sendEmail

Implementa la aplicación en el entorno estándar de App Engine con el siguiente comando:
```
gcloud app deploy
```
Abre la aplicación para enviar una postal por correo electrónico:
```
gcloud app browse
```