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

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

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

始める前に

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

必要なロール

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

ロールの付与の詳細については、アクセス権の管理をご覧ください。

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

アクセス トークンの取得

アクセス トークンは 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 タグを追加します。特定の開発段階でパッケージのインストールを簡素化するには、betadev などのタグを使用してパッケージを公開することを検討してください。

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 を使用してパッケージとパッケージのバージョンを表示するには:

コンソール

  1. Google Cloud Console で [リポジトリ] ページを開きます。

    [リポジトリ] ページを開く

  2. リポジトリ リストで、適切なリポジトリをクリックします。

    [パッケージ] ページに、リポジトリ内のパッケージが一覧表示されます。

  3. パッケージをクリックして、そのパッケージのバージョンを表示します。

gcloud

リポジトリ内のパッケージを一覧表示するには、次のコマンドを実行します。

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

場所

  • REPOSITORY はリポジトリの名前です。 デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。
  • LOCATION は、 リージョンまたはマルチリージョンの ロケーションです。 このフラグを使用して、特定のロケーションのリポジトリを表示します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。

パッケージのバージョンを表示するには、次のコマンドを実行します。

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

場所

  • PACKAGE は、パッケージの ID またはパッケージの完全修飾識別子です。
  • REPOSITORY はリポジトリの名前です。 デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。
  • 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
パッケージのバージョン 1.0 内のファイルを一覧表示します。

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0
次のコマンドは、1.0-dev タグを持つパッケージのバージョン内のファイルを一覧表示します。

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

パッケージへのタグ付け

リポジトリ モード: 標準

タグを表示、追加、更新、削除できます。タグは、パッケージのセマンティック バージョンを管理し、開発の特定の段階でパッケージのインストールを合理化するのに役立ちます。

たとえば、現在のリリース候補ビルドに rc というタグを付けることができます。バージョン指定子の代わりに、タグに基づいて正しいバージョンをインストールできます。未使用のプレリリース バージョンの公開を停止しても、リリース候補パッケージへの影響はありません。

タグの表示

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

コンソール

  1. Google Cloud コンソールで [リポジトリ] ページを開きます。

    [リポジトリ] ページを開く

  2. パッケージをクリックして、バージョンと関連するタグを表示します。

  3. タグを付けるパッケージ バージョンを選択します。

  4. 選択したバージョンの行で、[その他の操作](その他の操作)をクリックし、[タグを編集] をクリックします。

  5. フィールドに新しいタグを入力し、[保存] をクリックします。

gcloud

次のコマンドを実行します。

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

ここで

  • PACKAGE は、リポジトリ内のパッケージの名前です。
  • REPOSITORY はリポジトリの名前です。デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。
  • LOCATION は、リージョンまたはマルチリージョンのロケーションです。特定のロケーションのリポジトリを表示するには、このフラグを使用します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。

たとえば、デフォルトのロケーションにあるリポジトリ my-repo のパッケージ my-package のタグを表示するには、次のコマンドを実行します。

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

タグを作成する

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

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

コンソール

  1. Google Cloud コンソールで [リポジトリ] ページを開きます。

    [リポジトリ] ページを開く

  2. パッケージのバージョンを表示するには、パッケージをクリックします。

  3. タグを付けるパッケージ バージョンを選択します。

  4. 選択したバージョンの行で、[その他の操作](その他の操作)をクリックし、[タグを編集] をクリックします。

  5. フィールドに新しいタグを入力し、[保存] をクリックします。

gcloud

次のコマンドを実行します。

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

ここで

  • TAG は、パッケージに適用するタグです。
  • PACKAGE は、リポジトリ内のパッケージの名前です。
  • VERSION は、タグ付けするパッケージのバージョンです。
  • LOCATION は、リージョンまたはマルチリージョンのロケーションです。特定のロケーションのリポジトリを表示するには、このフラグを使用します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。
  • REPOSITORY はリポジトリの名前です。デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。

たとえば、デフォルトのロケーションのリポジトリ my-repo でパッケージ my-package のバージョン 1.0.0 にタグ release-candidate を作成するには、次のコマンドを実行します。

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

