Guida introduttiva: Usare le librerie client di Registro Azure Container

  • Articolo

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 di sistema
  • Eliminare immagini e artefatti, repository e tag

Registro Azure Container dispone anche di una libreria di gestione per le operazioni del piano di controllo, tra cui la creazione e gli aggiornamenti del Registro di sistema.

Prerequisiti

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 e 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, repository e artefatti.

Introduzione

Esempi di riferimento | per il pacchetto del codice | sorgente (NuGet)API |

Per sviluppare codice dell'applicazione .NET in grado di connettersi a un'istanza di Registro Azure Container, è necessaria la Azure.Containers.ContainerRegistry libreria .

Installare il pacchetto

Installare la libreria client Registro Azure Container per .NET con NuGet:

dotnet add package Azure.Containers.ContainerRegistry --prerelease

Autenticare il client

Affinché l'applicazione si connetta al registro, è necessario creare un ContainerRegistryClient oggetto che possa eseguire l'autenticazione con esso. Usare la libreria di identità di Azure per aggiungere il supporto 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 di sistema 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 con DefaultAzureCredential, 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 le informazioni di riferimento sulle API.

Per altre informazioni sull'uso di Microsoft Entra ID con Registro Azure Container, vedere la panoramica dell'autenticazione.

Esempi

Ogni esempio presuppone che esista una REGISTRY_ENDPOINT variabile di ambiente impostata su una stringa contenente il https:// prefisso 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 di sistema.

// 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();
    }
}

Introduzione

Esempi di riferimento | dell'API del pacchetto di codice | sorgente (Maven) |

Ambienti attualmente supportati

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 di sistema contenente il https:// prefisso 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 la panoramica dell'autenticazione.

Esempi

Ogni esempio presuppone che sia presente una stringa di endpoint del Registro di sistema contenente il https:// prefisso 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 di sistema.

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryClient client = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildClient();

client.listRepositoryNames().forEach(repository -> System.out.println(repository));

Impostare le proprietà dell'artefatto

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();
        });
}

Introduzione

Esempi di riferimento | api del pacchetto del codice | sorgente (npm) |

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 la panoramica dell'autenticazione.

Esempi

Ogni esempio presuppone che esista una CONTAINER_REGISTRY_ENDPOINT variabile di ambiente impostata su una stringa contenente il https:// prefisso 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 di sistema.

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);
});

Introduzione

Esempi di riferimento | dell'API del pacchetto di codice | sorgente (Pypi)API |

Installare il pacchetto

Installare la libreria client 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 AZURE_CLIENT_IDvariabili di ambiente , AZURE_TENANT_IDe AZURE_CLIENT_SECRET . Per altre informazioni, vedere Variabili di ambiente di 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())

Esempi

Ogni esempio presuppone che esista una CONTAINERREGISTRY_ENDPOINT variabile di ambiente impostata su una stringa contenente il https:// prefisso 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 di sistema 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 di sistema 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]

Introduzione

Informazioni di riferimento sulle API REST del pacchetto del codice | sorgente (pkg.go.dev) |

Installare il pacchetto

Installare la libreria client 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 di sistema 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)
		}
	}
}

Impostare le proprietà dell'artefatto

In questo esempio si presuppone che il Registro di sistema 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

Se si vuole pulire e rimuovere un registro Azure Container, è 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 Registro Azure Container per eseguire operazioni su immagini e artefatti nel registro contenitori.