Gestisci pacchetti Node.js

In questa pagina vengono descritte le attività seguenti:

• Visualizzazione ed eliminazione di pacchetti e versioni dei pacchetti
• Visualizzazione, creazione, aggiornamento ed eliminazione di tag

Prima di iniziare

1. Se il repository di destinazione non esiste, creane uno nuovo.
2. Verifica di disporre delle autorizzazioni necessarie per il repository.
3. Configura l'autenticazione per npm.
4. (Facoltativo) Configura i valori predefiniti per i comandi gcloud.
5. Se utilizzi l'helper per le credenziali npm per l'autenticazione, ottieni un token di accesso prima di connetterti a un repository con npm.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire i pacchetti, chiedi all'amministratore di concederti i seguenti ruoli IAM nel repository:

• Visualizza pacchetti, file in pacchetti e tag: Artifact Registry Reader (roles/artifactregistry.reader)
• Scarica o installa pacchetti: Artifact Registry Reader (roles/artifactregistry.reader)
• Aggiungi pacchetti a un repository: Artifact Registry Writer (roles/artifactregistry.writer)
• Elimina i pacchetti: Amministratore repository Artifact Registry (roles/artifactregistry.repoAdmin)

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Ottenere un token di accesso

I token di accesso sono validi per 60 minuti. Genera un token di accesso poco prima di eseguire i comandi che interagiscono con i repository.

Per ottenere un token, utilizza una delle seguenti opzioni:

• Usa il comando npx per aggiornare il token di accesso.

  1. Assicurati che le credenziali per la connessione al registro npm pubblico siano presenti nel file di configurazione npm dell'utente, ~/.npmrc.

  2. Esegui questo comando nella directory del progetto Node.js.

     npx google-artifactregistry-auth
     

     Se il repository Artifact Registry è impostato come registro globale e i tuoi pacchetti non hanno un ambito, utilizza il comando seguente in modo che il comando possa scaricare l'helper delle credenziali dal registry pubblico npm anziché dal repository Artifact Registry.

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

• Aggiungi uno script al file package.json nel tuo progetto.

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

  Esegui lo script nella directory del progetto Node.js.

  npm run artifactregistry-login
  

Artifact Registry legge le impostazioni del repository Artifact Registry nel file .npmrc del tuo progetto e le utilizza per aggiungere le credenziali del token al file .npmrc dell'utente. L'archiviazione del token nel file .npmrc dell'utente isola le tue credenziali dal codice sorgente e dal sistema di controllo del codice sorgente.

Aggiunta di pacchetti

Modalità repository: standard

Puoi pubblicare una versione specifica di un pacchetto una sola volta. Questa è una restrizione npm per garantire che i contenuti di una versione pubblicata del pacchetto siano sempre gli stessi. Di conseguenza non puoi:

• Sovrascrivi una versione del pacchetto pubblicandola di nuovo nel repository
• Rimuovi un pacchetto o la relativa versione dal repository, quindi pubblica un pacchetto con lo stesso nome e numero di versione

Se non specifichi un tag quando pubblichi un pacchetto, npm aggiunge il tag latest. Per semplificare l'installazione dei pacchetti in una fase di sviluppo specifica, valuta la possibilità di pubblicare i pacchetti con un tag, ad esempio beta o dev.

Artifact Registry applica nomi di pacchetti alfanumerici minuscoli per i pacchetti npm.

Per aggiungere un pacchetto:

1. Assicurati che il nome del pacchetto in package.json includa l'ambito configurato per il tuo repository. L'esempio seguente mostra un pacchetto con l'ambito dev-repo.

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

2. Se usi l'helper per le credenziali per l'autenticazione con un token di accesso, richiedi un nuovo token.

3. Aggiungi pacchetti al repository. Puoi utilizzare un comando npm o yarn.

   Per taggare il pacchetto, includi il flag --tag e sostituisci TAG con il tag che vuoi utilizzare. Se non includi il flag --tag, npm imposta automaticamente il tag su latest.

   npm publish --tag=TAG
   

   yarn publish --tag TAG
   

Visualizzazione di pacchetti e versioni

Modalità repository: standard, remoto, virtuale

Per ricevere informazioni sul pacco presso npm o yarn:

1. Se usi l'helper per le credenziali per l'autenticazione con un token di accesso, richiedi un nuovo token.

2. Esegui il comando appropriato:

   npm view
   

   yarn info
   

Per visualizzare i pacchetti e le versioni dei pacchetti utilizzando la console Google Cloud o gcloud:

Console

1. Apri la pagina Repositories nella console Google Cloud.

   Apri la pagina Repository

2. Nell'elenco dei repository, fai clic su quello appropriato.

   Nella pagina Pacchetti sono elencati i pacchetti nel repository.

