Inicio rápido: Uso de las bibliotecas cliente de Azure Container Registry

Use este artículo para empezar a trabajar con la biblioteca cliente de Azure Container Registry. Siga estos pasos para probar código de ejemplo para operaciones del plano de datos en imágenes y artefactos.

Use la biblioteca cliente de Azure Container Registry para lo siguiente:

  • Enumeración de imágenes o artefactos en un registro
  • Obtención de metadatos para imágenes y artefactos, repositorios y etiquetas
  • Establecimiento de propiedades de lectura, escritura y eliminación en elementos del registro
  • Eliminación de imágenes y artefactos, repositorios y etiquetas

Azure Container Registry también tiene una biblioteca de administración para las operaciones del plano de control, incluida la creación y las actualizaciones del registro.

Requisitos previos

Conceptos clave

  • Una instancia de Azure Container Registry almacena imágenes de contenedor y artefactos de OCI.
  • Una imagen o artefacto se compone de un manifiesto y capas.
  • Un manifiesto describe las capas que componen la imagen o el artefacto. Se identifica de forma única por su código hash.
  • Una imagen o artefacto también se puede etiquetar para asignarle un alias legible. Una imagen o artefacto puede tener cero o más etiquetas asociadas y cada etiqueta identifica de forma única la imagen.
  • Una colección de imágenes o artefactos que comparten el mismo nombre pero tienen etiquetas diferentes se denomina repositorio.

Para más información, consulte Acerca de los registros, repositorios y artefactos.

Introducción

Código fuente | Paquete (NuGet) | Referencia de API | Ejemplos

Para desarrollar código de aplicación .NET que pueda conectarse a una instancia de Azure Container Registry, necesitará la biblioteca Azure.Containers.ContainerRegistry.

Instalar el paquete

Instale la biblioteca cliente de Azure Container Registry para .NET con NuGet:

dotnet add package Azure.Containers.ContainerRegistry --prerelease

Autenticar el cliente

Para que la aplicación se conecte al registro, deberá crear un cliente ContainerRegistryClient que pueda autenticarse con él. Utilice la biblioteca Azure Identity para agregar compatibilidad con Microsoft Entra ID para autenticar a los clientes del SDK de Azure con sus correspondientes servicios de Azure.

Al desarrollar y depurar la aplicación localmente, puede usar su propio usuario para autenticarse en el registro. Una manera de hacerlo es autenticar el usuario con la CLI de Azure y ejecutar la aplicación desde este entorno. Si la aplicación usa un cliente que se ha construido para autenticarse con DefaultAzureCredential, se autenticará correctamente con el registro en el punto de conexión 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 el archivo Léame de identidad de Azure para obtener más enfoques para la autenticación con DefaultAzureCredential, tanto localmente como en entornos de implementación. Para conectarse a registros en nubes de Azure no públicas, consulte la referencia de API.

Para obtener más información sobre el uso de Microsoft Entra ID con Azure Container Registry, consulte la información general de la autenticación.

Ejemplos

En cada ejemplo se asume que hay una variable de entorno REGISTRY_ENDPOINT establecida en una cadena que contiene el prefijo https:// y el nombre del servidor de inicio de sesión, por ejemplo, "https://myregistry.azurecr.io"".

En los ejemplos siguientes se usan API asincrónicas que devuelven una tarea. También hay disponibles API sincrónicas.

Enumeración asincrónica de repositorios

Recorra en iteración la colección de repositorios del 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);
}

Establecimiento de propiedades de artefactos de forma asincrónica

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

Eliminación asincrónica de imágenes

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

Introducción

Código fuente | Paquete (Maven) | Referencia de API | Ejemplos

Entornos admitidos actualmente

Inclusión del paquete

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-containers-containerregistry</artifactId>
  <version>1.0.0-beta.3</version>
</dependency>

Autenticar el cliente

La biblioteca Azure Identity ofrece compatibilidad con Microsoft Entra ID para la autenticación.

En los ejemplos siguientes se asume que tiene una cadena de punto de conexión del registro que contiene el prefijo https:// y el nombre del servidor de inicio de sesión, por ejemplo, "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 obtener más información sobre el uso de Microsoft Entra ID con Azure Container Registry, consulte la información general de la autenticación.

