Node.js-Pakete verwalten

Auf dieser Seite werden die folgenden Aufgaben beschrieben:

• Pakete und Paketversionen ansehen und löschen
• Tags anzeigen, erstellen, aktualisieren und löschen

Hinweise

1. Wenn das Ziel-Repository nicht vorhanden ist, erstellen Sie ein neues Repository.
2. Prüfen Sie, ob Sie die erforderlichen Berechtigungen für das Repository haben.
3. Konfigurieren Sie die Authentifizierung für npm.
4. (Optional) Konfigurieren Sie die Standardeinstellungen für gcloud-Befehle.
5. Wenn Sie das npm-Credential Helper für die Authentifizierung verwenden, rufen Sie ein Zugriffstoken ab, bevor Sie mit npm eine Verbindung zu einem Repository herstellen.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Repository zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Verwalten von Paketen benötigen:

• Pakete, Dateien in Paketen und Tags ansehen: Artifact Registry-Leser (roles/artifactregistry.reader)
• Pakete herunterladen oder installieren: Artifact Registry-Leser (roles/artifactregistry.reader)
• Pakete einem Repository hinzufügen: Artifact Registry Writer (roles/artifactregistry.writer)
• Pakete löschen: Repository-Administrator für Artifact Registry (roles/artifactregistry.repoAdmin)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Zugriffstoken abrufen

Zugriffstokens sind 60 Minuten lang gültig. Generieren Sie ein Zugriffstoken kurz vor dem Ausführen von Befehlen, die mit Repositories interagieren.

Sie haben folgende Möglichkeiten, ein Token zu erhalten:

• Verwenden Sie den Befehl npx, um das Zugriffstoken zu aktualisieren.

  1. Die Anmeldedaten für die Verbindung zur öffentlichen npm-Registry befinden sich in der npm-Konfigurationsdatei des Nutzers ~/.npmrc.

  2. Führen Sie den folgenden Befehl in Ihrem Node.js-Projektverzeichnis aus.

     npx google-artifactregistry-auth
     

     Wenn Ihr Artifact Registry-Repository als globale Registry festgelegt ist und Ihre Pakete keinen Bereich haben, verwenden Sie stattdessen den folgenden Befehl, damit der Anmeldedaten-Helper aus der öffentlichen npm-Registry anstelle Ihres Artifact Registry-Repositorys heruntergeladen werden kann.

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

• Fügen Sie der Datei package.json in Ihrem Projekt ein Skript hinzu.

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

  Führen Sie das Skript in Ihrem Node.js-Projektverzeichnis aus.

  npm run artifactregistry-login
  

Artifact Registry liest die Einstellungen für Artifact Registry-Repositories in der .npmrc-Datei Ihres Projekts und verwendet sie, um Ihrer Nutzerdatei .npmrc Tokenanmeldedaten hinzuzufügen. Wenn Sie das Token in der Datei .npmrc Ihres Nutzers speichern, werden Ihre Anmeldedaten von Ihrem Quellcode und Ihrem Versionsverwaltungssystem isoliert.

Pakete hinzufügen

Repository-Modi:Standard

Sie können jeweils nur eine bestimmte Version eines Pakets veröffentlichen. Dies ist eine npm-Einschränkung, damit der Inhalt einer veröffentlichten Paketversion immer gleich ist. Folgendes ist dann nicht möglich:

• Überschreiben einer Paketversion durch erneutes Veröffentlichen im Repository.
• Entfernen eines Pakets oder seiner Version aus dem Repository und Veröffentlichen eines Pakets mit demselben Namen und derselben Versionsnummer.

Wenn Sie beim Veröffentlichen eines Pakets kein Tag angeben, fügt npm das latest-Tag hinzu. Um die Installation Ihrer Pakete in einer bestimmten Entwicklungsphase zu vereinfachen, sollten Sie Ihre Pakete mit einem Tag wie beta oder dev veröffentlichen.

In Artifact Registry müssen Paketnamen für npm-Pakete alphanumerisch und kleingeschrieben sein.

So fügen Sie ein Paket hinzu:

1. Der Paketname in package.json muss den für Ihr Repository konfigurierten Bereich enthalten. Das folgende Beispiel zeigt ein Paket mit dem Bereich dev-repo.

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

