Firebase Cloud Functions — 概要、トリガー、関数の書き方

Firebase Cloud Functionsとは何か、どのように機能するか

Firebase Cloud Functionsは、Google Cloud Functions（GCF）上に構築されたコンピューティングプラットフォームで、Firebaseエコシステムに適応しています。関数は、モジュールからエクスポートされ、特定のイベントタイプに登録された通常のJavaScriptまたはTypeScriptコードです。イベントが発生すると（例えば、ユーザーが登録したりファイルをアップロードしたりすると）、Firebase Cloud Functionsは対応するコードを実行し、イベントコンテキストを渡します。

Cloud Functionsのアーキテクチャは単一責任の原則に従います。1つの関数が1つのイベントタイプを処理し、1つのアトミック操作を実行します。例えば、sendWelcomeEmail関数はFirebase Authenticationで新しいユーザーが作成されたときにトリガーされ、ウェルカムメールを送信します。この分離により、デバッグ、テスト、および異なるプロジェクト間での関数の再利用が容易になります。

各関数は、一時的なライフサイクルを持つ分離されたコンテナで実行されます。最大実行時間のデフォルトは60秒です（HTTPS関数の場合は9分）。関数がタイムアウト内に完了しない場合、リクエストはエラー500で失敗します。長時間実行される操作には、再試行付きのCloud TasksまたはPub/Subを使用します。コンテナは後続の呼び出しで再利用（keep-alive）できるため、最初の呼び出し後のコールドスタートのレイテンシが低減されます。

実行環境とNode.jsのバージョン

Firebase Cloud Functionsは、Node.js 18、20、22（新しいプロジェクトでは推奨）の複数のバージョンをサポートしています。バージョンはpackage.jsonファイルのenginesフィールドで指定します。Firebase CLIは、指定されたバージョンに基づいて実行環境を自動的に設定します。重要な点：Firebase Cloud Functionsは任意のDockerコンテナの実行をサポートしていません — 環境はGoogle Cloud Functionsによって厳密に固定されています。

新しいプロジェクトでは、Node.js 22を推奨します。これには最新のV8最適化、改善されたESMモジュールサポート、プラットフォームレベルのWebSocketサポートが含まれています。特定のNodeバージョン用にビルドされた依存関係（ネイティブC++モジュールなど）を使用するプロジェクトでは、互換性を個別に確認する必要があります — すべてのネイティブモジュールがGCF環境でコンパイルされるわけではありません。

Firebase Cloud FunctionsとGoogle Cloud Functionsの違い

Firebase Cloud Functionsは、Google Cloud Functionsのラッパーで、Firebase SDKがプリインストールされ、Firebaseサービスとの統合が含まれています。開発者はfirebase-functions SDKを使用してコードを記述し、すべてのFirebaseサービスに対して型指定されたトリガーを提供します。Google Cloud Functionsはより低レベルのプラットフォームで、トリガーはEventarcまたはPub/Subを介して明示的に設定されます。

主な違い：Firebase Cloud Functionsでは、トリガーはfunctions.firestore.document('path').onWrite()を介して宣言的に登録されますが、Google Cloud Functionsではイベント属性フィルタリングを使用してEventarcを介して設定されます。Firebase Cloud Functionsには、プロジェクトのサービスアカウント認証情報で自動的に初期化されるAdmin SDKも付属しており、追加設定なしですべてのFirebaseサービスへの完全なアクセスを提供します。

トリガーの種類：サポートされるイベント

Firebase Cloud Functionsは8カテゴリのトリガーをサポートしており、それぞれが特定のFirebaseまたはGoogle Cloudサービスに対応しています。トリガーとは、条件が満たされたときに関数を自動的に呼び出す条件です。開発者は関数のライフサイクルを直接管理しません。Firebase CLIがGoogle Cloud Eventarcにトリガーを登録し、イベントが発生するとクラウドプラットフォームが関数を実行します。

最も人気のあるトリガーはFirestoreトリガー（onWrite、onCreate、onUpdate、onDelete）です。これらはFirestoreコレクション内のドキュメントが変更されたときに作動します。関数は変更前と変更後のドキュメントのスナップショットを受け取り、値を比較して特定の変更にのみ応答できます。例えば、注文ステータスが“保留中”から“発送済み”に変更された場合、ユーザーにプッシュ通知を送信できます。

Authenticationトリガー（onCreate、onDelete）は、ユーザーアカウントが作成または削除されたときに作動します。これらはユーザーデータの初期化（Firestoreでのユーザードキュメントの作成、ウェルカムメールの送信、分析への書き込み）に使用されます。注意：関数はユーザー作成をキャンセルできません — アカウントが既に作成された後に実行されます。事前検証には、Identity Platformで利用可能なBlocking Functionsを使用します。

HTTPSトリガーとCORS

