Node.js パッケージを管理する

このページでは、次のタスクについて説明します。

• パッケージとパッケージ バージョンの表示と削除
• タグの表示、作成、更新、削除

始める前に

1. ターゲット リポジトリが存在しない場合は、新しいリポジトリを作成します。
2. リポジトリに必要な権限が付与されていることを確認します。
3. npm の認証を構成します。
4. （省略可）gcloud コマンドのデフォルトを構成します。
5. npm の認証情報ヘルパーを使用して認証する場合は、npm でリポジトリに接続する前にアクセス トークンを取得します。

必要なロール

パッケージの管理に必要な権限を取得するには、リポジトリに対する次の IAM ロールの付与を管理者に依頼してください。

• パッケージ、パッケージ内のファイル、タグを表示する: Artifact Registry 読み取り（roles/artifactregistry.reader）
• パッケージをダウンロードまたはインストールする: Artifact Registry 読み取り（roles/artifactregistry.reader）
• リポジトリにパッケージを追加する: Artifact Registry 書き込み（roles/artifactregistry.writer）
• パッケージを削除する: Artifact Registry リポジトリ管理者（roles/artifactregistry.repoAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

アクセス トークンの取得

アクセス トークンは 60 分間有効です。リポジトリを操作するコマンドを実行する直前にアクセス トークンを生成します。

トークンを取得するには、次のいずれかのオプションを使用します。

• npx コマンドを使用して、アクセス トークンを更新する。

  1. 公開 npm レジストリに接続するための認証情報が、ユーザーの npm 構成ファイル ~/.npmrc に含まれていることを確認します。

  2. Node.js プロジェクト ディレクトリで次のコマンドを実行します。

     npx google-artifactregistry-auth
     

     Artifact Registry リポジトリがグローバル レジストリとして設定され、パッケージのスコープが設定されていない場合は、次のコマンドを使用すると、Artifact Registry リポジトリではなく公開 npm レジストリから認証情報ヘルパーをダウンロードできます。

     npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
     

• プロジェクトの package.json ファイルにスクリプトを追加します。

  "scripts": {
   "artifactregistry-login": "npx google-artifactregistry-auth"
  }
  

  Node.js プロジェクト ディレクトリでスクリプトを実行します。

  npm run artifactregistry-login
  

Artifact Registry はプロジェクト .npmrc ファイル内の Artifact Registry リポジトリの設定を読み取り、それらを使用してユーザーの .npmrc ファイルにトークン認証情報を追加します。ユーザーの .npmrc ファイルにトークンを保存すると、認証情報がソースコードとソース コントロール システムから分離されます。

パッケージの追加

リポジトリ モード: 標準

特定のバージョンのパッケージは 1 回だけ公開できます。これは npm の制限であり、公開されるパッケージ バージョンの内容が常に同じになるようにします。そのため、以下のような操作はできません。

• パッケージ バージョンを上書きするには、リポジトリに再度公開します。
• リポジトリからパッケージまたはそのバージョンを削除してから、同じ名前とバージョン番号のパッケージを公開する

パッケージを公開するときにタグを指定しない場合、npm は latest タグを追加します。特定の開発段階でパッケージのインストールを簡素化するには、beta や dev などのタグを使用してパッケージを公開することを検討してください。

Artifact Registry では、npm パッケージに英数字の小文字のパッケージ名が適用されます。

パッケージを追加するには、次の手順を行います。

1. package.json のパッケージ名に、リポジトリに設定されたスコープが含まれていることを確認します。次の例は、dev-repo というスコープを持つパッケージを示しています。

   "name": "@dev-repo/my-package"
   

2. 認証情報ヘルパーを使用してアクセス トークンで認証する場合は、新しいトークンを取得します。

3. リポジトリにパッケージを追加する。npm、もしくは yarn コマンドを使用できます。

   パッケージにタグを付けるには、--tag フラグを指定し、TAG を使用するタグに置き換えます。--tag フラグを指定しない場合、npm はタグを自動的に latest に設定します。

   npm publish --tag=TAG
   

   yarn publish --tag TAG
   

パッケージとバージョンを表示する

リポジトリ モード: 標準、リモート、仮想

npm または yarn を使用してパッケージ情報を取得するには:

1. 認証情報ヘルパーを使用してアクセス トークンで認証する場合は、新しいトークンを取得します。

2. 適切なコマンドを実行します。

   npm view
   

   yarn info
   