2. Wenn Sie den Credential Helper verwenden, um sich mit einem Zugriffstoken zu authentifizieren, rufen Sie ein neues Token ab.

3. Fügen Sie dem Repository Pakete hinzu. Sie können dazu einen npm- oder yarn-Befehl verwenden.

   Fügen Sie das Flag --tag ein und ersetzen Sie TAG durch das gewünschte Tag, um das Paket zu taggen. Wenn Sie das Flag --tag nicht angeben, legt npm das Tag automatisch auf latest fest.

   npm publish --tag=TAG
   

   yarn publish --tag TAG
   

Pakete und Versionen ansehen

Repository-Modi:Standard, Remote, virtuell

So rufen Sie Paketinformationen mit npm oder yarn ab:

1. Wenn Sie den Credential Helper verwenden, um sich mit einem Zugriffstoken zu authentifizieren, rufen Sie ein neues Token ab.

2. Führen Sie den entsprechenden Befehl aus:

   npm view
   

   yarn info
   

To view packages and package versions using the Google Cloud console or gcloud:

Console

1. Open the Repositories page in the Google Cloud console.

   Zur Seite „Repositories“

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Click a package to view versions of the package.

gcloud

To list packages in a repository, run the following command:

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

Replace the following:

• REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. If you configured a default location, then you can omit this flag to use the default.

To view versions of a package, run the following command:

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

Replace the following:

• PACKAGE is the ID of the package or fully qualified identifier for the package.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

Das Aufrufen von Paketen und Versionen über die Google Cloud -Konsole oder die gcloud CLI ist nur für Standard- und Remote-Repositories verfügbar.

Bei Remote-Repositories sollte die zurückgegebene Liste alle direkten und transitiven Abhängigkeiten enthalten, die im Repository zwischengespeichert sind.

Dateien auflisten

Repository-Modi:Standard, Remote

Sie können Dateien in einem Repository, Dateien in allen Versionen eines angegebenen Pakets oder Dateien in einer bestimmten Version eines Pakets auflisten.

Für alle folgenden Befehle können Sie eine maximale Anzahl von zurückzugebenden Dateien festlegen, indem Sie dem Befehl das Flag --limit hinzufügen.

So listen Sie alle Dateien im Standardprojekt, im Standard-Repository und am Standard-Speicherort auf, wenn die Standardwerte konfiguriert sind:

gcloud artifacts files list

Führen Sie den folgenden Befehl aus, um Dateien in einem angegebenen Projekt, Repository und Speicherort aufzulisten:

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

So listen Sie Dateien für alle Versionen eines bestimmten Pakets auf:

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

So listen Sie Dateien für eine bestimmte Paketversion auf:

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

So listen Sie Dateien für ein bestimmtes Tag auf:

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

Ersetzen Sie die folgenden Werte:

• LOCATION: der regionale oder multiregionale Speicherort für das Repository.
• PROJECT: Ihre Google Cloud Projekt-ID. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
• REPOSITORY: der Name des Repositorys, in dem das Image gespeichert ist.
• PACKAGE: der Name des Pakets.
• VERSION: die Version des Pakets.
• TAG: Das mit dem Paket verknüpfte Tag.

Beispiele

Sehen Sie sich die folgenden Paketinformationen an:

• Projekt: my-project
• Repository: my-repo
• Speicherort des Repositorys: us-west1
• Paket: my-app

Mit dem folgenden Befehl werden alle Dateien im Repository my-repo am Speicherort us-west1 im Standardprojekt aufgelistet:

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

Mit dem folgenden Befehl werden die Dateien in Version 1.0 des Pakets aufgelistet.

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

Mit dem folgenden Befehl werden Dateien in der Version des Pakets mit dem Tag 1.0-dev aufgelistet.

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

Pakete taggen

Repository-Modi:Standard

You can view, add, update, and delete tags. Tags can help you manage semantic versions of your packages and streamline installation of packages at a specific stage of development.

For example, you can tag the current release candidate build with rc. Your team can then install the correct version based on the tag instead of a version specifier, and unpublishing unused pre-release versions won't break your dependencies on the release candidate package.

Viewing tags