HTTPS関数（onRequest）を使用すると、HTTP経由でアクセス可能な完全なREST APIエンドポイントを作成できます。イベント駆動型トリガーとは異なり、HTTPS関数はhttps://{region}-{project}.cloudfunctions.net/{functionName}形式のURLを介して呼び出されます。エンドポイントがブラウザやモバイルアプリケーションから呼ばれる場合は、CORSを正しく設定することが重要です。Firebase SDKは自動的にCORSヘッダーを含めないため、ミドルウェアを介して手動で追加する必要があります。

モバイルクライアント（Android、iOS）の場合、ネイティブHTTPクライアントはクロスオリジンポリシーによって制限されないため、CORSは必要ありません。CORSはWebリクエストにのみ関連します。HTTPS関数がアプリとWebの両方から呼び出される場合は、開発用にres.set('Access-Control-Allow-Origin', '*')、またはプロダクション用に許可されたドメインのリストを含むユニバーサルCORS処理を追加します。

Pub/SubとCloud Schedulerを使用したスケジューリング

定期的な実行（cronジョブ）には、Cloud SchedulerとPub/Subの組み合わせを使用します。Cloud Schedulerはスケジュールに従ってPub/Subトピックにメッセージを送信し、Cloud FunctionsのonPublishトリガーがそのメッセージを処理します。Firebase CLIは直接的なcron構文をサポートしていません — スケジュールはGoogle CloudコンソールまたはTerraformを介してunix-cron形式（0 3 * * *（毎日3:00））で設定します。

タスクの例：日次ニュースレター、古いデータのクリーンアップ、レポート生成、外部APIとの同期。重要な点：Cloud SchedulerはGoogle Cloudの有料サービスです（1ジョブあたり月額約2ドル）。各トリガーは個別の関数呼び出しとしてカウントされ、標準のCloud Functions料金で請求されます。

関数の作成とデプロイ方法

Cloud Functionsの開発は、Firebase CLIを使用したプロジェクトの初期化から始まります：firebase init functions。このコマンドは、index.js（またはindex.ts）テンプレート、package.jsonファイル、TypeScript設定（選択した場合）を含むfunctions/ディレクトリを作成します。初期化後、関数を記述し、モジュールからエクスポートして、firebase deploy --only functionsを実行してデプロイするだけです。

各関数は、適切なトリガーメソッドを呼び出して登録されます。HTTPS関数の例：exports.helloWorld = functions.https.onRequest((req, res) => { res.send(“Hello!”); })。Firebase Functionsは非同期モデルを使用します。イベント駆動型トリガー（非HTTPS）の場合、関数はPromiseを返す必要があります。Firebaseはコンテナを終了する前にPromiseの完了を待機します。Promiseが返されない場合、非同期操作が完了する前に関数が終了される可能性があります。

ローカル開発はFirebase Emulator Suiteを介して行われ、Cloud Functionsエミュレーターが含まれています。firebase emulators:startコマンドは、http://localhost:5001でアクセス可能な関数を使用してローカルサーバーを起動します。エミュレーターはコード変更時のホットリロードをサポートし、本番環境から完全に分離されているため、実際のデータを危険にさらすことなくテストできます。

依存関係と設定の管理

Cloud Functionsの依存関係はpackage.jsonを介して管理されます。Firebaseは本番依存関係のみをインストールします（dependencies。devDependenciesは除く）。関数パッケージのサイズはコールドスタート時間に影響するため、依存関係の数を最小限に抑えることをお勧めします。Firebase Admin SDKのfirebase-admin依存関係はプリインストールされているため、手動で追加する必要はありません。

機密データ（APIキー、トークン）は関数コードに保存しないでください。設定を保存するにはfunctions.config()を使用します：firebase functions:config:set stripe.key=“sk_...”。値は暗号化され、functions.config().stripe.keyを介して実行時に利用できます。大規模なシリアル化された設定には、Google Cloud Secret Managerを使用します。

エラー処理とロギング

Cloud Functionsでのロギングは、console.log、console.warn、console.errorを介して行われます。すべてのログは自動的にGoogle Cloud Loggingに収集され、Firebaseコンソール（Functions > Logs）で利用できます。構造化ロギングには、JSONフォーマットとログレベルをサポートするwinstonまたはpinoライブラリを使用します。

エラー処理は信頼性にとって非常に重要です。Promiseで未処理の例外が発生すると、関数はエラーで終了し、その後Firebaseが自動的に指数バックオフで再試行します。再試行回数は0から無限大まで設定可能です。イベント駆動型トリガーの場合、外部サービスの一時的な障害でも各イベントが確実に処理されるように、再試行を有効にすることをお勧めします。

コールドスタートとスケーリング

