【Google Cloud / Node.js】Cloud SchedulerをAPI経由で使ってみる #JavaScript

はじめに

Firebase をバックエンドに使ったWebアプリの開発にあたり
「定期実行されるcronサービスを使いたい」
「クライアントアプリからジョブを設定したい(API使いたい)」
と思い、調べたところ Google Cloud Platform の Cloud Scheduler が良さげさったので使ってみました。

cronサービスは他にもいくつかありますが、Cloud Schedulerの特徴としては

無料枠がある（1アカウントあたり3タスク）
APIが提供されており、HTTP経由でジョブの設定、変更が可能である
GCPの他のサービスとの親和性が高い※

などかなと思います。

※ Cloud Functions for Firebaseであれば、Cloud Schedulerの機能をラップしたメソッドを使って定期実行ができるそうです。参考: Firebase Cloud Functionsの定期実行が、それ単体で簡単にできるようになった！ - Qiita

本記事は、Node.jsでCloud SchedulerジョブをAPIを使って設定し、 Cloud Functions for Firebase を実行する方法の備忘録です。

事前準備

GCPに登録

Cloud Schedulerは Google Cloud Platform が提供するサービスです。無料使用枠はありますが使用には登録が必要なため、予め登録しておきましょう。
登録完了後、APIを使うためのプロジェクトを作成してください。

APIを有効化

APIを使用するため、コンソールのAPIライブラリからCloud Schedulerを検索しAPIを有効化しておきます。
今回はCloud FunctionsもAPI経由で実行するため、Cloud Functions APIも有効化しましょう。

Google Cloud API認証用の環境設定

Google Cloud APIの使用にはOAuth認証が必須です。
事前にGCPのサービスアカウントと、秘密鍵を含むJSONファイルを作成し、それを用いて認証を行います。
こちらを参考に、サービスアカウントの作成〜環境変数の設定までを実施します。

Cloud Pub/Sub の設定

Cloud Schedulerでジョブを作成する際、定期実行するジョブの種類（ターゲット）を以下の選択肢から設定する必要があります。

Cloud Pub/Sub
HTTP
App Engine HTTP

今回はCloud Scheduler → Cloud Pub/Sub → Cloud Functions の順で実行するので、予めPub/Subの設定と実行される関数を準備しておきます。
まず、最終的に実行されるCloud Functionsの関数を functions.pubsub で作成します。トピック名は後ほど設定します。

const functions = require('firebase-functions');

exports.handlePubSubTrigger = functions
  // トリガーとなるPub/Subのトピックを指定する
  .pubsub.topic('[トピック名]')
  // Pub/SubからPUSHがあったときの処理
  .onPublish(async (event, context) => {
    const pubsubMessage = event.data;
    console.log(Buffer.from(pubsubMessage, 'base64').toString());
  });

次に、前段で作成した関数をトリガーするPub/Subのトピックおよびサブスクリプションを作成します。作成は Google Cloud SDK からCLIで作成できるほか、GCPのコンソール画面からも作成可能です。こちらを参照しつつ

トピック作成後、トピック名を実行する関数に設定
サブスクリプションのエンドポイントURLに実行する関数のURLを指定

を行います。

APIを使ってみる

事前準備が完了したら、実際にCloud Scheduler APIを使ってジョブを作成してみます。
なお、Google Cloud API リクエストの実装方法として
1. 単純にHTTPリクエストを発行する
2. クライアントライブラリ( Google APIs Node.js Client )を使う

の2パターンあり、今回は使い勝手のいい後者を採用します。
ジョブ作成するCloud Functionsの関数は以下になります。プロセスとしては、

GCPのOAuth認証
Cloud Schedulerジョブの新規作成(APIのリクエスト)

の2つです。

const functions = require('firebase-functions');
const { google } = require('googleapis');

exports.createSchedulerJob = functions.https.onRequest(
  async (req, res) => {
    // ①GCPのOAuth認証
    const client = await google.auth.getClient({
      scopes: ['https://www.googleapis.com/auth/cloud-platform'],
    });

    // ②ジョブの新規作成
    const projectId = '[PROJECT_ID]'; // プロジェクトID
    const locationId = '[LOCATION_ID]'; // ロケーション名(Cloud Functionsのデフォルトはus-central1)
    const topicName = '[TOPIC_NAME]'; // トリガーするPub/Subのトピック名
    const jobName = '[JOB_NAME]'; //作成するCronジョブ名

    const request = {
      parent: `projects/${projectId}/locations/${locationId}`,
      resource: {
        name: `projects/${projectId}/locations/${locationId}/jobs/${jobName}`,
        schedule: '0 7 * * 1-5', // 定期実行する時刻 今回は月~金のAM7:00に設定
        pubsubTarget: {
          topicName: `projects/${projectId}/topics/${topicName}`,
          data:  Buffer.from('Cron triggered.').toString('base64'),
        },
      },
      auth: client,
    };
    // APIリクエスト
    cloudScheduler.projects.locations.jobs.create(request, (err, response) => {
      if (err) {
        console.error(err);
        return;
      }
      return response.data;
    });
  },
);