To view tags for a package:

Console

1. Open the Repositories page in the Google Cloud console.

   Zur Seite „Repositories“

2. Click the package to view versions and the associated tags.

3. Select the package version to tag.

4. In the row of the selected version, click More actions (), and then click Edit tags.

5. Type new tags into the field and then click SAVE.

gcloud

Run the command:

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

Where

• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
• LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.

For example, to view tags for the package my-package in the repository my-repo in the default location, run the command:

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

Creating tags

You can create a tag for a specific version of a package.

To tag an existing image in a repository:

Console

1. Open the Repositories page in the Google Cloud console.

   Zur Seite „Repositories“

2. Click the package to view versions of the package.

3. Select the package version to tag.

4. In the row of the selected version, click More actions (), and then click Edit tags.

5. Type new tags into the field and then click SAVE.

gcloud

Run the following command:

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

Where

• TAG is the tag you want to apply to the package.
• PACKAGE is the name of the package in the repository.
• VERSION is version of the package that you want to tag.
• LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
• REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to create the tag release-candidate for version 1.0.0 of package my-package in the repository my-repo in the default location, run the command:

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

Updating tags

You can change a tag associated with a package version.

To change an existing tag:

Console

1. Open the Repositories page in the Google Cloud console.

   Zur Seite „Repositories“

2. Click the package to view versions of the package.

3. Select the package version with the tag to change.

4. In the row of the selected version, click More actions (), and then click Edit tags.

5. Edit the tag and then click SAVE.

gcloud

Run the following command:

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

Where

• TAG is the tag you want to apply to the package.
• PACKAGE is the name of the package in the repository.
• VERSION is version of the package that you want to tag.
• LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
• REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to change the tag for version 1.0.0 of package my-package to production in the repository my-repo in the default location, run the command:

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

Untagging package versions

You can remove an existing tag from a package version.

To remove a tag:

Console

1. Open the Repositories page in the Google Cloud console.

   Zur Seite „Repositories“

2. Click the image to view versions of the image.

3. Select the image version to untag.

4. In the row of the selected version, click More actions (), and then click Edit tags.

5. Delete the tag and then click SAVE.

gcloud

Run the following command:

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

Where

• TAG is the tag you want to apply to the package.
• PACKAGE is the name of the package in the repository.
• LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
• REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to remove the tag release-candidate from package my-package in the repository my-repo in the default location, run the command:

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

Pakete installieren

Repository-Modi:Standard, Remote, virtuell

So installieren Sie ein Paket aus dem Node.js-Paket-Repository:

1. Wenn Sie den Credential Helper verwenden, um sich mit einem Zugriffstoken zu authentifizieren, rufen Sie ein neues Token ab.

2. Verwenden Sie den Befehl npm install oder yarn add.

   npm

   So installieren Sie die Version mit dem Tag latest:

   npm install @SCOPE/PACKAGE
   

   So installieren Sie eine Version mit einem anderen Tag:

   npm install @SCOPE/PACKAGE@TAG
   

   So installieren Sie eine bestimmte Version:

   npm install @SCOPE/PACKAGE@VERSION
   

   yarn

   So installieren Sie die Version mit dem Tag latest:

   yarn add @SCOPE/PACKAGE
   

   So installieren Sie eine Version mit einem anderen Tag:

   yarn add @SCOPE/PACKAGE@TAG
   

   So installieren Sie eine bestimmte Version:

   yarn add @SCOPE/PACKAGE@VERSION
   

   Ersetzen Sie die folgenden Werte:

   • SCOPE ist der mit dem Repository verknüpfte Bereich. Wenn Ihr Node.js-Paketrepository nicht mit einem Bereich konfiguriert ist, lassen Sie @SCOPE/ aus dem Befehl weg.
   • PACKAGE ist der Name des Pakets im Repository.
   • TAG ist das Tag für die Version, die Sie installieren möchten.
   • VERSION ist die Versionsnummer, die Sie installieren möchten.

Wenn Sie ein Paket als Abhängigkeit in package.json angeben, muss der Bereich für das Repository enthalten sein. Das folgende Beispiel zeigt den Bereich @dev-repo für ein Paket mit dem Namen my-package.

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