コールドスタートとは、非アクティブ期間後の関数の最初の呼び出し時の遅延で、コードを含むコンテナが再度ロードおよび初期化されます。Firebaseのドキュメント（2026年）によると、コールドスタートはパッケージサイズ、依存関係の数、リージョンに応じて200ミリ秒から2秒かかります。ユーザーインターフェースの場合、1秒を超える遅延は顕著で、ユーザーエクスペリエンスに影響を与える可能性があります。

コールドスタートを最小限に抑える方法：依存関係を最小限にし、CommonJSにコンパイルされたTypeScriptを使用し、関数パッケージのサイズを減らし、アクティブインスタンスの最小数を設定します。Firebase Cloud Functions v2（第2世代）では、minInstances（常にリクエストを処理する準備ができているウォームコンテナの最小数）を設定できます。コンテナをウォームに保つには、アイドル時間に対して課金されます。

Cloud Functionsのスケーリングは自動的に行われます。リクエスト量が増加すると、Firebaseは新しいコンテナを作成します。デフォルトでは、並列インスタンスの最大数は3000です（Google Cloudプロジェクトの割り当て）。各インスタンスは一度に1つのリクエストを処理します。関数が高速（100ミリ秒未満）な場合、1つのインスタンスは1秒あたり最大10リクエストを処理でき、プロジェクトあたり1秒あたり最大30,000リクエストのピークスループットを提供します。

minInstancesとmaxInstancesの設定

minInstancesは、指定された数のコンテナを予約してウォームに保つパラメータです。コールドスタートのレイテンシが許容できない重要なHTTPS関数に推奨されます。例えば、認証エンドポイントの場合はminInstances: 1を設定します。maxInstancesは並列インスタンスの最大数を制限し、突然のトラフィックスパイク時のコストの制御不能な増加を防ぐのに役立ちます。

設定はコード内で行います：functions.runWith({ minInstances: 1, maxInstances: 10 })。重要：minInstancesはコンテナが継続的に実行されるため、コストを増加させます。テストプロジェクトでは、minInstancesを無効にする必要があります。プロダクションでは、すべての公開HTTPS関数にminInstancesを推奨し、1秒の遅延が重要でないイベント駆動型トリガーには0を推奨します。

デプロイリージョン

デプロイリージョンは、エンドユーザーへのレイテンシと送信トラフィックのコストに影響します。Firebase Cloud Functionsは30以上のGoogle Cloudリージョンで利用可能です。モバイルアプリケーションの場合は、ターゲットオーディエンスに最も近いリージョンを選択します：アメリカ大陸の場合はus-central1、ヨーロッパの場合はeurope-west1、アジアの場合はasia-east2。リージョンは関数を再デプロイしないと変更できません。

リージョンの変更は、コード内のregionパラメータを介して行います：functions.region('europe-west1')。1つのファイル内のすべての関数が異なるリージョンを持つことができます。グローバルプロジェクトの場合は、複数のリージョンに関数をデプロイし、トラフィック分散にCloud Load Balancingを使用することをお勧めしますが、ほとんどのモバイルアプリケーションでは、適切に選択されれば1つのリージョンで十分です。

Firebase Cloud Functionsのコード例

TypeScriptでのCloud Functionsの実用的な例を見てみましょう。コードはESモジュール構文のFirebase Functions SDK v2（第2世代）を使用しています。例には、ユーザー作成イベントの処理、画像アップロード時のサムネイル生成、REST API用のシンプルなHTTPSエンドポイントが含まれます。すべての関数は非同期で、適切なコンテナ終了のためにPromiseを返します。

実行する前に、Firebase CLIがバージョン13+に更新されていることを確認してください：npm install -g firebase-tools。v2関数にはBlaze料金プランが必要です。初期化：TypeScriptを選択したfirebase init functions。

ユーザー登録の処理

最初の例は、新しいユーザーが登録したときにFirestoreでドキュメントを作成するものです。関数はauth.user().onCreateイベントによってトリガーされ、users/{uid}コレクションに基本プロファイルを書き込みます。これにより、登録された各ユーザーが必要なフィールドを持つドキュメントを持つことが保証されます。

import * as functions from "firebase-functions"
import * as admin from "firebase-admin"

admin.initializeApp()

export const createUserProfile = functions.auth
    .user()
    .onCreate(async (user) => {
        const profile = {
            email: user.email,
            displayName: user.displayName ?? "User",
            createdAt: admin.firestore.Timestamp.now(),
            role: "free",
            avatarUrl: null,
        }

        await admin.firestore()
            .collection("users")
            .doc(user.uid)
            .set(profile)

        console.log(`Profile created for ${user.uid}`)
    })

createUserProfile関数は非同期で、Firebaseが終了前に待機するPromiseを返します。Firestoreへの書き込みが失敗した場合（例えば、権限不足）、関数は自動的に再試行されます（再試行が有効な場合）。“free”値のroleフィールドは、resource.data.roleを必要なアクセスレベルと比較して、FirestoreのSecurity Rulesで直接無料プランの制限を実装できます。

