Cloud Tasks を使用して Cloud Functions をトリガーする

このチュートリアルでは、App Engine アプリケーション内で Cloud Tasks を使用して Cloud Functions の関数をトリガーし、スケジュールされたメールを送信する方法について説明します。

目標

各コンポーネントのコードを理解する。
SendGrid アカウントを作成する。
ソースコードをダウンロードする。
Cloud Tasks リクエストを受信し、SendGrid API を介してメールを送信する Cloud Function をデプロイする。
Cloud Tasks キューを作成する。
Cloud Tasks リクエストを認証するためのサービスアカウントを作成する。
ユーザーがメールを送信できるようにクライアントコードをデプロイする。

料金

Cloud Tasks、Cloud Functions、App Engine には無料枠があるため、無料枠でチュートリアルを実行する限り、追加の費用は発生しません。詳細については、料金をご覧ください。

始める前に

Google Cloud プロジェクトを選択または作成します。

注: この手順で作成するリソースをそのまま保持する予定でない場合、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。チュートリアルの完了後にそのプロジェクトを削除すれば、プロジェクトに関連するすべてのリソースを削除できます。

[App Engine] ページに移動
プロジェクトで App Engine アプリケーションを初期化します。
1. [App Engine へようこそ] ページで [アプリケーションを作成] をクリックします。
2. アプリケーションのリージョンを選択します。このロケーションは、Cloud Tasks リクエストの LOCATION_ID パラメータとして使用するため、メモしておいてください。App Engine コマンドで europe-west および us-central と呼ばれる 2 つのロケーションは、Cloud Tasks コマンドではそれぞれ europe-west1 および us-central1 と呼ばれます。
3. 言語として [Node.js] を選択し、環境として [Standard] を選択します。
4. [課金を有効にする] ポップアップが表示されたら、請求先アカウントを選択します。まだ請求先アカウントがない場合は、[請求先アカウントの作成] をクリックしてウィザードの手順を行います。
5. [開始] ページで [次へ] をクリックします。他のことは後で対応します。
Cloud Functions と Cloud Tasks APIs を有効にします。

API を有効にする
gcloud CLI をインストールして初期化する

コードについて

このセクションでは、アプリのコードとその動作を順を追って説明します。

タスクの作成

インデックスページは、app.yaml のハンドラを使用して提供されます。タスクの作成に必要な変数が、環境変数として渡されます。

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

このコードにより、エンドポイント /send-email が作成されます。このエンドポイントは、インデックスページからのフォーム送信を処理し、そのデータをタスク作成コードに渡します。

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

このコードでは実際にタスクが作成され、Cloud Tasks キューに送信されます。コードは、次の方法でタスクを構築します。

ターゲットタイプを HTTP Request に指定します。
使用する HTTP method とターゲットの URL を指定します。
ダウンストリームアプリケーションが構造化ペイロードを解析できるように、Content-Typeヘッダーをapplication/jsonに設定します。
認証を要求しているリクエストターゲットに Cloud Tasks が認証情報を提供できるように、サービスアカウントのメールアドレスを追加します。サービスアカウントは個別に作成されます。
日付のユーザー入力が最大 30 日以内であることを確認し、フィールド 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;

メールの作成

このコードは、Cloud Tasks リクエストのターゲットである Cloud Functions の関数を作成します。リクエスト本文を使用してメールを作成し、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);
  }
};

アプリケーションの準備

SendGrid の設定

SendGrid アカウントを作成する。
- これは、SendGrid ウェブサイトから手動で行うこともできます。
- アカウントを作成し、課金データを統合する Google Cloud Launcher を使って行うことも可能です。Cloud Launcher を使って SendGrid アカウントを作成するをご覧ください。
SendGrid API キーを作成します。
1. SendGrid アカウントにログインします。
2. 左側のナビゲーションで、[設定] を開き、[API キー] をクリックします。
3. [Create API Key] をクリックし、制限付きアクセスを選択します。[メール送信] ヘッダーで、[フルアクセス] を選択します。
4. 表示された API キーをコピーします（このキーは 1 回だけ表示されます。後で使用できるように別の場所に貼り付けてください）。

ソースコードのダウンロード

ローカルマシンにサンプルアプリのレポジトリのクローンを作成します。
```
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
```
サンプルコードが入っているディレクトリに移動します。
```
cd cloud-tasks/
```

Cloud 関数のデプロイ

function/ ディレクトリに移動します。
```
cd function/
```
関数をデプロイします。
```
gcloud functions deploy sendEmail --runtime nodejs14 --trigger-http \
  --no-allow-unauthenticated \
  --set-env-vars SENDGRID_API_KEY=SENDGRID_API_KEY \
```
SENDGRID_API_KEY を API キーに置き換えます。