Bei Standard-Repositories laden Sie ein Paket direkt aus dem Repository herunter.

Bei einem Remote-Repository laden Sie eine im Cache gespeicherte Kopie des Pakets und seiner Abhängigkeiten herunter. Wenn keine Kopie im Cache vorhanden ist, lädt das Remote-Repository das Paket von der Upstream-Quelle herunter und speichert es im Cache, bevor es an Sie gesendet wird. Sie können prüfen, ob das Remote-Repository die Pakete aus der Upstream-Quelle abgerufen hat, indem Sie die Liste der Pakete im Repository aufrufen.

Bei einem virtuellen Repository durchsucht Artifact Registry Upstream-Repositories nach dem angeforderten Paket.

• Upstream-Remote-Repositories laden das angeforderte Paket herunter und speichern es im Cache, wenn keine im Cache gespeicherte Kopie vorhanden ist. Virtuelle Repositories stellen nur angeforderte Pakete bereit, sie speichern sie nicht.
• Wenn Sie eine Version anfordern, die in mehreren Upstream-Repositories verfügbar ist, wählt Artifact Registry ein Upstream-Repository basierend auf den für das virtuelle Repository konfigurierten Prioritätseinstellungen aus.

Angenommen, Sie haben ein virtuelles Repository mit den folgenden Prioritätseinstellungen für Upstream-Repositories:

• main-repo: Priorität auf 100 festgelegt
• secondary-repo1: Die Priorität ist auf 80 festgelegt.
• secondary-repo2: Die Priorität ist auf 80 festgelegt.
• test-repo: Die Priorität ist auf 20 festgelegt.

main-repo hat den höchsten Prioritätswert, daher wird immer zuerst in diesem virtuellen Repository gesucht.

Sowohl für secondary-repo1 als auch für secondary-repo2 ist die Priorität auf 80 festgelegt. Wenn ein angefordertes Paket nicht in main-repo verfügbar ist, durchsucht Artifact Registry als Nächstes diese Repositories. Da beide denselben Prioritätswert haben, kann Artifact Registry ein Paket aus einem der beiden Repositorys bereitstellen, wenn die Version in beiden verfügbar ist.

test-repo hat den niedrigsten Prioritätswert und es wird ein gespeichertes Artefakt bereitgestellt, wenn es in keinem der anderen Upstream-Repositories vorhanden ist.

Pakete löschen

Repository-Modi:Standard, Remote

Sie können ein Paket und alle seine Versionen oder eine bestimmte Version löschen.

• Das Löschen eines Pakets kann nicht rückgängig gemacht werden.
• Bei Remote-Repositories wird nur die im Cache gespeicherte Kopie des Pakets gelöscht. Die Upstream-Quelle ist nicht betroffen. Wenn Sie ein im Cache gespeichertes Paket löschen, wird es von Artifact Registry heruntergeladen und wieder im Cache gespeichert, wenn das Repository das nächste Mal eine Anfrage für dieselbe Paketversion erhält.

Nach der Veröffentlichung einer Paketversion können Sie ein Paket mit demselben Namen und derselben Versionskombination nicht noch einmal veröffentlichen, auch wenn diese Version gelöscht wurde. Dies ist eine npm-Einschränkung, damit der Inhalt einer veröffentlichten Paketversion immer gleich ist.

Wenn Sie die Nutzer auffordern möchten, eine aktualisierte Paketversion zu installieren, verwenden Sie den Befehl npm deprecate, um die alte Version des Pakets als verworfen zu kennzeichnen. Wenn ein Nutzer versucht, das verworfene Paket zu installieren, gibt Artifact Registry eine Warnung zurück, dass diese Version verworfen wurde.

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

1. Open the Repositories page in the Google Cloud console.

   Zur Seite „Repositories“

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Select the package that you want to delete.

4. Click DELETE.

5. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

1. Open the Repositories page in the Google Cloud console.

   Zur Seite „Repositories“

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Click a package to view versions of that package.

4. Select versions that you want to delete.

5. Click DELETE.

6. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

• VERSION is the name of the version to delete.
• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

Nächste Schritte

• Maven-Pakete verwalten
• Container-Images verwalten
• Einzelne Dateien in einem Paket herunterladen