3. Fai clic su un pacchetto per visualizzare le versioni del pacchetto.

gcloud

Per elencare i pacchetti in un repository, esegui questo comando:

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

Dove

• REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.
• LOCATION è una località a livello di una o più regioni. Utilizza questo flag per visualizzare i repository in una località specifica. Se hai configurato una località predefinita, puoi omettere questo flag per utilizzare quella predefinita.

Per visualizzare le versioni di un pacchetto, esegui questo comando:

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

Dove

• PACKAGE è l'ID del pacchetto o l'identificatore completo del pacchetto.
• REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.
• LOCATION è una località a livello di una o più regioni. Utilizza questo flag per visualizzare i repository in una località specifica. Se hai configurato una località predefinita, puoi omettere questo flag per utilizzare quella predefinita.

La visualizzazione di pacchetti e versioni dalla console Google Cloud o gcloud CLI è disponibile solo per i repository standard e remoti.

Per i repository remoti, l'elenco restituito dovrebbe includere tutte le dipendenze dirette e transitive memorizzate nella cache nel repository.

Elenco dei file

Modalità repository: standard, remoto

Puoi elencare i file di un repository, i file di tutte le versioni di un pacchetto specificato o i file di una versione specifica di un pacchetto.

Per tutti i comandi seguenti, puoi impostare il numero massimo di file da restituire aggiungendo il flag --limit al comando.

Per elencare tutti i file nel progetto, nel repository e nella posizione predefiniti quando sono configurati i valori predefiniti:

gcloud artifacts files list

Per elencare i file in un progetto, un repository e una posizione specificati, esegui il comando:

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

Per elencare i file di tutte le versioni di un pacchetto specifico:

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

Per elencare i file relativi a una versione specifica del pacchetto:

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

Per elencare i file per un tag specifico:

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

Sostituisci i seguenti valori:

• LOCATION è la località a livello di una o più regioni del repository.
• PROJECT è il tuo ID progetto Google Cloud. Se l'ID progetto contiene i due punti (:), consulta Progetti con ambito di dominio.
• REPOSITORY è il nome del repository in cui è archiviata l'immagine.
• PACKAGE è il nome del pacchetto.
• VERSION è la versione del pacchetto.
• TAG è il tag associato al pacchetto.

Esempi

Prendi in considerazione le seguenti informazioni sul pacchetto:

• Progetto: my-project
• Repository: my-repo
• Località del repository: us-central1
• Pacchetto: my-app

Il seguente comando elenca tutti i file nel repository my-repo nella posizione us-central1 all'interno del progetto predefinito:

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

Il comando seguente elenca i file nella versione 1.0 del pacchetto.

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

Il comando seguente elenca i file che si trovano nella versione del pacchetto con il tag 1.0-dev

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

Tagging dei pacchetti

Modalità repository: standard

Puoi visualizzare, aggiungere, aggiornare ed eliminare i tag. I tag possono aiutarti a gestire le versioni semantiche dei pacchetti e a semplificare l'installazione dei pacchetti in una fase specifica di sviluppo.

Ad esempio, puoi taggare la build candidata di release corrente con rc. Il tuo team può quindi installare la versione corretta in base al tag anziché a un identificatore di versione. L'annullamento della pubblicazione di versioni pre-release inutilizzate non interromperà le dipendenze dal pacchetto candidato per la release.

Visualizzazione dei tag

Per visualizzare i tag di un pacchetto:

Console

1. Apri la pagina Repositories nella console Google Cloud.

   Apri la pagina Repository

2. Fai clic sul pacchetto per visualizzare le versioni e i tag associati.

3. Seleziona la versione del pacchetto da taggare.

4. Nella riga della versione selezionata, fai clic su Altre azioni () e poi su Modifica tag.

5. Digita nuovi tag nel campo e fai clic su SALVA.

gcloud

Esegui il comando:

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

Dove

• PACKAGE è il nome del pacchetto nel repository.
• REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.
• LOCATION è una località a livello di una o più regioni. Utilizza questo flag per visualizzare i repository in una località specifica. Se hai configurato una località predefinita, puoi omettere questo flag per utilizzare quella predefinita.

Ad esempio, per visualizzare i tag del pacchetto my-package nel repository my-repo nella posizione predefinita, esegui questo comando:

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

Creazione dei tag

Puoi creare un tag per una versione specifica di un pacchetto.

Per taggare un'immagine esistente in un repository:

Console

1. Apri la pagina Repositories nella console Google Cloud.

   Apri la pagina Repository

2. Fai clic sul pacchetto per visualizzare le versioni del pacchetto.

3. Seleziona la versione del pacchetto da taggare.

4. Nella riga della versione selezionata, fai clic su Altre azioni () e poi su Modifica tag.

