Node.js で依存関係を指定する
関数では、ローカルデータだけでなく、外部の Node.js モジュールも使用できます。Node.js における依存関係は、npm で管理され、package.json
というメタデータ ファイルで表現されます。Cloud Run functions の Node.js ランタイムは、npm、yarn、pnpm を使用したインストールをサポートしています。
関数の依存関係を指定するには、package.json
ファイルにその依存関係を追加します。
この例では、依存関係は package.json
ファイルにリストされています。
{ "dependencies": { "escape-html": "^1.0.3" } }
依存関係は関数にインポートされます。
Functions Framework は、すべての関数に必須の依存関係です。Cloud Run functions は、関数の作成時にユーザーの代理でこの依存関係をインストールしますが、明確化のため明示的な依存関係として含めておくことをおすすめします。
関数がプライベート依存関係を利用している場合は、functions-framework
をプライベート レジストリにミラーリングすることをおすすめします。ミラーリング対象の functions-framework
を依存関係として関数に含めることで、公共のインターネットからパッケージがインストールされないようにします。
npm
を使用してローカルで Node.js モジュールをインストールする
ローカルで Node.js モジュールをインストールする特に簡単な方法は、Cloud Run 関数のあるフォルダで npm install
コマンドを使用することです。たとえば、次のコマンドは uuid
モジュールを追加します。
npm install uuid
これは、次の 2 つのステップを組み合わせたものです。
package.json
ファイルで、モジュールの最新バージョンを依存関係としてマークします。これは非常に重要です。Cloud Run functions では、package.json
ファイルで宣言されたモジュールのみがインストールされます。- モジュールを
node_modules
ディレクトリにダウンロードします。これにより、モジュールをローカルでの開発に使用できます。
マシンに npm がインストールされていない場合は、npm を入手します。
デプロイの依存関係の構成
NPM、Yarn、Pnpm の本番環境の依存関係をインストールできます。
NPM
関数をデプロイする際、Cloud Run functions は npm install
コマンドを使用して、package.json
ファイル内で宣言されている依存関係をインストールします。
npm install --production
Yarn
Node.js 8 以降のランタイムでは、yarn.lock
ファイルが存在する場合は、Cloud Run functions では代わりに yarn install
コマンドが使用されます。
yarn install --production
Pnpm
Node.js 8 以降のランタイムでは、pnpm-lock.yaml
ファイルが存在する場合は、Cloud Run functions では代わりに pnpm install
コマンドが使用されます。
pnpm install
デプロイ時にカスタムビルド ステップを実行する
デプロイした後、package.json
ファイルに gcp-build
スクリプトを追加すると、関数のビルドプロセス中にカスタム ビルドステップを実行できます。
このスクリプトの実行時には、package.json
ファイルの dependencies
フィールドと devDependencies
フィールドの依存関係を利用できます。カスタムビルド ステップが実行された後、Cloud Run functions は package.json
ファイルの dependencies
フィールドで宣言されている本番環境の依存関係のみをインストールし、node_modules
フォルダを削除して生成し直します。
package.json
に gcp-build
スクリプトがない場合、Cloud Run 関数は本番環境の依存関係をインストールするだけです。
システム パッケージの使用
Node.js ランタイムでは、実行環境に多数のシステム パッケージが含まれています。リストされていないパッケージが必要な依存関係が関数で使用されている場合は、パッケージをリクエストできます。
ローカル Node.js モジュールを含める
関数の一部としてローカルの Node.js モジュールを含めることもできます。そのためには、file:
接頭辞を使用してモジュールを package.json
で宣言します。次の例では、mymodule
はモジュール名を指し、mymoduledir
はモジュールを含むディレクトリを指します。
{ "dependencies": { "mymodule": "file:mymoduledir" } }
このローカル モジュールのコードは、関数のルート ディレクトリ内にある node_modules
フォルダ以外の場所に保存する必要があります。
Node.js モジュールを読み込む
インストールされている任意の Node.js モジュールを読み込むには、Node.js の require()
関数を使用します。require()
関数を使用して、関数とともにデプロイするローカル ファイルをインポートすることもできます。
非公開モジュールの使用
非公開の npm モジュールを使用するには、関数のディレクトリにある .npmrc
ファイルに、レジストリを認証するための設定を記述します。パッケージ管理システムとして Yarn v2 以降を使用している場合、このファイルの名前は .yarnrc.yml
です。
Artifact Registry の非公開モジュール
Artifact Registry Node.js パッケージ リポジトリは、関数の非公開モジュールをホストできます。Cloud Run functions の関数をデプロイすると、ビルドプロセスにより、Cloud Build サービス アカウント用の Artifact Registry 認証情報が自動的に生成されます。必要な操作は、.npmrc
に Artifact Registry リポジトリのリストを記述するだけです。追加の認証情報を生成する必要はありません。例:
@SCOPE:registry=https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
//REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME:always-auth=true
このアプローチは Yarn v1 パッケージ管理システムでも機能します。Yarn v2 以降を使用している場合は、追加の認証情報なしで Artifact Registry リポジトリを .yarnrc.yml
に一覧表示するだけで済みます。例:
npmScopes:
SCOPE:
npmRegistryServer: https://REGION_ID-npm.pkg.dev/PROJECT_ID/REPOSITORY_NAME
npmAlwaysAuth: true
他のリポジトリの非公開モジュール
npm のドキュメントでは、カスタムの読み取り専用アクセス トークンを作成する方法について説明しています。.npmrc
ファイルには読み取り / 書き込みトークンが含まれているため、ホーム ディレクトリにこのファイルを作成して使用することは避けてください。デプロイ時に書き込み権限は必要なく、セキュリティ上のリスクが発生する可能性があります。
非公開リポジトリを使用していない場合は .npmrc
ファイルを追加しないでください。追加すると、関数のデプロイ時間が長くなる可能性があります。
ファイル形式
.npmrc
ファイルを使用してカスタム認証トークンを設定する場合は、以下の行を含める必要があります。
//REGISTRY_DOMAIN/:_authToken=AUTH_TOKEN
次のように置き換えます。
- REGISTRY_DOMAIN: 非公開 npm レジストリのドメイン名。リポジトリが
npmjs.org
でホストされている場合は、このフィールドをregistry.npmjs.org
に設定します。 AUTH_TOKEN: npm レジストリの認証トークン。トークンのリテラル テキスト値、または
npm
を環境の実際のトークン値に置き換えるテキスト文字列${NPM_TOKEN}
のいずれかになります。$NPM_TOKEN
環境変数と--set-build-env-vars
引数をgcloud functions deploy
コマンドに設定できます。NPM 認証トークンについて詳しくは、非公開モジュールに関する NPM のチュートリアルをご覧ください。
ベンダリングされた依存関係を使用して関数をビルドする
ベンダリングされた依存関係とは、ソースがソースコード パッケージに直接組み込まれ、独自のコードとともに再ビルドされる依存関係です。ベンダリングされた Node.js 依存関係を作成し、GOOGLE_VENDOR_NPM_DEPENDENCIES ビルド環境変数を使用してデプロイ時にインストールをスキップします。
ベンダリングされた依存関係の前提条件
ベンダー定義する関数(すべての依存関係を含み、機能している関数)が
package.json
ファイルにあることを確認します。次のコマンドを実行して、これらの依存関係をローカルにインストールします。
npm install
作業ディレクトリの .gcloudignore ファイルから
node_modules
を削除します。関数をデプロイして、ローカルの Node.js のバージョンが、デプロイ時に指定したバージョンと同じであることを確認します。
次のコマンドを使用して、関数とベンダリングされた依存関係をデプロイします。
gcloud functions deploy FUNCTION_NAME \ --runtime RUNTIME_NAME \ --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
次のように置き換えます。
- FUNCTION_NAME: デプロイする Cloud Run functions の関数名
- RUNTIME_NAME: デプロイされた関数を実行する Node.js ランタイムの名前。これは、ローカル開発環境で使用したものと同じ Node.js バージョンである必要があります。
Functions フレームワーク パッケージは、関数に必須の依存関係です。ビルドを高速化するには、このパッケージをベンダリングすることをおすすめします。そうしない場合は、関数をビルドするときにダウンロードおよびインストールされます。
package.json ファイルで npm エンジンを指定すると、指定したバージョンの npm がビルド時間にダウンロードされます。この動作を抑制するには、package.json ファイルから削除します。