Esta página foi traduzida pela API Cloud Translation.

Faça a gestão de pacotes Node.js

Esta página descreve as seguintes tarefas:

Ver e eliminar pacotes e versões de pacotes
Ver, criar, atualizar e eliminar etiquetas

Antes de começar

Se o repositório de destino não existir, crie um novo repositório.
Verifique se tem as autorizações necessárias para o repositório.
Configure a autenticação para o npm.
(Opcional) Configure as predefinições para os comandos gcloud.
Se estiver a usar o auxiliar de credenciais do npm para autenticação, obtenha um token de acesso antes de se ligar a um repositório com o npm.

Funções necessárias

Para receber as autorizações de que precisa para gerir pacotes, peça ao seu administrador para lhe conceder as seguintes funções do IAM no repositório:

Ver pacotes, ficheiros em pacotes e etiquetas: Leitor do Artifact Registry (roles/artifactregistry.reader)
Transferir ou instalar pacotes: Leitor do Artifact Registry (roles/artifactregistry.reader)
Adicione pacotes a um repositório: Escritor do Artifact Registry (roles/artifactregistry.writer)
Eliminar pacotes: Administrador do repositório do Artifact Registry (roles/artifactregistry.repoAdmin)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Obter um token de acesso

As chaves de acesso são válidas durante 60 minutos. Gere um token de acesso pouco tempo antes de executar comandos que interagem com repositórios.

Para obter um token, use uma destas opções:

Use o comando npx para atualizar a chave de acesso.
1. Certifique-se de que as credenciais para estabelecer ligação ao registo npm público estão no ficheiro de configuração npm do utilizador, ~/.npmrc.
2. Execute o seguinte comando no diretório do projeto Node.js.
```
npx google-artifactregistry-auth
```
  Se o seu repositório do Artifact Registry estiver definido como o registo global e os seus pacotes não estiverem no âmbito, use o seguinte comando para que o comando possa transferir o auxiliar de credenciais do registo npm público em vez do seu repositório do Artifact Registry.
```
npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
```

Adicione um script ao ficheiro package.json no seu projeto.

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

Execute o script no diretório do projeto Node.js.

npm run artifactregistry-login

O Artifact Registry lê as definições do repositório do Artifact Registry no ficheiro .npmrc do projeto e usa-as para adicionar credenciais de token ao ficheiro .npmrc do utilizador. Armazenar o token no ficheiro .npmrc do utilizador isola as suas credenciais do código-fonte e do sistema de controlo de origem.

Adicionar pacotes

Modos de repositório: padrão

Só pode publicar uma versão específica de um pacote uma vez. Esta é uma restrição do npm para garantir que o conteúdo de uma versão de pacote publicada é sempre o mesmo. Por conseguinte, não pode:

Substituir uma versão de um pacote publicando-a novamente no repositório
Remover um pacote ou a respetiva versão do repositório e, em seguida, publicar um pacote com o mesmo nome e número de versão

Se não especificar uma etiqueta quando publica um pacote, o npm adiciona a etiqueta latest. Para simplificar a instalação dos seus pacotes numa fase de desenvolvimento específica, considere publicar os pacotes com uma etiqueta, como beta ou dev.

O Artifact Registry aplica nomes de pacotes alfanuméricos em minúsculas para pacotes npm.

Para adicionar um pacote:

Certifique-se de que o nome do pacote em package.json inclui o âmbito configurado para o seu repositório. O exemplo seguinte mostra um pacote com o âmbito dev-repo.
```
"name": "@dev-repo/my-package"
```
Se estiver a usar o auxiliar de credenciais para autenticar com um token de acesso, obtenha um novo token.
Adicione pacotes ao repositório. Pode usar um comando npm ou yarn.

Para etiquetar o pacote, inclua a flag --tag e substitua TAG pela etiqueta que quer usar. Se não incluir o sinalizador --tag, o npm define automaticamente a etiqueta como latest.
```
npm publish --tag=TAG
```
```
yarn publish --tag TAG
```

Visualizar pacotes e versões

Modos de repositório: padrão, remoto, virtual

Para receber informações sobre encomendas com o npm ou o yarn:

Se estiver a usar o auxiliar de credenciais para autenticar com um token de acesso, obtenha um novo token.
Execute o comando adequado:
```
npm view
```
```
yarn info
```

Para conferir pacotes e versões de pacotes usando o console Google Cloud ou gcloud:

Console

Abra a página Repositórios no console do Google Cloud .

Abra a página Repositórios
Na lista de repositórios, clique no repositório apropriado.

A página Pacotes lista os pacotes no repositório.
Clique em um pacote para visualizar as versões dele.

gcloud

Para listar pacotes em um repositório, execute o seguinte comando:

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

Substitua:

REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa flag para usar o padrão.
LOCATION é o local regional ou multirregional do repositório. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.

Para ver as versões de um pacote, execute o seguinte comando:

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

Substitua:

PACKAGE é o ID do pacote ou o identificador totalmente qualificado do pacote.
REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa flag para usar o padrão.
LOCATION é o local regional ou multirregional do repositório. Use esta flag para conferir repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.

A visualização de pacotes e versões a partir da Google Cloud consola ou da CLI gcloud só está disponível para repositórios padrão e remotos.

Para repositórios remotos, a lista devolvida deve incluir todas as dependências diretas e transitivas que estão em cache no repositório.

Listar ficheiros

Modos de repositório: padrão, remoto

Pode listar ficheiros num repositório, ficheiros em todas as versões de um pacote especificado ou ficheiros numa versão específica de um pacote.

Para todos os comandos seguintes, pode definir um número máximo de ficheiros a devolver adicionando a flag --limit ao comando.

Para listar todos os ficheiros no projeto, repositório e localização predefinidos quando os valores predefinidos estão configurados:

gcloud artifacts files list

Para listar ficheiros num projeto, num repositório e numa localização especificados, execute o comando:

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

Para listar ficheiros de todas as versões de um pacote específico:

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

Para listar ficheiros de uma versão específica de um pacote:

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

Para listar ficheiros de uma etiqueta específica:

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

Substitua os seguintes valores:

LOCATION: a localização regional ou multirregional do repositório.
PROJECT: o seu Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte o artigo Projetos com âmbito de domínio.
REPOSITORY: o nome do repositório onde a imagem está armazenada.
PACKAGE: o nome do pacote.
VERSION: a versão do pacote.
TAG: a etiqueta associada ao pacote.

Exemplos

Considere as seguintes informações do pacote:

Projeto: my-project
Repositório: my-repo
Localização do repositório: us-west1
Pacote: my-app

O comando seguinte lista todos os ficheiros no repositório my-repo na localização us-west1 no projeto predefinido:

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

O seguinte comando lista os ficheiros na versão 1.0 do pacote.

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

O comando seguinte lista os ficheiros na versão do pacote com a etiqueta 1.0-dev

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

Etiquetagem de pacotes

Modos de repositório: padrão

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

Open the Repositories page in the Google Cloud console.

Abra a página Repositórios
Click the package to view versions and the associated tags.
Select the package version to tag.
In the row of the selected version, click More actions (), and then click Edit tags.
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

Open the Repositories page in the Google Cloud console.

Abra a página Repositórios
Click the package to view versions of the package.
Select the package version to tag.
In the row of the selected version, click More actions (), and then click Edit tags.
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

Open the Repositories page in the Google Cloud console.

Abra a página Repositórios
Click the package to view versions of the package.
Select the package version with the tag to change.
In the row of the selected version, click More actions (), and then click Edit tags.
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

Open the Repositories page in the Google Cloud console.

Abra a página Repositórios
Click the image to view versions of the image.
Select the image version to untag.
In the row of the selected version, click More actions (), and then click Edit tags.
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

Instalar pacotes

Modos de repositório: padrão, remoto, virtual

Para instalar um pacote a partir do repositório de pacotes do Node.js:

Se estiver a usar o auxiliar de credenciais para autenticar com um token de acesso, obtenha um novo token.
Use o comando npm install ou yarn add.
npm
Para instalar a versão com a etiqueta latest:
```
npm install @SCOPE/PACKAGE
```
Para instalar a versão com uma etiqueta diferente:
```
npm install @SCOPE/PACKAGE@TAG
```
Para instalar uma versão específica:
```
npm install @SCOPE/PACKAGE@VERSION
```
fio
Para instalar a versão com a etiqueta latest:
```
yarn add @SCOPE/PACKAGE
```
Para instalar a versão com uma etiqueta diferente:
```
yarn add @SCOPE/PACKAGE@TAG
```
Para instalar uma versão específica:
```
yarn add @SCOPE/PACKAGE@VERSION
```
Substitua os seguintes valores:
- SCOPE é o âmbito associado ao repositório. Se o repositório de pacotes Node.js não estiver configurado com um âmbito, omita @SCOPE/ do comando.
- PACKAGE é o nome do pacote no repositório.
- TAG é a etiqueta da versão que quer instalar.
- VERSION é o número da versão que quer instalar.

Quando especifica um pacote como uma dependência em package.json, certifique-se de que inclui o âmbito do repositório. O exemplo seguinte mostra o âmbito @dev-repo para um pacote denominado my-package.

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

Para repositórios padrão, transfere um pacote diretamente do repositório.

