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 cliente para o 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 cliente para o Registro de Contêiner do Azure para:
- Listar imagens ou artefatos em um registro
- Obter metadados para imagens e artefatos, repositórios e tags
- Definir propriedades de leitura/gravação/exclusão em itens do Registro
- Excluir imagens e artefatos, repositórios e tags
O Registro de Contêiner do Azure também tem uma biblioteca de gerenciamento para operações de plano de controle, incluindo criação e atualizações do Registro.
Pré-requisitos
Você precisa de uma assinatura do Azure e um registro de contêiner do Azure para usar essa biblioteca.
Para criar um novo registro de contêiner do Azure, você pode usar 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 uma ou mais imagens de contêiner para o registro. Para conhecer as etapas, consulte Enviar sua primeira imagem para o registro de contêiner do Azure usando a CLI do Docker.
Conceitos-chave
- Um registro de contêiner do Azure armazena imagens de contêiner e artefatos OCI.
- Uma imagem ou artefato consiste em um manifesto e camadas.
- Um manifesto descreve as camadas que compõem a imagem ou artefato. É identificado de forma única pelo seu resumo.
- Uma imagem ou artefato também pode ser marcado para dar a ele um alias legível por humanos. Uma imagem ou artefato pode ter zero ou mais tags associadas a ela, e cada tag identifica exclusivamente a imagem.
- Uma coleção de imagens ou artefatos que compartilham o mesmo nome, mas têm tags diferentes, é um repositório.
Para obter mais informações, consulte Sobre registros, repositórios e artefatos.
Começar agora
Exemplos de referência | de API do pacote de código-fonte | (NuGet)API |
Para desenvolver o código do aplicativo .NET que pode se conectar a uma instância do Registro de Contêiner do Azure, você precisará da Azure.Containers.ContainerRegistry
biblioteca.
Instalar o pacote
Instale a biblioteca de cliente do Registro de Contêiner do Azure para .NET com NuGet:
dotnet add package Azure.Containers.ContainerRegistry --prerelease
Autenticar o cliente
Para que seu aplicativo se conecte ao seu registro, você precisará criar um ContainerRegistryClient
que possa autenticar com ele. Use a biblioteca de Identidade do Azure para adicionar suporte ao Microsoft Entra ID para autenticar clientes do SDK do Azure com seus serviços correspondentes do Azure.
Ao desenvolver e depurar seu aplicativo localmente, você pode usar seu próprio usuário para autenticar com seu registro. Uma maneira de fazer isso é autenticar seu usuário com a CLI do Azure e executar seu aplicativo a partir desse ambiente. Se seu aplicativo estiver usando um cliente que foi construído para autenticar com DefaultAzureCredential
o , ele será autenticado corretamente com o 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
});
Consulte o Leiame do Azure Identity para obter mais abordagens de autenticação com DefaultAzureCredential
o , tanto localmente quanto em ambientes de implantação. Para se conectar a registros em nuvens do Azure não públicas, consulte a referência da API.
Para obter mais informações sobre como usar o Microsoft Entra ID com o Registro de Contêiner do Azure, consulte a visão geral da autenticação.
Exemplos
Cada exemplo pressupõe que há uma REGISTRY_ENDPOINT
variável de ambiente definida como uma cadeia de caracteres que contém o prefixo https://
e o nome do servidor de login, por exemplo "https://myregistry.azurecr.io".
Os exemplos a seguir usam APIs assíncronas que retornam uma tarefa. APIs síncronas também estão disponíveis.
Listar repositórios de forma assíncrona
Iterar através da 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 de artefato de forma 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 forma 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();
}
}
Começar agora
Exemplos de referência | de API do pacote de código-fonte | (Maven)API |
Ambientes atualmente suportados
- Java Development Kit (JDK), versão 8 ou posterior.
Inclua 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 Identidade do Azure fornece suporte ao Microsoft Entra ID para autenticação.
Os exemplos a seguir pressupõem que você tenha uma cadeia de caracteres de ponto de extremidade do Registro contendo 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 como usar o Microsoft Entra ID com o Registro de Contêiner do Azure, consulte a visão geral da autenticação.
Exemplos
Cada exemplo pressupõe que há uma cadeia de caracteres de ponto de extremidade do Registro contendo o prefixo https://
e o nome do servidor de login, por exemplo "https://myregistry.azurecr.io".
Listar nomes de repositórios
Iterar através da 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));
Eliminar 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();
});
}
Começar agora
Exemplos de referência | de API do pacote de código-fonte | (npm)API |
Ambientes atualmente suportados
Consulte a nossa política de suporte para obter mais detalhes.
Instalar o pacote @azure/container-registry
Instale a biblioteca de cliente do Container Registry para JavaScript com npm
:
npm install @azure/container-registry
Autenticar o cliente
A biblioteca de Identidade do Azure fornece 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 como usar o Microsoft Entra ID com o Registro de Contêiner do Azure, consulte a visão geral da autenticação.
Exemplos
Cada exemplo pressupõe que há 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 login, por exemplo "https://myregistry.azurecr.io".
Listar repositórios de forma assíncrona
Iterar através da 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 de artefato de forma 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 forma 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);
});
Começar agora
Exemplos de referência | do pacote de código | fonte (Pypi)API |
Instalar o pacote
Instale a biblioteca de cliente do Registro de Contêiner do Azure para Python com pip:
pip install --pre azure-containerregistry
Autenticar o cliente
A biblioteca de Identidade do Azure fornece suporte ao Microsoft Entra ID para autenticação. O DefaultAzureCredential
pressupõe que as AZURE_CLIENT_ID
variáveis , AZURE_TENANT_ID
, e AZURE_CLIENT_SECRET
ambiente são definidas. Para obter mais informações, consulte Variáveis de ambiente do Azure Identity.
# 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 exemplo pressupõe que há uma CONTAINERREGISTRY_ENDPOINT
variável de ambiente definida como uma cadeia de caracteres que contém o prefixo https://
e o nome do servidor de login, por exemplo "https://myregistry.azurecr.io".
Listar tags de forma 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 de artefato de forma assíncrona
Este exemplo pressupõe que o registro tenha um repositório hello-world
com imagem marcada 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 forma 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]
Começar agora
Pacote de código-fonte (pkg.go.dev) | Referência da API REST |
Instalar o pacote
Instale a biblioteca de cliente do Registro de Contêiner do Azure para 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ê pode usar azidentity. NewDefaultAzureCredential para autenticar. Recomendamos o uso de 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 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 do contêiner é "https://myregistry.azurecr.io".
Listar etiquetas
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 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)
}
Eliminar 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)
}
}
}
}
}
}
Clean up resources (Limpar recursos)
Se quiser limpar e remover um registro de contêiner do Azure, você pode excluir o recurso ou grupo de recursos. A exclusão do grupo de recursos também exclui quaisquer outros recursos associados a ele.
Próximos passos
Neste início rápido, você aprendeu sobre como usar a biblioteca de cliente do Registro de Contêiner do Azure para executar operações em imagens e artefatos em seu registro de contêiner.
Para obter mais informações, consulte a documentação de referência da API:
Saiba mais sobre a API REST do Registro de Contêiner do Azure.