画像アップロード時のサムネイル生成

2番目の例は、画像アップロード後に自動的にサムネイルを生成するStorageトリガーです。関数は200×200ピクセルの縮小コピーを作成し、thumb_プレフィックスを付けて元のファイルのパスに保存します。画像処理にはsharpライブラリを使用し、すべての一般的な形式をサポートし、システム依存関係なしでNode.js環境で動作します。

import * as path from "path"
import * as os from "os"
import * as sharp from "sharp"

export const generateThumbnail = functions.storage
    .object()
    .onFinalize(async (object) => {
        if (!object.contentType?.startsWith("image/")) return

        const filePath = object.name!
        const thumbPath = filePath.replace(
            /(\.\w+)$/, "_thumb$1"
        )

        const bucket = admin.storage().bucket()
        const tempDir = os.tmpdir()
        const tempFile = path.join(tempDir, path.basename(filePath))

        await bucket.file(filePath).download({ destination: tempFile })
        await sharp(tempFile)
            .resize(200, 200, { fit: "cover" })
            .toFile(tempFile.replace(/(\.\w+)$/, "_thumb$1"))

        await bucket.upload(tempFile.replace(
            /(\.\w+)$/, "_thumb$1"
        ), { destination: thumbPath })
    })

generateThumbnail関数はオブジェクトのContent-Typeをチェックし、画像以外を無視してリソースを節約します。sharpを使用するには、依存関係をpackage.jsonに追加する必要があります。サムネイルはfit: “cover”パラメータで作成され、画像を中央から200×200ピクセルの正方形にトリミングします。作成後、サムネイルは変更された名前で同じバケットにアップロードされます。

公開API用のHTTPSエンドポイント

3番目の例は、サーバーステータスを確認するためのREST APIエンドポイントを実装するHTTPS関数です。関数はGETリクエストを受け入れ、プロジェクトに接続されたFirebaseサービスの状態に関するJSONを返します。このエンドポイントは、データを送信する前にバックエンドの可用性を確認する必要がある監視や外部システムに役立ちます。

import * as express from "express"

const app = express.Router()

app.get("/status", async (req, res) => {
    try {
        const db = admin.firestore()
        await db.collection("_health").doc("check").get()
        res.json({ status: "ok", timestamp: Date.now() })
    } catch (error) {
        res.status(503).json({ status: "error", message: error })
    }
})

export const api = functions.https.onRequest(app)

api関数はルーティングにexpress Routerを使用しており、1つの関数で複数のエンドポイントを作成する場合に便利です。ヘルスチェックは_healthコレクションのFirestoreに書き込み、Firestoreの可用性を同時に確認できます。本番環境では、公開エンドポイントの悪用を防ぐために、APIキーまたはFirebase Authトークンによるリクエスト認証を追加することをお勧めします。

モバイルアプリケーションでの典型的なユースケース

Cloud Functionsは、クライアントで実行できない、または実行すべきでないタスクに最もよく使用されます：プッシュ通知の送信、アップロードされた画像のプレビュー生成、外部決済システムとの統合、コンテンツモデレーション、Firebaseとサードパーティサービス間のデータ同期。サーバーレスモデルにより、これらのタスクはコスト効率が高くなります。実際のコード実行時間に対してのみ支払います。

決済システムの統合は、アプリ内購入を含むアプリの典型的なシナリオです。Cloud Functionsは決済プロバイダー（Stripe、PayPal）からWebhookを受信し、リクエストの署名を検証し、Firestoreのサブスクリプションステータスを更新し、ユーザーに確認を送信します。すべてのコードはサーバー上で実行され、クライアントでのデータ改ざんのリスクはありません。Stripeのドキュメント（2026年）によると、Webhook処理には500ミリ秒未満かかります。

スマートコンテンツモデレーションは、Cloud Function Storageトリガーを使用して、Google Cloud Vision APIを介してアップロードされた画像を自動的にチェックします。関数は画像をVision APIに送信して不適切なコンテンツ（暴力、アダルトコンテンツ）を検出し、しきい値を超えた場合はファイルを削除して管理者に通知します。このシナリオは、ユーザーギャラリーを持つUGCアプリケーションにとって重要です。

データ集約 — Firebase Realtime Databaseカウンターの代替としてのCloud Functions。クライアントでカウンターを読み書きする（競合状態を引き起こす）代わりに、FirestoreのonWriteトリガーを使用して集約フィールドをアトミックに更新します。例えば、関数は/posts/{postId}/likes/{userId}サブコレクションでドキュメントが追加または削除されるたびに投稿のいいね数をカウントし、親ドキュメントのlikesCountフィールドを更新します。