Google Cloud コンソールまたは gcloud を使用してパッケージとパッケージのバージョンを表示するには:

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

Google Cloud コンソールや gcloud CLI からパッケージとバージョンを表示する機能は、標準リポジトリとリモート リポジトリでのみ使用できます。

リモート リポジトリの場合、返されるリストには、リポジトリにキャッシュ保存されているすべての直接的な依存関係と一時的な依存関係が含まれます。

ファイルのリスティング

リポジトリ モード: 標準、リモート

リポジトリ内のファイル、指定したパッケージのすべてのバージョン内のファイル、またはパッケージの特定のバージョン内のファイルを一覧表示できます。

次のすべてのコマンドについては、コマンドに --limit フラグを追加することで、返されるファイルの最大数を設定できます。

デフォルト値が構成されている場合にデフォルトのプロジェクト、リポジトリ、ロケーションのすべてのファイルを一覧表示するには次のようにします。

gcloud artifacts files list

指定したプロジェクト、リポジトリ、ロケーション内のファイルを一覧表示するには、次のコマンドを実行します。

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

特定のパッケージのすべてのバージョン内のファイルを一覧表示するには:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

特定のパッケージ バージョンのファイルを一覧表示するには:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --tag=TAG

次の値を置き換えます。

• LOCATION: リポジトリのリージョンまたはマルチリージョンのロケーション。
• PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
• REPOSITORY: イメージが保存されるリポジトリの名前。
• PACKAGE: パッケージの名前。
• VERSION: パッケージのバージョン。
• TAG: パッケージに関連付けられているタグ。

例

次のパッケージ情報について考慮するには:

• プロジェクト: my-project
• リポジトリ: my-repo
• リポジトリの場所: us-west1
• パッケージ: my-app

次のコマンドは、デフォルト プロジェクト内のロケーション us-west1 のリポジトリ my-repo 内のすべてのファイルを一覧表示します。

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --tag=1.0-dev

パッケージへのタグ付け

リポジトリ モード: 標準

タグの表示、追加、更新、削除を行うことができます。タグを使用すると、パッケージのセマンティック バージョンを管理し、開発の特定の段階でパッケージのインストールを合理化できます。

たとえば、現在のリリース候補ビルドに rc というタグを設定できます。チームは、バージョン指定子ではなくタグに基づいて正しいバージョンをインストールできます。また、未使用のプレリリース版の公開を停止しても、リリース候補版パッケージへの依存関係が破綻することはありません。

タグの表示

パッケージのタグを表示するには、次の手順を行います。

gcloud artifacts tags list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

gcloud artifacts tags list --package=my-pkg --repository=my-repo

タグの作成

パッケージの特定のバージョンのタグを作成できます。

リポジトリ内の既存のイメージにタグを付けるには、次の手順を行います。

gcloud artifacts tags create TAG --package=PACKAGE \
    version=VERSION [--location=LOCATION] [--repository=REPOSITORY]

gcloud artifacts tags create release-candidate --version=1.0.0 \
    --package=my-pkg --repository=my-repo

タグの更新

パッケージ バージョンに関連付けられているタグを変更できます。

既存のタグを変更するには、次の手順を行います。

gcloud artifacts tags update TAG --package=PACKAGE \
    version=VERSION [--location=LOCATION] [--repository=REPOSITORY]

gcloud artifacts tags update production --version=1.0.0 \
    --package=my-pkg --repository=my-repo

パッケージ バージョンのタグ付けを解除する

パッケージ バージョンから既存のタグを削除できます。

タグを削除するには、次の手順を行います。

gcloud artifacts tags delete TAG --package=PACKAGE \
    [--location=<LOCATION] [--repository=REPOSITORY]

gcloud artifacts tags delete release-candidate --package=my-pkg \
    --repository=my-repo

パッケージのインストール

リポジトリ モード: 標準、リモート、仮想

Node.js パッケージ レポジトリ からパッケージをインストールするには:

1. 認証情報ヘルパーを使用してアクセス トークンで認証する場合は、新しいトークンを取得します。