Ejemplos

En cada ejemplo se asume que hay una cadena de punto de conexión del registro que contiene el prefijo https:// y el nombre del servidor de inicio de sesión, por ejemplo, "https://myregistry.azurecr.io"".

Enumeración de nombres de repositorio

Recorra en iteración la colección de repositorios del registro.

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

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

Establecimiento de propiedades de artefactos

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

Eliminación de imágenes

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

Introducción

Código fuente | Paquete (npm) | Referencia de API | Ejemplos

Entornos admitidos actualmente

Para más información, consulte la directiva de compatibilidad.

Instalar el paquete @azure/container-registry

Instale la biblioteca cliente de Container Registry para JavaScript con npm:

npm install @azure/container-registry

Autenticar el cliente

La biblioteca Azure Identity ofrece compatibilidad con Microsoft Entra ID para la autenticación.

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 obtener más información sobre el uso de Microsoft Entra ID con Azure Container Registry, consulte la información general de la autenticación.

Ejemplos

En cada ejemplo se asume que hay una variable de entorno CONTAINER_REGISTRY_ENDPOINT establecida en una cadena que contiene el prefijo https:// y el nombre del servidor de inicio de sesión, por ejemplo, "https://myregistry.azurecr.io"".

Enumeración asincrónica de repositorios

Recorra en iteración la colección de repositorios del 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);
});

Establecimiento de propiedades de artefactos de forma asincrónica

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

Eliminación asincrónica de imágenes

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

Introducción

Código fuente | Paquete (Pypi) | Referencia de API | Ejemplos

Instalar el paquete

Instale la biblioteca de Azure Container Registry para Python con pip:

pip install --pre azure-containerregistry

Autenticar el cliente

La biblioteca Azure Identity ofrece compatibilidad con Microsoft Entra ID para la autenticación. DefaultAzureCredential asume que están establecidas las variables de entorno AZURE_CLIENT_ID, AZURE_TENANT_ID y AZURE_CLIENT_SECRET. Para más información, consulte Variables de entorno de identidades de 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())

Ejemplos

En cada ejemplo se asume que hay una variable de entorno CONTAINERREGISTRY_ENDPOINT establecida en una cadena que contiene el prefijo https:// y el nombre del servidor de inicio de sesión, por ejemplo, "https://myregistry.azurecr.io"".

Enumeración asincrónica de etiquetas

En este ejemplo se asume que el registro tiene un repositorio 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")

Establecimiento de propiedades de artefactos de forma asincrónica

En este ejemplo se asume que el registro tiene un repositorio hello-world con la imagen v1 etiquetada.

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.

Eliminación asincrónica de imágenes

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]

Introducción

Código fuente | Paquete (pkg.go.dev) | Referencia de la API de REST

Instalar el paquete

Instale la biblioteca cliente de Azure Container Registry para Go con go get:

go get github.com/Azure/azure-sdk-for-go/sdk/containers/azcontainerregistry

Autenticar el cliente

Al desarrollar y depurar la aplicación localmente, puede usar azidentity.NewDefaultAzureCredential para autenticarse. Se recomienda usar una identidad administrada en un entorno de producción.

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 la documentación de azidentity para obtener más información sobre otros enfoques de autenticación.

Ejemplos

En cada ejemplo, se supone que la dirección URL del punto de conexión del registro de contenedor es "https://myregistry.azurecr.io".

Lista de etiquetas

En este ejemplo se asume que el registro tiene un repositorio 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)
		}
	}
}

Establecimiento de propiedades de artefactos

En este ejemplo se asume que el registro tiene un repositorio hello-world con la imagen latest etiquetada.

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

Eliminación de imágenes

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

Limpieza de recursos

Si quiere limpiar y quitar una instancia de Azure Container Registry, puede eliminar el recurso o grupo de recursos. Al eliminar el grupo de recursos, también se elimina cualquier otro recurso que esté asociado a él.

Pasos siguientes

En este inicio rápido, ha aprendido a usar la biblioteca cliente de Azure Container Registry para realizar operaciones en imágenes y artefactos en el registro de contenedor.

  • Para más información, vea la documentación de referencia de la API:

  • Más información acerca de la API REST de Azure Container Registry.