① GCPのOAuth認証

まず、クライアントライブラリのauth.getClient()メソッドを使ってOAuth認証を行います。

このとき、scopesの設定が必要になります。
スコープとはアプリケーションに許可するAPI操作の権限の範囲で、これを認証時に明記する必要があります。
各APIに必要なスコープはAPIのドキュメントにAuthorization Scopesとして記載されています。今回はCloud Schedulerに必要なhttps://www.googleapis.com/auth/cloud-platformを指定します。

const client = await google.auth.getClient({
  scopes: ['https://www.googleapis.com/auth/cloud-platform'],
});

補足ですが、auth.getClient()は開発環境において前段で準備した秘密鍵のJSONファイルをよしなに参照してくれるので、コード内で認証ファイルをインポートするなどの必要はありません。クライアントライブラリを使うのにはこうした利点があります。

② Cloud Schedulerジョブの新規作成

OAuth認証後、Cloud Schedulerのジョブを作成します。ジョブの作成には projects.locations.jobs.create を使います。

リクエストとして以下の項目を設定します。

parent …ジョブを作成するプロジェクト。
resource.name …ジョブの名前。projects/~で始まるパスの形で設定。
resource.schedule … ジョブの設定時刻。 unix-cron 文字列形式で設定。
resource.pubsubTarget … トリガーするPub/Subトピックの設定。topicNameとdataを必須で設定する。dataはBase64エンコードする。
auth … 前段で取得した認証情報

なお、resource.pubsubTarget の箇所はトリガーするターゲットに応じてプロパティが変わるので注意してください。

const projectId = '[PROJECT_ID]'; // プロジェクトID
const locationId = '[LOCATION_ID]'; // ロケーション名(Cloud Functionsのデフォルトはus-central1)
const topicName = '[TOPIC_NAME]'; // トリガーするPub/Subのトピック名
const jobName = '[JOB_NAME]'; //作成するCronジョブ名

const request = {
  parent: `projects/${projectId}/locations/${locationId}`,
  resource: {
    name: `projects/${projectId}/locations/${locationId}/jobs/${jobName}`,
    schedule: '0 7 * * 1-5', // 定期実行する時刻 今回は月~金のAM7:00に設定
    pubsubTarget: {
      topicName: `projects/${projectId}/topics/${topicName}`,
      data:  Buffer.from('Cron triggered.').toString('base64'),
    },
  },
  auth: client,
};
// APIリクエスト
cloudScheduler.projects.locations.jobs.create(request, (err, response) => {
  if (err) {
    console.error(err);
    return;
  }
  return response.data;
});
},

無事ジョブが作成されると、レスポンスで作成されたジョブの情報が返却されます。

③ ジョブの変更

一度作成したジョブを変更する際は projects.locations.jobs.patch を使います。
以下の例では、先程作成したジョブの設定時刻を7時から8時に変更します。

const client = await google.auth.getClient({
  scopes: ['https://www.googleapis.com/auth/cloud-platform'],
});
const projectId = '[PROJECT_ID]'; // プロジェクトID
const locationId = '[LOCATION_ID]'; // ロケーション名(Cloud Functionsのデフォルトはus-central1)
const jobName = '[JOB_NAME]'; // 更新するCronジョブ名

const request = {
  name: `projects/${projectId}/locations/${locationId}/jobs/${jobName}`,
  updateMask: 'schedule',
  resource: {
    schedule: '0 8 * * 1-5', // AM8:00に設定変更
  },
  auth: client,
};

cloudScheduler.projects.locations.jobs.patch(request, (err, response) => {
  if (err) {
    console.error(err);
    return;
  }
  return response.data;
});

作成時と異なるのはpubsubTargetが不要となる点と、リクエストにupdateMaskを指定する点です。
updateMaskはジョブのどのフィールドを更新するかを指定するパラメータです。設定しないと更新されないので必ず設定します。

おわりに

API経由でcronジョブをスケジューリングするような記事があまりなかったので、参考になれば幸いです。
内容に誤りや改善点があればコメントいただけるとありがたいです！

【Google Cloud / Node.js】Cloud SchedulerをAPI経由で使ってみる