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

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

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

この例では、依存関係は 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')}!`);
});

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

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

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

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

npm install uuid

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

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

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

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

NPM、Yarn、Pnpm の本番環境の依存関係をインストールできます。

NPM

関数をデプロイする際、Cloud Functions は npm install コマンドを使用して、package.json ファイル内で宣言されている依存関係をインストールします。

npm install --production

Yarn

Node.js 8 以降のランタイムでは、yarn.lock ファイルが存在する場合は、Cloud Functions では代わりに yarn install コマンドが使用されます。

yarn install --production

Pnpm

Node.js 8 以降のランタイムでは、pnpm-lock.yaml ファイルが存在する場合は、Cloud Functions では代わりに pnpm install コマンドが使用されます。

pnpm install

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

デプロイした後、package.json ファイルに gcp-build スクリプトを追加すると、関数のビルドプロセス中にカスタム ビルドステップを実行できます。

このスクリプトの実行時には、package.json ファイルの dependencies フィールドと devDependencies フィールドの依存関係を利用できます。カスタムビルド ステップが実行された後、Cloud Functions は package.json ファイルの dependencies フィールドで宣言されている本番環境の依存関係のみをインストールし、node_modules フォルダを削除して生成し直します。

package.json に gcp-build スクリプトがない場合、Cloud Functions は本番環境の依存関係をインストールするだけです。

システム パッケージの使用

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

ベンダリングされた依存関係の前提条件

  1. ベンダー定義する関数（すべての依存関係を含み、機能している関数）が package.json ファイルにあることを確認します。

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

        npm install

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

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

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

      gcloud functions deploy FUNCTION_NAME \
    --runtime RUNTIME_NAME \
    --set-build-env-vars GOOGLE_VENDOR_NPM_DEPENDENCIES=true

    次のように置き換えます。

    • FUNCTION_NAME: デプロイする Cloud Functions 関数の名前
    • RUNTIME_NAME: デプロイされた関数を実行する Node.js ランタイムの名前。これは、ローカル開発環境で使用したものと同じ Node.js バージョンである必要があります。

Functions フレームワーク パッケージは、関数に必須の依存関係です。ビルドを高速化するには、このパッケージをベンダリングすることをおすすめします。そうしない場合は、関数をビルドするときにダウンロードおよびインストールされます。

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