Node.js で依存関係を指定する

プレビュー — Cloud Run functions

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

関数では、ローカルデータだけでなく、外部の Node.js モジュールも使用できます。Node.js における依存関係は、npm で管理され、package.json というメタデータ ファイルで表現されます。npm、yarn、pnpm を使用して Node.js の依存関係をインストールできます。

Node.js Functions Framework は、すべての関数に必須の依存関係です。Cloud Run functions は、関数の作成時にユーザーの代理でこの依存関係をインストールしますが、明確化のため明示的な依存関係として含めておくことをおすすめします。

関数が非公開の依存関係に依存している場合は、functions-framework を非公開のレジストリにミラーリングすることをおすすめします。ミラーリング対象の functions-framework を依存関係として関数に含めることで、公共のインターネットからパッケージがインストールされないようにします。

関数の依存関係を指定するには、package.json ファイルにその依存関係を追加します。

注: package-lock.json ファイル、yarn.lock ファイル、pnpm-lock.yaml ファイルのいずれかがプロジェクト内にある場合は、npm ci、yarn install、pnpm install を使用して依存関係がインストールされる際、そのロックファイルが優先されます。

この例では、依存関係は package.json ファイルにリストされています。

{
  "dependencies": {
    "escape-html": "^1.0.3"
  }
}

依存関係は関数にインポートされます。

const functions = require('@google-cloud/functions-framework');
const escapeHtml = require('escape-html');

/**
 * Responds to an HTTP request using data from the request body parsed according
 * to the "content-type" header.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('helloHttp', (req, res) => {
  res.send(`Hello ${escapeHtml(req.query.name || req.body.name || 'World')}!`);
});

npm を使用してローカルで Node.js モジュールをインストールする

ローカルで Node.js モジュールをインストールする特に簡単な方法は、Cloud Run 関数のあるフォルダで npm install コマンドを使用することです。たとえば、次のコマンドは uuid モジュールを追加します。

npm install uuid

これは、次の 2 つのステップを組み合わせたものです。

1. package.json ファイルで、モジュールの最新バージョンを依存関係としてマークします。これは非常に重要です。Cloud Run functions は、package.json ファイルで宣言されたモジュールのみをインストールします。
2. モジュールを node_modules ディレクトリにダウンロードします。これにより、モジュールをローカルでの開発に使用できます。

マシンに npm がインストールされていない場合は、npm を入手します。

注: npm パッケージは、さまざまな Google Cloud プロダクトで利用できます。Node.js クライアント ライブラリをご覧ください。

デプロイの依存関係の構成

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

注: サブディレクトリで宣言されている依存関係はインストールされません。monorepo を使用している場合は、デプロイ時にカスタム ビルド スクリプトを実行して、これらの依存関係をインストールすることをおすすめします。

デプロイ時にカスタムビルド ステップを実行する

デプロイした後、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 フォルダ以外の場所に保存する必要があります。

注: gcloud コマンドライン ツールを使用してデプロイする場合は、gcloud によって関数のディレクトリに .gcloudignore ファイルが自動作成されます。デフォルトでは、node_modules フォルダはこの .gcloudignore に追加され、デプロイメントの一部としてはアップロードされません。手動でコードを zip ファイルとしてアップロードする場合は、node_modules フォルダを含める必要はありません。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 ファイルを追加しないでください。追加すると、関数のデプロイ時間が長くなる可能性があります。

注: カスタム権限（VPC に必要な権限など）を使用している場合は、対象の非公開リポジトリに関数がアクセスすることを明示的に許可してください。

ファイル形式

.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 ビルド環境変数を使用してデプロイ時にインストールをスキップします。

コピーされた依存関係の前提条件

1. コピーするすべての依存関係を含む関数（package.json ファイルにある関数）が機能していることを確認します。

2. 次のコマンドを実行して、これらの依存関係をローカルにインストールします。

       npm install
   

3. 作業ディレクトリの .gcloudignore ファイルから node_modules を削除します。

4. 関数をデプロイして、ローカルの Node.js のバージョンが、デプロイ時に指定したバージョンと同じであることを確認します。

5. 次のコマンドを使用して、関数とコピーされた依存関係をデプロイします。

     gcloud run deploy SERVICE \
       --source . \
       --function FUNCTION_ENTRY_POINT \
       --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true
   

   以下のように置き換えます。

   • SERVICE: デプロイする Cloud Run 関数の名前
   • FUNCTION_ENTRY_POINT: ソースコード内の関数のエントリ ポイント。

package.json ファイルで npm エンジンを指定すると、指定したバージョンの npm がビルド時間にダウンロードされます。この動作を抑制するには、package.json ファイルから削除します。