5. Digita nuovi tag nel campo e fai clic su SALVA.

gcloud

Esegui questo comando:

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

Dove

• TAG è il tag da applicare al pacchetto.
• PACKAGE è il nome del pacchetto nel repository.
• VERSION è la versione del pacchetto che vuoi taggare.
• LOCATION è una località a livello di una o più regioni. Utilizza questo flag per visualizzare i repository in una località specifica. Se hai configurato una località predefinita, puoi omettere questo flag per utilizzare quella predefinita.
• REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.

Ad esempio, per creare il tag release-candidate per la versione 1.0.0 del pacchetto my-package nel repository my-repo nella posizione predefinita, esegui il comando:

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

Aggiornamento dei tag

Puoi modificare un tag associato a una versione di pacchetto.

Per modificare un tag esistente:

Console

1. Apri la pagina Repositories nella console Google Cloud.

   Apri la pagina Repository

2. Fai clic sul pacchetto per visualizzare le versioni del pacchetto.

3. Seleziona la versione del pacchetto con il tag da modificare.

4. Nella riga della versione selezionata, fai clic su Altre azioni () e poi su Modifica tag.

5. Modifica il tag e fai clic su SALVA.

gcloud

Esegui questo comando:

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

Dove

• TAG è il tag da applicare al pacchetto.
• PACKAGE è il nome del pacchetto nel repository.
• VERSION è la versione del pacchetto che vuoi taggare.
• LOCATION è una località a livello di una o più regioni. Utilizza questo flag per visualizzare i repository in una località specifica. Se hai configurato una località predefinita, puoi omettere questo flag per utilizzare quella predefinita.
• REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.

Ad esempio, per modificare il tag della versione 1.0.0 del pacchetto my-package in production nel repository my-repo nella posizione predefinita, esegui il comando:

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

Annullamento del tagging delle versioni del pacchetto

Puoi rimuovere un tag esistente da una versione di pacchetto.

Per rimuovere un tag:

Console

1. Apri la pagina Repositories nella console Google Cloud.

   Apri la pagina Repository

2. Fai clic sull'immagine per visualizzarne le versioni.

3. Seleziona la versione dell'immagine per cui rimuovere il tag.

4. Nella riga della versione selezionata, fai clic su Altre azioni () e poi su Modifica tag.

5. Elimina il tag e fai clic su SALVA.

gcloud

Esegui questo comando:

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

Dove

• TAG è il tag da applicare al pacchetto.
• PACKAGE è il nome del pacchetto nel repository.
• LOCATION è una località a livello di una o più regioni. Utilizza questo flag per visualizzare i repository in una località specifica. Se hai configurato una località predefinita, puoi omettere questo flag per utilizzare quella predefinita.
• REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.

Ad esempio, per rimuovere il tag release-candidate dal pacchetto my-package nel repository my-repo nella posizione predefinita, esegui questo comando:

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

Installazione dei pacchetti

Modalità repository: standard, remoto, virtuale

Per installare un pacchetto dal repository dei pacchetti Node.js:

1. Se usi l'helper per le credenziali per l'autenticazione con un token di accesso, richiedi un nuovo token.

2. Utilizza il comando npm install o yarn add.

   npm

   Per installare la versione con il tag latest:

   npm install @SCOPE/PACKAGE
   

   Per installare la versione con un tag diverso:

   npm install @SCOPE/PACKAGE@TAG
   

   Per installare una versione specifica:

   npm install @SCOPE/PACKAGE@VERSION
   

   filo

   Per installare la versione con il tag latest:

   yarn add @SCOPE/PACKAGE
   

   Per installare la versione con un tag diverso:

   yarn add @SCOPE/PACKAGE@TAG
   

   Per installare una versione specifica:

   yarn add @SCOPE/PACKAGE@VERSION
   

   Sostituisci i seguenti valori:

   • SCOPE è l'ambito associato al repository. Se il repository dei pacchetti Node.js non è configurato con un ambito, ometti @SCOPE/ dal comando.
   • PACKAGE è il nome del pacchetto nel repository.
   • TAG è il tag relativo alla versione da installare.
   • VERSION è il numero di versione da installare.

Quando specifichi un pacchetto come dipendenza in package.json, assicurati di includere l'ambito del repository. L'esempio seguente mostra l'ambito @dev-repo per un pacchetto denominato my-package.

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

Per i repository standard, è possibile scaricare un pacchetto direttamente dal repository.

Per un repository remoto, scarichi una copia memorizzata nella cache del pacchetto e delle sue dipendenze. Se non esiste una copia memorizzata nella cache, il repository remoto scarica il pacchetto dall'origine a monte e lo memorizza nella cache prima di fornirtelo. Puoi verificare che il repository remoto abbia recuperato i pacchetti dall'origine upstream visualizzando l'elenco dei pacchetti nel repository.