2. npm install コマンドまたは yarn add コマンドを使用します。

   npm

   latest タグを使用してバージョンをインストールするには:

   npm install @SCOPE/PACKAGE
   

   別のタグを使用してバージョンをインストールするには:

   npm install @SCOPE/PACKAGE@TAG
   

   特定のバージョンをインストールするには:

   npm install @SCOPE/PACKAGE@VERSION
   

   yarn

   latest タグを使用してバージョンをインストールするには:

   yarn add @SCOPE/PACKAGE
   

   別のタグを使用してバージョンをインストールするには:

   yarn add @SCOPE/PACKAGE@TAG
   

   特定のバージョンをインストールするには:

   yarn add @SCOPE/PACKAGE@VERSION
   

   次の値を置き換えます。

   • SCOPE は、リポジトリに関連付けられているスコープです。Node.js パッケージ リポジトリでスコープが構成されていない場合は、コマンドから @SCOPE/ を省略します。
   • PACKAGE は、リポジトリ内のイメージの名前です。
   • TAG は、インストールするバージョンのタグです。
   • VERSION は、インストールするバージョン番号です。

package.json でパッケージを依存関係として指定する場合は、リポジトリのスコープを含めるようにしてください。次の例では、@dev-repo という名前のパッケージの my-package スコープを示します。

"dependencies": {
  "@dev-repo/my-package": ">=1.0.0"
}

標準リポジトリの場合は、リポジトリからパッケージを直接ダウンロードします。

リモート リポジトリの場合は、パッケージとその依存関係のキャッシュに保存されたコピーをダウンロードします。キャッシュに保存されたコピーが存在しない場合は、リモート リポジトリがアップストリーム ソースからパッケージをダウンロードし、それを提供する前にキャッシュに保存します。リモート リポジトリがアップストリーム ソースからパッケージを取得したことを確認するには、リポジトリ内のパッケージの一覧を表示します。

仮想リポジトリの場合は、Artifact Registry はリクエストされたパッケージのアップストリーム リポジトリを検索します。

• キャッシュに保存されたコピーが存在しない場合、アップストリームのリモート リポジトリは、リクエストされたパッケージをダウンロードしてキャッシュに保存します。仮想リポジトリはリクエストされたパッケージを提供だけして、保存しません。
• 複数のアップストリーム リポジトリに存在する利用可能なバージョンをリクエストすると、Artifact Registry は仮想リポジトリ用に構成された優先度設定に基づいて、使用するアップストリーム リポジトリを選択します。

たとえば、アップストリーム リポジトリに次の優先度設定がある仮想リポジトリについて考えます。

• main-repo: 優先度が 100 に設定
• secondary-repo1: 優先度が 80 に設定
• secondary-repo2: 優先度が 80 に設定
• test-repo: 優先度が 20 に設定

main-repo の優先度の値は最も高いため、仮想リポジトリは常に最初に検索します。

secondary-repo1 と secondary-repo2 はどちらも優先度が 80 に設定されています。リクエストされたパッケージが main-repo にない場合、Artifact Registry は次にこれらのリポジトリを検索します。どちらも同じ優先度を持つため、両方にそのバージョンがある場合、Artifact Registry はどちらか一方のリポジトリからパッケージを提供するように選択できます。

test-repo の優先度は最も低くなります。他のアップストリーム リポジトリにアーティファクトがない場合、保存されたアーティファクトが提供されます。

パッケージの削除

リポジトリ モード: 標準、リモート

パッケージとそのすべてのバージョンを削除することや、特定のバージョンを削除することができます。

• パッケージを削除すると、その操作は元に戻せません。
• リモート リポジトリの場合は、パッケージのキャッシュに保存されたコピーのみが削除されます。アップストリーム ソース はこの影響を受けません。キャッシュに保存されたパッケージを削除し、次回、リポジトリが同じパッケージ バージョンのリクエストを受け取った場合、Artifact Registry は、そのパッケージを再度ダウンロードしてキャッシュに保存します。

パッケージ バージョンが公開された後は、バージョンを削除した後でも、同じ名前とバージョンの組み合わせを持つパッケージは再公開できません。これは npm の制限であり、公開されるパッケージ バージョンの内容が常に同じになるようにします。

ユーザーに更新されたパッケージ バージョンのインストールを促すには、npm deprecate コマンドを使用して、古いバージョンのパッケージを非推奨としてマークします。ユーザーが非推奨パッケージをインストールしようとすると、Artifact Registry から非推奨警告が返されます。

パッケージまたはパッケージのバージョンを削除する前に、そのパッケージの重要な依存関係を送信済み、または対処済みであることを確認してください。

パッケージを削除するには：

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

パッケージのバージョンを削除するには:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

次のステップ

• Maven パッケージの管理について学習する
• コンテナ イメージの管理について確認する
• パッケージ内の個々のファイルをダウンロードする