このコマンドでは、次のフラグを使用します。
- --trigger-http は Cloud Functions のトリガータイプを指定します。
- --no-allow-unauthenticated は関数呼び出しを指定するには認証が必要です。
- --set-env-var は SendGrid 認証情報を設定します。
注: Cloud Functions は、Firebase と Google Cloud コンソールの両方から管理できます。FirebaseUI からの書き込みとデプロイは複製できます。ただし、関数コードは Firebase Functions フレームワークと一致する必要があります。詳しくは、Firebase Functions と HTTP トリガーのスタートガイドをご覧ください。
認証されたユーザーだけを許可するように、関数へのアクセス制御を設定します。
1. Cloud Functions UI で sendEmail 関数を選択します。
2. sendEmail の権限情報が表示されない場合は、右上隅にある [情報パネルを表示] をクリックします。
3. 上の [プリンシパルを追加] ボタンをクリックします。
4. [新しいプリンシパル] を allAuthenticatedUsers に設定します。
5. [ロール] を設定します。
  - 第 1 世代の関数: ロールを Cloud Function Invoker に設定します。
  - 第 2 世代の関数: ロールを Cloud Run Invoker に設定します。
6. [保存] をクリックします。

Cloud Tasks キューの作成

次の gcloud コマンドを使用して、キューを作成します。
```
gcloud tasks queues create my-queue --location=LOCATION
```
LOCATION は、キューの目的のロケーション（us-west2 など）に置き換えます。ロケーションを指定しない場合は、gcloud CLI によってデフォルトが選択されます。
正常に作成されたことを確認します。
```
gcloud tasks queues describe my-queue --location=LOCATION
```
LOCATION は、キューのロケーションに置き換えます。

サービスアカウントの作成

Cloud Tasks リクエストでは、Cloud Function がリクエストを認証するための認証情報を Authorization ヘッダーで指定する必要があります。このサービスアカウントで、その目的のために Cloud Tasks で OIDC トークンを作成して追加できます。

[サービスアカウント] ページで、[サービスアカウントを作成] をクリックします。
サービスアカウント名（わかりやすい表示名）を追加し、[作成] を選択します。
[ロール] を設定し、[続行] をクリックします。
- 第 1 世代の関数: ロールを Cloud Function Invoker に設定します。
- 第 2 世代の関数: ロールを Cloud Run Invoker に設定します。
[完了] を選択します。

エンドポイントとタスク作成者の App Engine へのデプロイ

app/ ディレクトリに移動します。
```
cd ../app/
```

app.yaml の変数を実際の値で更新します。

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"

キューのロケーションを探すには、次のコマンドを使用します。

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

LOCATION は、キューのロケーションに置き換えます。

関数の URL を探すには、次のコマンドを使用します。

gcloud functions describe sendEmail

次のコマンドを使用して、アプリケーションを App Engine スタンダード環境にデプロイします。
```
gcloud app deploy
```
アプリケーションを開き、ポストカードをメールで送信します。
```
gcloud app browse
```

クリーンアップ

チュートリアルが終了したら、作成したリソースをクリーンアップして、割り当ての使用を停止し、課金されないようにできます。次のセクションで、リソースを削除または無効にする方法を説明します。

リソースの削除

Google Cloud で作成したリソースをクリーンアップして、今後料金が発生しないようにします。次のセクションで、このようなリソースを削除または無効にする方法を説明します。

Cloud 関数の削除

Google Cloud コンソールの [Cloud Functions] ページに移動します。

[Cloud Functions] ページに移動
関数の横にあるチェックボックスをクリックします。
ページの上部にある [削除] ボタンをクリックして、削除操作を確定します。

Cloud Tasks キューの削除

Console で Cloud Tasks キューのページを開きます。

Cloud Tasks キューのページに移動
削除するキューの名前を選択し、[キューの削除] をクリックします。
処理を確認します。

注: Google Cloud コンソールからキューを削除した後に同じ名前で再度作成する場合は、再作成する前に 7 日間待つ必要があります。

プロジェクトの削除

課金をなくす最も簡単な方法は、チュートリアル用に作成したプロジェクトを削除することです。

プロジェクトを削除するには:

注意: プロジェクトを削除すると、次のような影響があります。

プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
カスタムプロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタムプロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。

Google Cloud コンソールで、[リソースの管理] ページに移動します。
[リソースの管理] に移動
プロジェクトリストで、削除するプロジェクトを選択し、[削除] をクリックします。
ダイアログでプロジェクト ID を入力し、[シャットダウン] をクリックしてプロジェクトを削除します。

次のステップ

HTTP ターゲットタスクの作成の詳細を学習する。
Cloud Tasks キューの詳細を学習する。