タグを更新する

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

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

コンソール

  1. Google Cloud コンソールで [リポジトリ] ページを開きます。

    [リポジトリ] ページを開く

  2. パッケージのバージョンを表示するには、パッケージをクリックします。

  3. 変更するタグが含まれるパッケージ バージョンを選択します。

  4. 選択したバージョンの行で、[その他の操作](その他の操作)をクリックし、[タグを編集] をクリックします。

  5. タグを削除して [保存] をクリックします。

gcloud

次のコマンドを実行します。

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

ここで

  • TAG は、パッケージに適用するタグです。
  • PACKAGE は、リポジトリ内のパッケージの名前です。
  • VERSION は、タグ付けするパッケージのバージョンです。
  • LOCATION は、リージョンまたはマルチリージョンのロケーションです。特定のロケーションのリポジトリを表示するには、このフラグを使用します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。
  • REPOSITORY はリポジトリの名前です。デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。

たとえば、パッケージ my-package のバージョン 1.0.0 のタグを、デフォルトのロケーションにあるリポジトリ my-repoproduction に変更するには、次のコマンドを実行します。

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

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

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

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

コンソール

  1. Google Cloud コンソールで [リポジトリ] ページを開きます。

    [リポジトリ] ページを開く

  2. イメージをクリックすると、そのイメージのバージョンが表示されます。

  3. タグを解除するイメージ バージョンを選択します。

  4. 選択したバージョンの行で、[その他の操作](その他の操作)をクリックし、[タグを編集] をクリックします。

  5. タグを削除して [保存] をクリックします。

gcloud

次のコマンドを実行します。

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

ここで

  • TAG は、パッケージに適用するタグです。
  • PACKAGE は、リポジトリ内のパッケージの名前です。
  • LOCATION は、リージョンまたはマルチリージョンのロケーションです。特定のロケーションのリポジトリを表示するには、このフラグを使用します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。
  • REPOSITORY はリポジトリの名前です。デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。

たとえば、デフォルトのロケーションにあるリポジトリ my-repo のパッケージ my-package からタグ release-candidate を削除するには、次のコマンドを実行します。

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

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

パッケージの削除

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

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

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

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

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

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

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

コンソール

  1. Google Cloud Console で [リポジトリ] ページを開きます。

    [リポジトリ] ページを開く

  2. リポジトリ リストで、適切なリポジトリをクリックします。

    [パッケージ] ページに、リポジトリ内のパッケージが一覧表示されます。

  3. 削除するパッケージを選択します。

  4. [削除] をクリックします。

  5. 確認のダイアログ ボックスで、[削除] をクリックします。

gcloud

次のコマンドを実行します。

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

場所

  • PACKAGE は、リポジトリ内のイメージの名前です。
  • REPOSITORY はリポジトリの名前です。デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。
  • LOCATION は、 リージョンまたはマルチリージョンの ロケーションです。 このフラグを使用して、特定のロケーションのリポジトリを表示します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。
  • --async - 処理中のオペレーションの完了を待たずに、直ちにコマンドを終了します。

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

コンソール

  1. Google Cloud Console で [リポジトリ] ページを開きます。

    [リポジトリ] ページを開く

  2. リポジトリ リストで、適切なリポジトリをクリックします。

    [パッケージ] ページに、リポジトリ内のパッケージが一覧表示されます。

  3. パッケージをクリックして、そのパッケージのバージョンを表示します。

  4. 削除するバージョンを指定します。

  5. [削除] をクリックします。

  6. 確認のダイアログ ボックスで、[削除] をクリックします。

gcloud

次のコマンドを実行します。

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

場所

  • PACKAGE は、リポジトリ内のイメージの名前です。
  • REPOSITORY はリポジトリの名前です。デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。
  • LOCATION は、 リージョンまたはマルチリージョンの ロケーションです。 このフラグを使用して、特定のロケーションのリポジトリを表示します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。
  • --async は処理中のオペレーションの完了を待たずに、直ちにコマンドを終了します。

次のステップ