Cloud Functions の使用を開始するには、このチュートリアルに取り組んでみてください。このチュートリアルでは、必要なセットアップ タスクから始めて、2 つの関連する関数の作成、テスト、デプロイを行います。
-
addMessage()
。テキスト値を受け入れて Cloud Firestore に書き込む URL を公開します。 - Cloud Firestore の書き込みでトリガーされ、テキストを大文字に変換する
makeUppercase()
。
このサンプルで Cloud Firestore と HTTP によってトリガーされる JavaScript 関数を選択した理由の 1 つは、これらのバックグラウンド トリガーをFirebase Local Emulator Suiteで徹底的にテストできるためです。このツールセットは、Realtime Database、PubSub、Auth、および HTTP 呼び出し可能トリガーもサポートしています。 Remote Config、TestLab、Analytics トリガーなどの他のタイプのバックグラウンド トリガーはすべて、このページで説明されていないツールセットを使用してインタラクティブにテストできます。
このチュートリアルの次のセクションでは、サンプルのビルド、テスト、デプロイに必要な手順について詳しく説明します。コードを実行して検査するだけの場合は、完全なサンプル コードを確認する にジャンプしてください。
Firebase プロジェクトを作成する
Firebase コンソールで、[プロジェクトを追加] をクリックします。
Firebase リソースを既存のGoogle Cloud プロジェクトに追加するには、そのプロジェクト名を入力するか、プルダウン メニューから選択します。
新しいプロジェクトを作成するには、目的のプロジェクト名を入力します。オプションで、プロジェクト名の下に表示されるプロジェクト ID を編集することもできます。
プロンプトが表示されたら、 Firebase の利用規約を確認して同意します。
[続行]をクリックします。
(オプション)プロジェクトに Google アナリティクスを設定すると、次の Firebase 製品のいずれかを使用して最適なエクスペリエンスを得ることができます。
既存のGoogle アナリティクス アカウントを選択するか、新しいアカウントを作成します。
新しいアカウントを作成する場合は、アナリティクス レポートの場所を選択し、プロジェクトのデータ共有設定と Google アナリティクスの利用規約に同意してください。
[プロジェクトを作成] をクリックします(または、既存の Google Cloud プロジェクトを使用している場合はFirebase を追加します)。
Firebase は、Firebase プロジェクトのリソースを自動的にプロビジョニングします。プロセスが完了すると、Firebase コンソールに Firebase プロジェクトの概要ページが表示されます。
Node.js と Firebase CLI を設定する
関数を作成するにはNode.js環境が必要です。関数を Cloud Functions ランタイムにデプロイするには、Firebase CLI が必要です。 Node.js とnpmのインストールには、 Node Version Managerが推奨されます。
Node.js と npm をインストールしたら、好みの方法で Firebase CLIをインストールします。 npm 経由で CLI をインストールするには、次を使用します。
npm install -g firebase-tools
これにより、グローバルに使用可能な firebase コマンドがインストールされます。コマンドが失敗した場合は、 npm 権限の変更が必要になる場合があります。 firebase-tools
の最新バージョンに更新するには、同じコマンドを再実行します。
プロジェクトを初期化する
Firebase SDK for Cloud Functions を初期化するときは、依存関係といくつかの最小限のサンプル コードを含む空のプロジェクトを作成し、関数を作成するために TypeScript または JavaScript のいずれかを選択します。このチュートリアルでは、Cloud Firestore も初期化する必要があります。
プロジェクトを初期化するには:
-
firebase login
を実行してブラウザ経由でログインし、Firebase CLI を認証します。 - Firebase プロジェクト ディレクトリに移動します。
-
firebase init firestore
を実行します。このチュートリアルでは、Firestore ルールとインデックス ファイルを求めるプロンプトが表示されたら、デフォルト値を受け入れることができます。このプロジェクトで Cloud Firestore をまだ使用していない場合は、Cloud Firestore の開始方法で説明されているように、Firestore の開始モードと場所も選択する必要があります。 -
firebase init functions
を実行します。 CLI により、既存のコードベースを選択するか、新しいコードベースを初期化して名前を付けるように求められます。始めたばかりの場合は、既定の場所にある単一のコードベースで十分です。後で、実装が拡大するにつれて、関数を codebases に編成することが必要になる場合があります。 CLI には、言語サポートの 2 つのオプションがあります。
- JavaScript
- 詳細については、TypeScript を使用した関数の記述を参照してください。
このチュートリアルでは、 JavaScriptを選択します。
CLI には、npm を使用して依存関係をインストールするオプションがあります。別の方法で依存関係を管理したい場合は断っても安全ですが、断る場合は、関数をエミュレートまたはデプロイする前に
npm install
を実行する必要があります。
これらのコマンドが正常に完了すると、プロジェクト構造は次のようになります。
myproject
+- .firebaserc # Hidden file that helps you quickly switch between
| # projects with `firebase use`
|
+- firebase.json # Describes properties for your project
|
+- functions/ # Directory containing all your functions code
|
+- .eslintrc.json # Optional file containing rules for JavaScript linting.
|
+- package.json # npm package file describing your Cloud Functions code
|
+- index.js # main source file for your Cloud Functions code
|
+- node_modules/ # directory where your dependencies (declared in
# package.json) are installed
初期化中に作成されたpackage.json
ファイルには、重要なキー"engines": {"node": "16"}
が含まれています。これにより、関数を作成およびデプロイするための Node.js のバージョンが指定されます。サポートされている他のバージョンを選択できます。
必要なモジュールをインポートしてアプリを初期化する
セットアップ タスクが完了したら、次のセクションで説明するように、ソース ディレクトリを開いてコードの追加を開始できます。このサンプルでは、Node のrequire
ステートメントを使用して、プロジェクトで Cloud Functions と Admin SDK モジュールをインポートする必要があります。次のような行をindex.js
ファイルに追加します。
// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers. const functions = require('firebase-functions'); // The Firebase Admin SDK to access Firestore. const admin = require('firebase-admin'); admin.initializeApp();
これらの行は、 firebase-functions
およびfirebase-admin
モジュールをロードし、Cloud Firestore の変更を行うことができるadmin
アプリ インスタンスを初期化します。 FCM、Authentication、Firebase Realtime Database など、 Admin SDKのサポートが利用できる場所であればどこでも、Cloud Functions を使用して Firebase を統合する強力な方法を提供します。
Firebase CLI は、プロジェクトを初期化するときに、Cloud Functions Node モジュール用の Firebase および Firebase SDK を自動的にインストールします。プロジェクトにサードパーティ ライブラリを追加するには、 package.json
を変更してnpm install
を実行します。詳細については、依存関係の処理を参照してください。
addMessage()
関数を追加する
addMessage()
関数については、次の行をindex.js
に追加します。
// Take the text parameter passed to this HTTP endpoint and insert it into // Firestore under the path /messages/:documentId/original exports.addMessage = functions.https.onRequest(async (req, res) => { // Grab the text parameter. const original = req.query.text; // Push the new message into Firestore using the Firebase Admin SDK. const writeResult = await admin.firestore().collection('messages').add({original: original}); // Send back a message that we've successfully written the message res.json({result: `Message with ID: ${writeResult.id} added.`}); });
addMessage()
関数は HTTP エンドポイントです。エンドポイントへのすべてのリクエストは、 onRequest()
コールバックに渡される ExpressJS スタイルのRequestおよびResponseオブジェクトになります。
HTTP 関数は同期的であるため (呼び出し可能な関数に似ています)、できるだけ早く応答を送信し、Cloud Firestore を使用して作業を延期する必要があります。 addMessage()
HTTP 関数は、テキスト値を HTTP エンドポイントに渡し、データベースのパス/messages/:documentId/original
に挿入します。
makeUppercase()
関数を追加する
makeUppercase()
関数については、次の行をindex.js
に追加します。
// Listens for new messages added to /messages/:documentId/original and creates an // uppercase version of the message to /messages/:documentId/uppercase exports.makeUppercase = functions.firestore.document('/messages/{documentId}') .onCreate((snap, context) => { // Grab the current value of what was written to Firestore. const original = snap.data().original; // Access the parameter `{documentId}` with `context.params` functions.logger.log('Uppercasing', context.params.documentId, original); const uppercase = original.toUpperCase(); // You must return a Promise when performing asynchronous tasks inside a Functions such as // writing to Firestore. // Setting an 'uppercase' field in Firestore document returns a Promise. return snap.ref.set({uppercase}, {merge: true}); });
Cloud Firestore への書き込み時にmakeUppercase()
関数が実行されます。 ref.set
関数は、リッスンするドキュメントを定義します。パフォーマンス上の理由から、できるだけ具体的に指定する必要があります。
{documentId}
などの中かっこは、一致するデータをコールバックで公開する「パラメータ」ワイルドカードを囲みます。
Cloud Firestore は、新しいメッセージが追加されるたびにonCreate()
コールバックをトリガーします。
Cloud Firestore イベントなどのイベント ドリブン機能は非同期です。コールバック関数は、 null
、 Object 、またはPromiseのいずれかを返す必要があります。何も返さない場合、関数はタイムアウトになり、エラーが通知され、再試行されます。同期、非同期、および Promiseを参照してください。
関数の実行をエミュレートする
Firebase Local Emulator Suiteを使用すると、Firebase プロジェクトにデプロイする代わりに、ローカル マシンでアプリをビルドしてテストできます。開発中にローカルでテストすることを強くお勧めします。これは、実稼働環境でコストが発生する可能性があるコーディング エラー (たとえば、無限ループ) のリスクを軽減するためでもあります。
関数をエミュレートするには:
firebase emulators:start
を実行し、Emulator Suite UI の URL の出力を確認します。デフォルトはlocalhost:4000ですが、マシンの別のポートでホストされている場合があります。その URL をブラウザーに入力して、Emulator Suite UI を開きます。HTTP 関数
addMessage()
の URL については、firebasefirebase emulators:start
コマンドの出力を確認してください。http://localhost:5001/MY_PROJECT/us-central1/addMessage
に似ていますが、次の点が異なります。-
MY_PROJECT
はプロジェクト ID に置き換えられます。 - ポートは、ローカル マシンでは異なる場合があります。
-
関数の URL の末尾にクエリ文字列
?text=uppercaseme
を追加します。これはhttp://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme
。必要に応じて、メッセージ「uppercaseme」をカスタム メッセージに変更できます。ブラウザの新しいタブで URL を開いて、新しいメッセージを作成します。
Emulator Suite UI で関数の効果を表示します。
[ログ] タブに、関数
addMessage()
およびmakeUppercase()
が実行されたことを示す新しいログが表示されます。i 関数: 「addMessage」の実行開始
i 関数: 「makeUppercase」の実行開始
[ Firestore ] タブに、元のメッセージと大文字バージョンのメッセージを含むドキュメントが表示されます (元のメッセージが「uppercaseme」だった場合は、「UPPERCASEME」と表示されます)。
関数を本番環境にデプロイする
関数がエミュレーターで目的どおりに機能したら、運用環境での展開、テスト、および実行に進むことができます。推奨される Node.js 14 ランタイム環境にデプロイするには、プロジェクトがBlaze 料金プランに含まれている必要があることに注意してください。 Cloud Functions の料金を参照してください。
チュートリアルを完了するには、関数をデプロイし、 addMessage() を実行してmakeUppercase()
addMessage()
をトリガーします。
次のコマンドを実行して、関数をデプロイします。
firebase deploy --only functions
このコマンドを実行すると、Firebase CLI はすべての HTTP 関数エンドポイントの URL を出力します。ターミナルに、次のような行が表示されます。
Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
URL には、プロジェクト ID と HTTP 関数のリージョンが含まれています。今は心配する必要はありませんが、一部の運用 HTTP 関数では、ネットワークの待機時間を最小限に抑えるために場所を指定する必要があります。
「プロジェクトへのアクセスを承認できません」などのアクセス エラーが発生した場合は、プロジェクトのエイリアシングを確認してください。
CLI によって出力された
addMessage()
URL を使用して、テキスト クエリ パラメータを追加し、ブラウザで開きます。https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
この関数が実行され、テキスト文字列が保存されているデータベースの場所にある Firebase コンソールにブラウザがリダイレクトされます。この書き込みイベントは、文字列の大文字バージョンを書き込む
makeUppercase()
をトリガーします。
関数をデプロイして実行したら、 Google Cloud Consoleでログを表示できます。開発中または本番環境で関数を削除する必要がある場合は、Firebase CLI を使用してください。
本番環境では、実行するインスタンスの最小数と最大数を設定することで、関数のパフォーマンスを最適化し、コストを制御したい場合があります。これらのランタイム オプションの詳細については、スケーリング動作の制御を参照してください。
完全なサンプル コードを確認する
関数addMessage()
とmakeUppercase()
) を含む完成したfunctions/index.js
を次に示します。これらの関数を使用すると、値を Cloud Firestore に書き込み、文字列内のすべての文字を大文字にして変換する HTTP エンドポイントにパラメータを渡すことができます。
// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers. const functions = require('firebase-functions'); // The Firebase Admin SDK to access Firestore. const admin = require('firebase-admin'); admin.initializeApp(); // Take the text parameter passed to this HTTP endpoint and insert it into // Firestore under the path /messages/:documentId/original exports.addMessage = functions.https.onRequest(async (req, res) => { // Grab the text parameter. const original = req.query.text; // Push the new message into Firestore using the Firebase Admin SDK. const writeResult = await admin.firestore().collection('messages').add({original: original}); // Send back a message that we've successfully written the message res.json({result: `Message with ID: ${writeResult.id} added.`}); }); // Listens for new messages added to /messages/:documentId/original and creates an // uppercase version of the message to /messages/:documentId/uppercase exports.makeUppercase = functions.firestore.document('/messages/{documentId}') .onCreate((snap, context) => { // Grab the current value of what was written to Firestore. const original = snap.data().original; // Access the parameter `{documentId}` with `context.params` functions.logger.log('Uppercasing', context.params.documentId, original); const uppercase = original.toUpperCase(); // You must return a Promise when performing asynchronous tasks inside a Functions such as // writing to Firestore. // Setting an 'uppercase' field in Firestore document returns a Promise. return snap.ref.set({uppercase}, {merge: true}); });
次のステップ
このドキュメントでは、Cloud Functions の一般的な概念に関する詳細情報と、Cloud Functions でサポートされるイベント タイプを処理する関数を作成するためのガイドを見つけることができます。
Cloud Functions について詳しく知るには、次のこともできます。
- Cloud Functions のユース ケースについてお読みください。
- Cloud Functions コードラボをお試しください。
- GitHub でコード サンプルを確認して実行します。
- API リファレンスを確認してください。
ビデオチュートリアル
Cloud Functions の詳細については、ビデオ チュートリアルをご覧ください。このビデオでは、Node.js や CLI のセットアップなど、Cloud Functions の使用を開始するための詳細なガイダンスをご覧いただけます。