Guida introduttiva: Usare le librerie client di Registro Azure Container
Usare questo articolo per iniziare a usare la libreria client per Registro Azure Container. Seguire questa procedura per provare il codice di esempio per le operazioni del piano dati su immagini e artefatti.
Usare la libreria client per Registro Azure Container per:
- Elencare immagini o artefatti in un registro
- Ottenere metadati per immagini e artefatti, repository e tag
- Impostare le proprietà di lettura/scrittura/eliminazione per gli elementi del registro
- Eliminare immagini e artefatti, repository e tag
Registro Azure Container include anche una libreria di gestione per le operazioni del piano di controllo, tra cui la creazione e gli aggiornamenti del registro.
Prerequisiti
Per usare questa libreria è necessaria una sottoscrizione di Azure e un Registro Azure Container.
Per creare un nuovo Registro Azure Container, è possibile usare il portale di Azure, Azure PowerShello l'interfaccia della riga di comando di Azure. Di seguito è riportato un esempio basato sull'uso dell'interfaccia della riga di comando di Azure:
az acr create --name MyContainerRegistry --resource-group MyResourceGroup \ --location westus --sku Basic
Eseguire il push di una o più immagini del contenitore nel registro. Per informazioni sulla procedura, vedere Effettuare il push della prima immagine nel Registro Azure Container tramite l'interfaccia della riga di comando di Docker.
Concetti chiave
- Un Registro Azure Container archivia le immagini dei contenitori e gli artefatti OCI.
- Un'immagine o un artefatto è costituito da un manifesto e livelli.
- Un manifesto descrive i livelli che costituiscono l'immagine o l'artefatto. Viene identificato in modo univoco dal digest.
- Un'immagine o un artefatto può anche essere contrassegnato per assegnargli un alias leggibile. A un'immagine o a un artefatto possono essere associati zero o più tag dove ogni tag identifica in modo univoco l'immagine.
- Una raccolta di immagini o artefatti che condividono lo stesso nome, ma hanno tag diversi, è un repository.
Per altre informazioni, vedere Informazioni su registri, i repository e le immagini.
Operazioni preliminari
Codice sorgente | Pacchetto (NuGet) | Riferimento API | Esempi
Per sviluppare il codice dell'applicazione .NET in grado di connettersi a un'istanza di Registro Azure Container, è necessaria la libreria Azure.Containers.ContainerRegistry
.
Installare il pacchetto
Installare la libreria client di Registro Azure Container per .NET con NuGet:
dotnet add package Azure.Containers.ContainerRegistry --prerelease
Autenticare il client
Per consentire all’applicazione di connettersi al registro, è necessario creare un ContainerRegistryClient
che possa eseguire l'autenticazione con esso. Usare la libreria di identità di Azure per aggiungere il supporto di Microsoft Entra ID per l'autenticazione dei client Azure SDK con i servizi di Azure corrispondenti.
Quando si sviluppa e si esegue il debug dell'applicazione in locale, è possibile usare il proprio utente per eseguire l'autenticazione con il registro. Un modo per eseguire questa operazione consiste nell'autenticare l'utente con l'interfaccia della riga di comando di Azure ed eseguire l'applicazione da questo ambiente. Se l'applicazione usa un client costruito per l'autenticazione con DefaultAzureCredential
, eseguirà correttamente l'autenticazione con il registro nell'endpoint specificato.
// 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
});
Per altri approcci all'autenticazione conDefaultAzureCredential
, sia in locale che negli ambienti di distribuzione, vedere README di Identità di Azure. Per connettersi ai registri in cloud di Azure non pubblici, vedere il riferimento all’API.
Per altre informazioni sull'uso di Microsoft Entra ID con Registro Azure Container, vedere Panoramica dell'autenticazione.
Esempi
Ogni esempio presuppone che esista una variabile di ambiente REGISTRY_ENDPOINT
impostata su una stringa contenente il prefisso https://
e il nome del server di accesso, ad esempio "https://myregistry.azurecr.io".
Gli esempi seguenti usano API asincrone che restituiscono un'attività. Sono disponibili anche API sincrone.
Elencare i repository in modo asincrono
Scorrere la raccolta di repository nel 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);
}
Impostare le proprietà degli artefatti in modo asincrono
// 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);
}
Eliminare le immagini in modo asincrono
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();
}
}
Operazioni preliminari
Codice sorgente | Pacchetto (Maven) | Riferimento API | Esempi
Ambienti attualmente supportati
- Java Development Kit (JDK), versione 8 o successiva.
Includere il pacchetto
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-containers-containerregistry</artifactId>
<version>1.0.0-beta.3</version>
</dependency>
Autenticare il client
La libreria di Identità di Azure fornisce il supporto di Microsoft Entra ID per l'autenticazione.
Gli esempi seguenti presuppongono che sia presente una stringa dell'endpoint del registro contenente il prefisso https://
e il nome del server di accesso, ad esempio "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();
Per altre informazioni sull'uso di Microsoft Entra ID con Registro Azure Container, vedere Panoramica dell'autenticazione.
Esempi
Ogni esempio presuppone che sia presente una stringa di endpoint del registro contenente il prefisso https://
e il nome del server di accesso, ad esempio "https://myregistry.azurecr.io".
Elencare i nomi dei repository
Scorrere la raccolta di repository nel registro.
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
.endpoint(endpoint)
.credential(credential)
.buildClient();
client.listRepositoryNames().forEach(repository -> System.out.println(repository));
Modificare le proprietà degli elementi
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));
Eliminare le immagini
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();
});
}
Operazioni preliminari
Codice sorgente | Pacchetto (npm) | Riferimento API | Esempi
Ambienti attualmente supportati
Per altre informazioni, vedere i criteri di supporto.
Installare il pacchetto @azure/container-registry
Installare la libreria client del Registro Container per JavaScript con npm
:
npm install @azure/container-registry
Autenticare il client
La libreria di Identità di Azure fornisce il supporto di Microsoft Entra ID per l'autenticazione.
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());
Per altre informazioni sull'uso di Microsoft Entra ID con Registro Azure Container, vedere Panoramica dell'autenticazione.
Esempi
Ogni esempio presuppone che esista una variabile di ambiente CONTAINER_REGISTRY_ENDPOINT
impostata su una stringa contenente il prefisso https://
e il nome del server di accesso, ad esempio "https://myregistry.azurecr.io".
Elencare i repository in modo asincrono
Scorrere la raccolta di repository nel 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);
});
Impostare le proprietà degli artefatti in modo asincrono
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);
});
Eliminare le immagini in modo asincrono
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);
});
Operazioni preliminari
Codice sorgente | Pacchetto (Pypi) | Riferimento API | Esempi
Installare il pacchetto
Installare la libreria client di Registro Azure Container per Python con pip:
pip install --pre azure-containerregistry
Autenticare il client
La libreria di Identità di Azure fornisce il supporto di Microsoft Entra ID per l'autenticazione. DefaultAzureCredential
presuppone che siano impostate le variabili di ambiente AZURE_CLIENT_ID
, AZURE_TENANT_ID
e AZURE_CLIENT_SECRET
. Per altre informazioni, vedere Variabili di ambiente di Identità di 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())
Esempi
Ogni esempio presuppone che esista una variabile di ambiente CONTAINERREGISTRY_ENDPOINT
impostata su una stringa contenente il prefisso https://
e il nome del server di accesso, ad esempio "https://myregistry.azurecr.io".
Elencare i tag in modo asincrono
In questo esempio si presuppone che il registro abbia un repository 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")
Impostare le proprietà degli artefatti in modo asincrono
In questo esempio si presuppone che il registro abbia un repository hello-world
con l'immagine con tag 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.
Eliminare le immagini in modo asincrono
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]
Operazioni preliminari
Codice sorgente | Pacchetto (pkg.go.dev) | Riferimenti API REST
Installare il pacchetto
Installare la libreria client di Registro Azure Container per Go con go get
:
go get github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry
Autenticare il client
Quando si sviluppa e si esegue il debug dell'applicazione in locale, è possibile usare azidentity. NewDefaultAzureCredential per l'autenticazione. È consigliabile usare un'identità gestita in un ambiente di produzione.
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)
}
}
Per altre informazioni sugli altri approcci di autenticazione, vedere la documentazione di azidentity.
Esempi
Ogni esempio presuppone che l'URL dell'endpoint del registro contenitori sia "https://myregistry.azurecr.io".
Elencare tag
In questo esempio si presuppone che il registro abbia un repository 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)
}
}
}
Modificare le proprietà degli elementi
In questo esempio si presuppone che il registro abbia un repository hello-world
con l'immagine con tag 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)
}
Eliminare le immagini
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)
}
}
}
}
}
}
Pulire le risorse
Per pulire e rimuovere una registro contenitori di Azure, è possibile eliminare la risorsa o il gruppo di risorse. L'eliminazione del gruppo di risorse comporta anche l'eliminazione di tutte le altre risorse associate.
Passaggi successivi
In questa guida introduttiva si è appreso come usare la libreria client di Registro Azure Container per eseguire operazioni su immagini e artefatti nel registro contenitori.
Per altre informazioni, vedere la documentazione di riferimento delle API:
Informazioni sull'API REST di Registro Azure Container.