Para um repositório remoto, transfere uma cópia em cache do pacote e das respetivas dependências. Se não existir uma cópia em cache, o repositório remoto transfere o pacote da origem a montante e coloca-o em cache antes de o disponibilizar. Pode verificar se o repositório remoto obteve os pacotes da origem a montante vendo a lista de pacotes no repositório.

Para um repositório virtual, o Artifact Registry pesquisa repositórios a montante para o pacote pedido.

Os repositórios remotos a montante transferem e colocam em cache o pacote pedido se não existir uma cópia em cache. Os repositórios virtuais apenas publicam pacotes pedidos e não os armazenam.
Se pedir uma versão que esteja disponível em mais do que um repositório a montante, o Artifact Registry escolhe um repositório a montante para usar com base nas definições de prioridade configuradas para o repositório virtual.

Por exemplo, considere um repositório virtual com as seguintes definições de prioridade para repositórios upstream:

main-repo: prioridade definida como 100
secondary-repo1: prioridade definida como 80.
secondary-repo2: prioridade definida como 80.
test-repo: prioridade definida como 20.

main-repo tem o valor de prioridade mais elevado, pelo que o repositório virtual pesquisa sempre primeiro.

Ambos os elementos secondary-repo1 e secondary-repo2 têm a prioridade definida como 80. Se um pacote pedido não estiver disponível em main-repo, o Artifact Registry pesquisa estes repositórios em seguida. Uma vez que ambos têm o mesmo valor de prioridade, o Artifact Registry pode optar por publicar um pacote de qualquer um dos repositórios se a versão estiver disponível em ambos.

test-repo tem o valor de prioridade mais baixo e vai publicar um artefacto armazenado se nenhum dos outros repositórios a montante o tiver.

Eliminar pacotes

Modos de repositório: padrão, remoto

Pode eliminar um pacote e todas as respetivas versões ou eliminar uma versão específica.

Depois de eliminar um pacote, não pode anular a ação.
Para repositórios remotos, apenas a cópia em cache do pacote é eliminada. A fonte a montante não é afetada. Se eliminar um pacote em cache, o Artifact Registry transfere-o e coloca-o novamente em cache da próxima vez que o repositório receber um pedido para a mesma versão do pacote.

Depois de publicar uma versão do pacote, não pode republicar um pacote com a mesma combinação de nome e versão, mesmo depois de eliminar a versão. Esta é uma restrição do npm para garantir que o conteúdo de uma versão do pacote publicada é sempre o mesmo.

Se quiser incentivar os utilizadores a instalarem uma versão atualizada de um pacote, use o comando npm deprecate para marcar a versão antiga do pacote como descontinuada. Quando um utilizador tenta instalar o pacote descontinuado, o Artifact Registry devolve um aviso de descontinuação.

Antes de excluir uma versão de pacote ou um pacote, verifique se você comunicou ou resolveu qualquer dependência importante nele.

Para excluir um pacote:

Console

Abra a página Repositórios no console do Google Cloud .

Abra a página Repositórios
Na lista de repositórios, clique no repositório apropriado.

A página Pacotes lista os pacotes no repositório.
Selecione o pacote que você quer excluir.
Clique em EXCLUIR.
Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

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

Substitua:

PACKAGE é o nome do pacote no repositório.
REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa flag para usar o padrão.
LOCATION é o local regional ou multirregional do repositório. Use esta flag para conferir repositórios em um local específico. Se você configurou um local padrão, poderá omitir essa flag para usar o padrão.

A flag --async faz com que o comando seja retornado imediatamente, sem aguardar a conclusão da operação em andamento.

Para excluir versões de um pacote:

Console

Abra a página Repositórios no console do Google Cloud .

Abra a página Repositórios
Na lista de repositórios, clique no repositório apropriado.

A página Pacotes lista os pacotes no repositório.
Clique em um pacote para visualizar as versões dele.
Selecione as versões que você quer excluir.
Clique em EXCLUIR.
Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

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

Substitua:

VERSION é o nome da versão a ser excluída.
PACKAGE é o nome do pacote no repositório.
REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa flag para usar o padrão.
LOCATION é o local regional ou multirregional do repositório. Use esta flag para conferir repositórios em um local específico. Se você configurou um local padrão, poderá omitir essa flag para usar o padrão.

A flag --async faz com que o comando seja retornado imediatamente, sem aguardar a conclusão da operação em andamento.

Faça a gestão de pacotes Node.js

Antes de começar

Funções necessárias

Obter um token de acesso

Adicionar pacotes

Visualizar pacotes e versões

Console

gcloud

Listar ficheiros

Exemplos

Etiquetagem de pacotes

Viewing tags

Console

gcloud

Creating tags

Console

gcloud

Updating tags

Console

gcloud

Untagging package versions

Console

gcloud

Instalar pacotes

npm

fio

Eliminar pacotes

Console

gcloud

Console

gcloud

O que se segue?