Guia de Início Rápido: usar as bibliotecas de cliente do Registro de Contêiner do Azure
Use este artigo para começar a usar a biblioteca de clientes do Registro de Contêiner do Azure. Siga estas etapas para experimentar o código de exemplo para operações de plano de dados em imagens e artefatos.
Use a biblioteca de clientes do Registro de Contêiner do Azure para:
- Listar imagens ou artefatos em um registro
- Obter metadados para imagens e artefatos, repositórios e marcas
- Definir propriedades de leitura/gravação/exclusão em itens do registro
- Excluir imagens e artefatos, repositórios e marcas
O Registro de Contêiner do Azure também tem uma biblioteca de gerenciamento para operações de plano de controle, incluindo a criação e as atualizações do registro.
Pré-requisitos
Você precisa de uma assinatura do Azure e de um registro de contêiner do Azure para usar essa biblioteca.
Para criar um registro de contêiner do Azure, use o portal do Azure, o Azure PowerShell ou a CLI do Azure. Aqui, está um exemplo usando a CLI do Azure:
az acr create --name MyContainerRegistry --resource-group MyResourceGroup \ --location westus --sku Basic
Envie por push uma ou mais imagens de contêiner para o registro. Para conhecer as etapas, confira Efetuar push de sua primeira imagem para o registro de contêiner do Azure usando a CLI do Docker.
Principais conceitos
- Um registro de contêiner do Azure armazena imagens de contêiner e artefatos de OCI.
- Uma imagem ou um artefato consiste em um manifesto e em camadas.
- Um manifesto descreve as camadas que compõem a imagem ou o artefato. Ele é identificado exclusivamente por seu código hash.
- Uma imagem ou um artefato também pode ser marcado para ter um alias legível. Uma imagem ou um artefato pode ter zero ou mais marcas associadas e cada marca identifica exclusivamente a imagem.
- Uma coleção de imagens ou artefatos que têm o mesmo nome, mas marcas diferentes, é chamada de repositório.
Para obter mais informações, confira Sobre registros, repositórios e artefatos.
Introdução
Código-fonte | Pacote (NuGet) | Referência da API | Exemplos
Para desenvolver o código do aplicativo .NET que possa se conectar a uma instância do Registro de Contêiner do Azure, você precisará da biblioteca Azure.Containers.ContainerRegistry
.
Instalar o pacote
Instale a biblioteca de clientes do Registro de Contêiner do Azure para o .NET com o NuGet:
dotnet add package Azure.Containers.ContainerRegistry --prerelease
Autenticar o cliente
Para que o aplicativo se conecte ao registro, você precisará criar um ContainerRegistryClient
que possa se autenticar no registro. Use a Biblioteca de Identidades do Azure para adicionar suporte ao Microsoft Entra ID para autenticar clientes SDK do Azure com os serviços do Azure correspondentes.
Ao desenvolver e depurar seu aplicativo localmente, você poderá usar o seu usuário para se autenticar no registro. Uma forma de fazer isso é fazer a autenticação do seu usuário com a CLI do Azure e executar o aplicativo nesse ambiente. Se seu aplicativo estiver usando um cliente que tenha sido construído para autenticar-se com a DefaultAzureCredential
, ele será autenticado corretamente no registro no ponto de extremidade especificado.
// Create a ContainerRegistryClient that will authenticate to your registry through Azure Active Directory
Uri endpoint = new Uri("https://myregistry.azurecr.io");
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(),
new ContainerRegistryClientOptions()
{
Audience = ContainerRegistryAudience.AzureResourceManagerPublicCloud
});
Confira o LEIAME da biblioteca de Identidades do Azure para conhecer outras abordagens para se autenticar com a DefaultAzureCredential
, tanto localmente quanto em ambientes de implantação. Para se conectar a registros em nuvens não públicas do Azure, veja a referência da API.
Para obter mais informações sobre o uso do Microsoft Entra ID com o Registro de Contêiner do Azure, consulte a visão geral sobre autenticação.
Exemplos
Cada amostra supõe que haja uma variável de ambiente REGISTRY_ENDPOINT
definida como uma cadeia de caracteres que contém o prefixo https://
e o nome do servidor de logon, por exemplo "https://myregistry.azurecr.io".
Os exemplos a seguir usam APIs assíncronas que retornam uma tarefa. Também há APIs síncronas disponíveis.
Listar repositórios de maneira assíncrona
Itere na coleção de repositórios no registro.
// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
// Create a new ContainerRegistryClient
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(),
new ContainerRegistryClientOptions()
{
Audience = ContainerRegistryAudience.AzureResourceManagerPublicCloud
});
// Get the collection of repository names from the registry
AsyncPageable<string> repositories = client.GetRepositoryNamesAsync();
await foreach (string repository in repositories)
{
Console.WriteLine(repository);
}
Definir propriedades do artefato de maneira assíncrona
// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
// Create a new ContainerRegistryClient
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(),
new ContainerRegistryClientOptions()
{
Audience = ContainerRegistryAudience.AzureResourceManagerPublicCloud
});
// Get the collection of repository names from the registry
AsyncPageable<string> repositories = client.GetRepositoryNamesAsync();
await foreach (string repository in repositories)
{
Console.WriteLine(repository);
}
Excluir imagens de maneira assíncrona
using System.Linq;
using Azure.Containers.ContainerRegistry;
using Azure.Identity;
// Get the service endpoint from the environment
Uri endpoint = new Uri(Environment.GetEnvironmentVariable("REGISTRY_ENDPOINT"));
// Create a new ContainerRegistryClient
ContainerRegistryClient client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential(),
new ContainerRegistryClientOptions()
{
Audience = ContainerRegistryAudience.AzureResourceManagerPublicCloud
});
// Iterate through repositories
AsyncPageable<string> repositoryNames = client.GetRepositoryNamesAsync();
await foreach (string repositoryName in repositoryNames)
{
ContainerRepository repository = client.GetRepository(repositoryName);
// Obtain the images ordered from newest to oldest
AsyncPageable<ArtifactManifestProperties> imageManifests =
repository.GetManifestPropertiesCollectionAsync(orderBy: ArtifactManifestOrderBy.LastUpdatedOnDescending);
// Delete images older than the first three.
await foreach (ArtifactManifestProperties imageManifest in imageManifests.Skip(3))
{
RegistryArtifact image = repository.GetArtifact(imageManifest.Digest);
Console.WriteLine($"Deleting image with digest {imageManifest.Digest}.");
Console.WriteLine($" Deleting the following tags from the image: ");
foreach (var tagName in imageManifest.Tags)
{
Console.WriteLine($" {imageManifest.RepositoryName}:{tagName}");
await image.DeleteTagAsync(tagName);
}
await image.DeleteAsync();
}
}
Introdução
Código-fonte | Pacote (Maven) | Referência da API | Exemplos
Ambientes com suporte no momento
- JDK (Java Development Kit) versão 8 ou posterior.
Incluir o pacote
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-containers-containerregistry</artifactId>
<version>1.0.0-beta.3</version>
</dependency>
Autenticar o cliente
A Biblioteca de Identidades do Azure oferece suporte ao Microsoft Entra ID para autenticação.
As amostras a seguir pressupõem que você tenha uma cadeia de caracteres do ponto de extremidade do registro que contém o prefixo https://
e o nome do servidor de logon, por exemplo "https://myregistry.azurecr.io".
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(credential)
.buildClient();
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryAsyncClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(credential)
.buildAsyncClient();
Para obter mais informações sobre o uso do Microsoft Entra ID com o Registro de Contêiner do Azure, consulte a visão geral sobre autenticação.
Exemplos
Cada amostra pressupõe que haja uma cadeia de caracteres do ponto de extremidade do registro que contém o prefixo https://
e o nome do servidor de logon, por exemplo "https://myregistry.azurecr.io".
Listar nomes de repositório
Itere na coleção de repositórios no registro.
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(credential)
.buildClient();
client.listRepositoryNames().forEach(repository -> System.out.println(repository));
Definir propriedades do artefato
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(defaultCredential)
.buildClient();
RegistryArtifact image = client.getArtifact(repositoryName, digest);
image.updateTagProperties(
tag,
new ArtifactTagProperties()
.setWriteEnabled(false)
.setDeleteEnabled(false));
Excluir imagens
TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(defaultCredential)
.buildClient();
final int imagesCountToKeep = 3;
for (String repositoryName : client.listRepositoryNames()) {
final ContainerRepository repository = client.getRepository(repositoryName);
// Obtain the images ordered from newest to oldest
PagedIterable<ArtifactManifestProperties> imageManifests =
repository.listManifestProperties(
ArtifactManifestOrderBy.LAST_UPDATED_ON_DESCENDING,
Context.NONE);
imageManifests.stream().skip(imagesCountToKeep)
.forEach(imageManifest -> {
System.out.printf(String.format("Deleting image with digest %s.%n", imageManifest.getDigest()));
System.out.printf(" This image has the following tags: ");
for (String tagName : imageManifest.getTags()) {
System.out.printf(" %s:%s", imageManifest.getRepositoryName(), tagName);
}
repository.getArtifact(imageManifest.getDigest()).delete();
});
}
Introdução
Código-fonte | Pacote (npm) | Referência da API | Exemplos
Ambientes com suporte no momento
Confira nossa política de suporte para mais detalhes.
Instalar o pacote @azure/container-registry
Instale a biblioteca de clientes do Registro de Contêiner para JavaScript com npm
:
npm install @azure/container-registry
Autenticar o cliente
A Biblioteca de Identidades do Azure oferece suporte ao Microsoft Entra ID para autenticação.
const { ContainerRegistryClient } = require("@azure/container-registry");
const { DefaultAzureCredential } = require("@azure/identity");
const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT;
// Create a ContainerRegistryClient that will authenticate through Active Directory
const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
Para obter mais informações sobre o uso do Microsoft Entra ID com o Registro de Contêiner do Azure, consulte a visão geral sobre autenticação.
Exemplos
Cada amostra supõe que haja uma CONTAINER_REGISTRY_ENDPOINT
variável de ambiente definida como uma cadeia de caracteres que contém o prefixo https://
e o nome do servidor de logon, por exemplo "https://myregistry.azurecr.io".
Listar repositórios de maneira assíncrona
Itere na coleção de repositórios no registro.
const { ContainerRegistryClient } = require("@azure/container-registry");
const { DefaultAzureCredential } = require("@azure/identity");
async function main() {
// endpoint should be in the form of "https://myregistryname.azurecr.io"
// where "myregistryname" is the actual name of your registry
const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
console.log("Listing repositories");
const iterator = client.listRepositoryNames();
for await (const repository of iterator) {
console.log(` repository: ${repository}`);
}
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
Definir propriedades do artefato de maneira assíncrona
const { ContainerRegistryClient } = require("@azure/container-registry");
const { DefaultAzureCredential } = require("@azure/identity");
async function main() {
// Get the service endpoint from the environment
const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
// Create a new ContainerRegistryClient and RegistryArtifact to access image operations
const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
const image = client.getArtifact("library/hello-world", "v1");
// Set permissions on the image's "latest" tag
await image.updateTagProperties("latest", { canWrite: false, canDelete: false });
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
Excluir imagens de maneira assíncrona
const { ContainerRegistryClient } = require("@azure/container-registry");
const { DefaultAzureCredential } = require("@azure/identity");
async function main() {
// Get the service endpoint from the environment
const endpoint = process.env.CONTAINER_REGISTRY_ENDPOINT || "<endpoint>";
// Create a new ContainerRegistryClient
const client = new ContainerRegistryClient(endpoint, new DefaultAzureCredential());
// Iterate through repositories
const repositoryNames = client.listRepositoryNames();
for await (const repositoryName of repositoryNames) {
const repository = client.getRepository(repositoryName);
// Obtain the images ordered from newest to oldest by passing the `orderBy` option
const imageManifests = repository.listManifestProperties({
orderBy: "LastUpdatedOnDescending"
});
const imagesToKeep = 3;
let imageCount = 0;
// Delete images older than the first three.
for await (const manifest of imageManifests) {
imageCount++;
if (imageCount > imagesToKeep) {
const image = repository.getArtifact(manifest.digest);
console.log(`Deleting image with digest ${manifest.digest}`);
console.log(` Deleting the following tags from the image:`);
for (const tagName of manifest.tags) {
console.log(` ${manifest.repositoryName}:${tagName}`);
image.deleteTag(tagName);
}
await image.delete();
}
}
}
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
Introdução
Código-fonte | Pacote (Pypi) | Referência da API | Exemplos
Instalar o pacote
Instale a biblioteca de clientes do Registro de Contêiner do Azure para o Python com o pip:
pip install --pre azure-containerregistry
Autenticar o cliente
A Biblioteca de Identidades do Azure oferece suporte ao Microsoft Entra ID para autenticação. A DefaultAzureCredential
pressupões que as variáveis de ambiente AZURE_CLIENT_ID
, AZURE_TENANT_ID
e AZURE_CLIENT_SECRET
estejam definidas. Para obter mais informações, confira Variáveis de ambiente da Identidade do Azure.
# Create a ContainerRegistryClient that will authenticate through Active Directory
from azure.containerregistry import ContainerRegistryClient
from azure.identity import DefaultAzureCredential
account_url = "https://mycontainerregistry.azurecr.io"
client = ContainerRegistryClient(account_url, DefaultAzureCredential())
Exemplos
Cada amostra supõe que haja uma variável de ambiente CONTAINERREGISTRY_ENDPOINT
definida como uma cadeia de caracteres que contém o prefixo https://
e o nome do servidor de logon, por exemplo "https://myregistry.azurecr.io".
Listar marcas de maneira assíncrona
Este exemplo pressupõe que o registro tenha um repositório hello-world
.
import asyncio
from dotenv import find_dotenv, load_dotenv
import os
from azure.containerregistry.aio import ContainerRegistryClient
from azure.identity.aio import DefaultAzureCredential
class ListTagsAsync(object):
def __init__(self):
load_dotenv(find_dotenv())
async def list_tags(self):
# Create a new ContainerRegistryClient
audience = "https://management.azure.com"
account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
credential = DefaultAzureCredential()
client = ContainerRegistryClient(account_url, credential, audience=audience)
manifest = await client.get_manifest_properties("library/hello-world", "latest")
print(manifest.repository_name + ": ")
for tag in manifest.tags:
print(tag + "\n")
Definir propriedades do artefato de maneira assíncrona
Este exemplo pressupõe que o registro tenha um repositório hello-world
com imagem marcada com v1
.
import asyncio
from dotenv import find_dotenv, load_dotenv
import os
from azure.containerregistry.aio import ContainerRegistryClient
from azure.identity.aio import DefaultAzureCredential
class SetImagePropertiesAsync(object):
def __init__(self):
load_dotenv(find_dotenv())
async def set_image_properties(self):
# Create a new ContainerRegistryClient
account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
audience = "https://management.azure.com"
credential = DefaultAzureCredential()
client = ContainerRegistryClient(account_url, credential, audience=audience)
# [START update_manifest_properties]
# Set permissions on the v1 image's "latest" tag
await client.update_manifest_properties(
"library/hello-world",
"latest",
can_write=False,
can_delete=False
)
# [END update_manifest_properties]
# After this update, if someone were to push an update to "myacr.azurecr.io\hello-world:v1", it would fail.
# It's worth noting that if this image also had another tag, such as "latest", and that tag did not have
# permissions set to prevent reads or deletes, the image could still be overwritten. For example,
# if someone were to push an update to "myacr.azurecr.io\hello-world:latest"
# (which references the same image), it would succeed.
Excluir imagens de maneira assíncrona
import asyncio
from dotenv import find_dotenv, load_dotenv
import os
from azure.containerregistry import ManifestOrder
from azure.containerregistry.aio import ContainerRegistryClient
from azure.identity.aio import DefaultAzureCredential
class DeleteImagesAsync(object):
def __init__(self):
load_dotenv(find_dotenv())
async def delete_images(self):
# [START list_repository_names]
audience = "https://management.azure.com"
account_url = os.environ["CONTAINERREGISTRY_ENDPOINT"]
credential = DefaultAzureCredential()
client = ContainerRegistryClient(account_url, credential, audience=audience)
async with client:
async for repository in client.list_repository_names():
print(repository)
# [END list_repository_names]
# [START list_manifest_properties]
# Keep the three most recent images, delete everything else
manifest_count = 0
async for manifest in client.list_manifest_properties(repository, order_by=ManifestOrder.LAST_UPDATE_TIME_DESCENDING):
manifest_count += 1
if manifest_count > 3:
await client.delete_manifest(repository, manifest.digest)
# [END list_manifest_properties]
Introdução
Código-fonte | Pacote (pkg.go.dev) | Referência da API REST
Instalar o pacote
Instale a biblioteca de clientes do Registro de Contêiner do Azure para linguagem Go com go get
:
go get github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry
Autenticar o cliente
Ao desenvolver e depurar seu aplicativo localmente, você poderá usar azidentity.NewDefaultAzureCredential para se autenticar. É recomendável usar uma identidade gerenciada em um ambiente de produção.
import (
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry"
"log"
)
func main() {
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("failed to obtain a credential: %v", err)
}
client, err := azcontainerregistry.NewClient("https://myregistry.azurecr.io", cred, nil)
if err != nil {
log.Fatalf("failed to create client: %v", err)
}
}
Consulte a documentação de azidentity para obter mais informações sobre outras abordagens de autenticação.
Exemplos
Cada exemplo pressupõe que a URL do ponto de extremidade do registro de contêiner é “https://myregistry.azurecr.io".
Listar marcas
Este exemplo pressupõe que o registro tenha um repositório hello-world
.
import (
"context"
"fmt"
"github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry"
"log"
)
func Example_listTagsWithAnonymousAccess() {
client, err := azcontainerregistry.NewClient("https://myregistry.azurecr.io", nil, nil)
if err != nil {
log.Fatalf("failed to create client: %v", err)
}
ctx := context.Background()
pager := client.NewListTagsPager("library/hello-world", nil)
for pager.More() {
page, err := pager.NextPage(ctx)
if err != nil {
log.Fatalf("failed to advance page: %v", err)
}
for _, v := range page.Tags {
fmt.Printf("tag: %s\n", *v.Name)
}
}
}
Definir propriedades do artefato
Este exemplo pressupõe que o registro tenha um repositório hello-world
com imagem marcada com latest
.
package azcontainerregistry_test
import (
"context"
"fmt"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry"
"log"
)
func Example_setArtifactProperties() {
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("failed to obtain a credential: %v", err)
}
client, err := azcontainerregistry.NewClient("https://myregistry.azurecr.io", cred, nil)
if err != nil {
log.Fatalf("failed to create client: %v", err)
}
ctx := context.Background()
res, err := client.UpdateTagProperties(ctx, "library/hello-world", "latest", &azcontainerregistry.ClientUpdateTagPropertiesOptions{
Value: &azcontainerregistry.TagWriteableProperties{
CanWrite: to.Ptr(false),
CanDelete: to.Ptr(false),
}})
if err != nil {
log.Fatalf("failed to finish the request: %v", err)
}
fmt.Printf("repository library/hello-world - tag latest: 'CanWrite' property: %t, 'CanDelete' property: %t\n", *res.Tag.ChangeableAttributes.CanWrite, *res.Tag.ChangeableAttributes.CanDelete)
}
Excluir imagens
package azcontainerregistry_test
import (
"context"
"fmt"
"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
"github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry"
"log"
)
func Example_deleteImages() {
cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("failed to obtain a credential: %v", err)
}
client, err := azcontainerregistry.NewClient("https://myregistry.azurecr.io", cred, nil)
if err != nil {
log.Fatalf("failed to create client: %v", err)
}
ctx := context.Background()
repositoryPager := client.NewListRepositoriesPager(nil)
for repositoryPager.More() {
repositoryPage, err := repositoryPager.NextPage(ctx)
if err != nil {
log.Fatalf("failed to advance repository page: %v", err)
}
for _, r := range repositoryPage.Repositories.Names {
manifestPager := client.NewListManifestsPager(*r, &azcontainerregistry.ClientListManifestsOptions{
OrderBy: to.Ptr(azcontainerregistry.ArtifactManifestOrderByLastUpdatedOnDescending),
})
for manifestPager.More() {
manifestPage, err := manifestPager.NextPage(ctx)
if err != nil {
log.Fatalf("failed to advance manifest page: %v", err)
}
imagesToKeep := 3
for i, m := range manifestPage.Manifests.Attributes {
if i >= imagesToKeep {
for _, t := range m.Tags {
fmt.Printf("delete tag from image: %s", *t)
_, err := client.DeleteTag(ctx, *r, *t, nil)
if err != nil {
log.Fatalf("failed to delete tag: %v", err)
}
}
_, err := client.DeleteManifest(ctx, *r, *m.Digest, nil)
if err != nil {
log.Fatalf("failed to delete manifest: %v", err)
}
fmt.Printf("delete image with digest: %s", *m.Digest)
}
}
}
}
}
}
Limpar os recursos
Caso queria limpar e remover um registro de contêiner do Azure, você pode excluir o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele.
Próximas etapas
Neste guia de início rápido, você aprendeu a usar a biblioteca de clientes do Registro de Contêiner do Azure para executar operações em imagens e artefatos no registro de contêiner.
Para obter mais informações, confira a documentação de referência da API:
Saiba mais sobre a API REST do Registro de Contêiner do Azure.