Per un repository virtuale, Artifact Registry cerca il pacchetto richiesto nei repository upstream.

• I repository remoti upstream scaricheranno e memorizzeranno nella cache il pacchetto richiesto se non esiste una copia memorizzata nella cache. I repository virtuali gestiscono solo i pacchetti richieste, non li archiviano.
• Se richiedi una versione disponibile in più di un repository upstream, Artifact Registry sceglie un repository upstream da utilizzare in base alle impostazioni di priorità configurate per il repository virtuale.

Ad esempio, considera un repository virtuale con le seguenti impostazioni di priorità per i repository upstream:

• main-repo: priorità impostata su 100
• secondary-repo1: priorità impostata su 80.
• secondary-repo2: priorità impostata su 80.
• test-repo: priorità impostata su 20.

main-repo ha il valore di priorità più alto, quindi il repository virtuale cerca sempre per primo.

Sia secondary-repo1 che secondary-repo2 hanno la priorità impostata su 80. Se un pacchetto richiesto non è disponibile in main-repo, Artifact Registry esegue successivamente ricerche in questi repository. Poiché hanno entrambi lo stesso valore di priorità, Artifact Registry può scegliere di gestire un pacchetto da entrambi i repository se la versione è disponibile in entrambi.

test-repo ha il valore di priorità più basso e gestirà un artefatto archiviato se nessuno degli altri repository a monte lo dispone.

Eliminazione dei pacchetti

Modalità repository: standard, remoto

Puoi eliminare un pacchetto e tutte le relative versioni oppure eliminare una versione specifica.

• L'eliminazione di un pacchetto non può essere annullata.
• Per i repository remoti viene eliminata solo la copia memorizzata nella cache del pacchetto. L'origine upstream non è interessata. Se elimini un pacchetto memorizzato nella cache, Artifact Registry lo scaricherà e lo memorizzerà di nuovo nella cache la prossima volta che il repository riceverà una richiesta per la stessa versione del pacchetto.

Dopo aver pubblicato la versione di un pacchetto, non puoi ripubblicare un pacchetto con la stessa combinazione di nome e versione, anche dopo aver eliminato la versione. Questa è una restrizione npm per garantire che i contenuti di una versione pubblicata del pacchetto siano sempre gli stessi.

Se vuoi incoraggiare gli utenti a installare una versione aggiornata del pacchetto, utilizza il comando npm deprecate per contrassegnare la versione precedente del pacchetto come deprecata. Quando un utente tenta di installare il pacchetto obsoleto, Artifact Registry restituisce un avviso di deprecazione.

Prima di eliminare un pacchetto o una versione del pacchetto, verifica di aver comunicato o risolto eventuali dipendenze importanti.

Per eliminare un pacchetto:

Console

1. Apri la pagina Repositories nella console Google Cloud.

   Apri la pagina Repository

2. Nell'elenco dei repository, fai clic su quello appropriato.

   Nella pagina Pacchetti sono elencati i pacchetti nel repository.

3. Seleziona il pacchetto da eliminare.

4. Fai clic su ELIMINA.

5. Nella finestra di dialogo di conferma, fai clic su ELIMINA.

gcloud

Esegui questo comando:

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

Dove

• PACKAGE è il nome del pacchetto nel repository.
• REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.
• LOCATION è una località a livello di una o più regioni. Utilizza questo flag per visualizzare i repository in una località specifica. Se hai configurato una località predefinita, puoi omettere questo flag per utilizzare quella predefinita.
• --async Torna immediatamente, senza attendere il completamento dell'operazione in corso.

Per eliminare le versioni di un pacchetto:

Console

1. Apri la pagina Repositories nella console Google Cloud.

   Apri la pagina Repository

2. Nell'elenco dei repository, fai clic su quello appropriato.

   Nella pagina Pacchetti sono elencati i pacchetti nel repository.

3. Fai clic su un pacchetto per visualizzare le relative versioni.

4. Seleziona le versioni da eliminare.

5. Fai clic su ELIMINA.

6. Nella finestra di dialogo di conferma, fai clic su ELIMINA.

gcloud

Esegui questo comando:

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

Dove

• PACKAGE è il nome del pacchetto nel repository.
• REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.
• LOCATION è una località a livello di una o più regioni. Utilizza questo flag per visualizzare i repository in una località specifica. Se hai configurato una località predefinita, puoi omettere questo flag per utilizzare quella predefinita.
• --async viene restituito immediatamente, senza attendere il completamento dell'operazione in corso.

Passaggi successivi

• Scopri di più sulla gestione dei pacchetti Maven
• Scopri di più sulla gestione delle immagini container