Halaman ini diterjemahkan oleh Cloud Translation API.

Memicu fungsi Cloud Run menggunakan Cloud Tasks

Tutorial ini menunjukkan cara menggunakan Cloud Tasks dalam aplikasi App Engine untuk memicu fungsi Cloud Run dan mengirim email terjadwal.

Memahami kode

Bagian ini akan memandu Anda mempelajari kode aplikasi dan menjelaskan cara kerjanya.

Membuat tugas

Halaman indeks ditayangkan menggunakan handler di app.yaml. Variabel yang diperlukan untuk pembuatan tugas diteruskan sebagai variabel lingkungan.

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

Kode ini membuat endpoint /send-email. Endpoint ini menangani pengiriman formulir dari halaman indeks dan meneruskan data tersebut ke kode pembuatan tugas.

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

Kode ini benar-benar membuat tugas dan mengirimkannya ke antrean Cloud Tasks. Kode ini membangun tugas dengan:

Menentukan jenis target sebagai HTTP Request.
Menentukan HTTP method yang akan digunakan dan URL target.
Menetapkan header Content-Type ke application/json sehingga aplikasi hilir dapat mengurai payload terstruktur.
Menambahkan email akun layanan agar Cloud Tasks dapat memberikan kredensial ke target permintaan, yang memerlukan autentikasi. Akun layanan dibuat secara terpisah.
Memeriksa untuk memastikan input pengguna untuk tanggal berada dalam batas maksimum 30 hari dan menambahkannya ke permintaan sebagai kolom 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;

Membuat email

Kode ini membuat fungsi Cloud Run yang menjadi target untuk permintaan Cloud Tasks. Fungsi ini menggunakan isi permintaan untuk membuat email dan mengirimkannya melalui 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);
  }
};

Menyiapkan aplikasi

Menyiapkan SendGrid

Buat akun SendGrid.
- Anda dapat melakukannya secara manual melalui situs SendGrid
- Atau, Anda dapat menggunakan Google Cloud Launcher, yang akan membuat akun untuk Anda dan mengintegrasikan penagihan. Lihat Membuat akun SendGrid menggunakan Cloud Launcher.
Buat kunci API SendGrid:
1. Login ke akun SendGrid Anda.
2. Di navigasi sebelah kiri, buka Setelan, lalu klik Kunci API.
3. Klik Create API Key, lalu pilih akses terbatas. Di bagian header Mail Send, pilih Full Access.
4. Salin Kunci API saat ditampilkan (Anda hanya akan melihatnya sekali, pastikan Anda menempelkannya di suatu tempat agar dapat menggunakannya nanti).

Mendownload kode sumber

Clone repositori aplikasi contoh ke komputer lokal Anda:

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

Ubah ke direktori yang berisi kode contoh:
```
cd cloud-tasks/
```

Men-deploy fungsi Cloud Run

Buka direktori function/:
```
cd function/
```
Deploy fungsi tersebut:
```
gcloud functions deploy sendEmail --runtime nodejs14 --trigger-http \
  --no-allow-unauthenticated \
  --set-env-vars SENDGRID_API_KEY=SENDGRID_API_KEY \
```
Ganti SENDGRID_API_KEY dengan kunci API Anda.

Perintah ini menggunakan flag:
- --trigger-http untuk menentukan jenis pemicu Cloud Run Functions.
- --no-allow-unauthenticated untuk menentukan bahwa pemanggilan fungsi memerlukan autentikasi.
- --set-env-var untuk menyetel kredensial SendGrid Anda
Catatan: Anda dapat mengelola fungsi Cloud Run dari konsol Firebase dan Google Cloud . Penulisan dan deployment dari FirebaseUI dapat direplikasi; namun, kode fungsi harus cocok dengan framework fungsi Firebase. Pelajari lebih lanjut cara memulai fungsi Firebase dan pemicu HTTP.
Tetapkan kontrol akses untuk fungsi agar hanya mengizinkan pengguna terautentikasi.
1. Pilih fungsi sendEmail di UI Cloud Run functions.
2. Jika Anda tidak melihat info izin untuk sendEmail, klik TAMPILKAN PANEL INFO di pojok kanan atas.
3. Klik tombol Tambahkan prinsipal di atas.
4. Tetapkan New principals ke allAuthenticatedUsers.
5. Tetapkan Role.
  - Fungsi generasi pertama (generasi ke-1): tetapkan peran ke Cloud Function Invoker
  - Fungsi generasi kedua (generasi ke-2): tetapkan peran ke Cloud Run Invoker
6. Klik SIMPAN.

Membuat antrean Cloud Tasks

Buat antrean menggunakan perintah gcloud berikut:
```
gcloud tasks queues create my-queue --location=LOCATION
```
Ganti LOCATION dengan lokasi pilihan Anda untuk antrean, misalnya, us-west2. Jika Anda tidak menentukan lokasi, gcloud CLI akan memilih lokasi default.
Pastikan bahwa cluster berhasil dibuat:
```
gcloud tasks queues describe my-queue --location=LOCATION
```
Ganti LOCATION dengan lokasi antrean.

Membuat akun layanan

Permintaan Cloud Tasks harus memberikan kredensial di header Authorization agar fungsi Cloud Run dapat mengautentikasi permintaan. Akun layanan ini memungkinkan Cloud Tasks membuat dan menambahkan token OIDC untuk tujuan tersebut.

Di UI akun layanan, klik +BUAT AKUN LAYANAN.
Tambahkan nama akun layanan(nama tampilan yang mudah diingat) dan pilih buat.
Tetapkan Peran, lalu klik Lanjutkan.
- Fungsi generasi pertama (generasi ke-1): tetapkan peran ke Cloud Function Invoker
- Fungsi generasi kedua (generasi ke-2): tetapkan peran ke Cloud Run Invoker
Pilih Selesai.

Men-deploy endpoint dan pembuat tugas ke App Engine

Buka direktori app/:
```
cd ../app/
```

Perbarui variabel di app.yaml dengan nilai Anda:

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"

Untuk menemukan lokasi antrean Anda, gunakan perintah berikut:

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

Ganti LOCATION dengan lokasi antrean.

Untuk menemukan URL fungsi Anda, gunakan perintah berikut:

gcloud functions describe sendEmail

Deploy aplikasi ke lingkungan standar App Engine menggunakan perintah berikut:
```
gcloud app deploy
```
Buka aplikasi untuk mengirim kartu pos sebagai email:
```
gcloud app browse
```