bibliothèque cliente Azure Container Registry pour Java - version 1.2.2

Article
10/21/2023

Azure Container Registry vous permet de stocker et de gérer des images conteneur et des artefacts dans un registre privé pour tous les types de déploiements de conteneurs.

Utilisez la bibliothèques de client pour Azure Container Registry afin de :

Lister des images ou des artefacts dans un registre.
Obtenir des métadonnées pour les images et les artefacts, les référentiels et les étiquettes
Définir les propriétés de lecture/écriture/suppression sur des éléments du registre.
Supprimer des images et des artefacts, des référentiels et des étiquettes

| Code source Package (Maven) | | Documentation produit Échantillons

Prise en main

Prérequis

Un Kit de développement Java (JDK), version 8 ou ultérieure.
Abonnement Azure
Création d’un registre de conteneurs

Inclure le package

Inclure le fichier de nomenclature

Incluez azure-sdk-bom dans votre projet pour dépendre de la version de disponibilité générale de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

puis incluez la dépendance directe dans la section dépendances sans la balise de version, comme indiqué ci-dessous.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-containers-containerregistry</artifactId>
  </dependency>
</dependencies>

Inclure une dépendance directe

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-containers-containerregistry</artifactId>
  <version>1.2.2</version>
</dependency>

Authentifier les clients

La bibliothèque Azure Identity fournit une prise en charge facile d’Azure Active Directory pour l’authentification. Notez que tous les exemples ci-dessous supposent que vous disposez d’un point de terminaison, qui est l’URL, y compris le nom du serveur de connexion et le https:// préfixe. Plus d’informations sur Azure Container Registry portail

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

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryAsyncClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .buildAsyncClient();

Pour plus d’informations sur l’utilisation d’AAD avec Azure Container Registry, consultez vue d’ensemble de l’authentification du service.

Authentification avec un jeton ARM AAD

Par défaut, le Kit de développement logiciel (SDK) Container Registry pour Java utilise des jetons d’accès ACR. Si vous souhaitez vous authentifier avec un jeton ARM AAD et que la stratégie correspondante est activée, veillez à définir l’audience lors de la création du client container Registry. Pour plus d’informations sur la configuration de la stratégie d’authentification ARM case activée, reportez-vous aux informations de référence sur l’interface CLI ACR.

ContainerRegistryAudience la valeur est spécifique au cloud :

ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(getEndpoint())
    .credential(credential)
    .audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_PUBLIC_CLOUD)
    .buildClient();

registryClient
    .listRepositoryNames()
    .forEach(name -> System.out.println(name));

Clouds nationaux

Pour vous authentifier auprès d’un registre dans un cloud national, vous devez effectuer les ajouts suivants à votre configuration client :

Définissez dans le générateur d’informations d’identification à la suite de la authorityHostdocumentation de la bibliothèque de client d’identité
Si l’authentification par jeton d’accès ACR est désactivée pour votre ressource de registrecontainer, vous devez configurer l’audience sur le générateur de client Container Registry.

ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(getEndpoint())
    .credential(credential)
    // only if ACR access tokens are disabled or not supported
    .audience(ContainerRegistryAudience.AZURE_RESOURCE_MANAGER_CHINA)
    .buildClient();

registryClient
    .listRepositoryNames()
    .forEach(name -> System.out.println(name));

Prise en charge de l’accès anonyme

Si le générateur est instancié sans informations d’identification, le Kit de développement logiciel (SDK) crée le client de service pour le mode d’extraction anonyme. L’utilisateur doit utiliser ce paramètre sur un registre qui a été activé pour l’extraction anonyme. Dans ce mode, l’utilisateur peut uniquement appeler la méthode listRepositoryNames et sa surcharge. Tous les autres appels échouent. Pour plus d’informations, consultez Accès par extraction anonyme

ContainerRegistryClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .buildClient();

ContainerRegistryAsyncClient registryClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .buildAsyncClient();

Concepts clés

Un registre stocke les images Docker et les artefacts OCI. Une image ou un artefact se compose d’un manifeste et de couches. Le manifeste d’une image décrit les couches qui composent l’image et est identifié de manière unique par son condensé. Une image peut également être « étiquetée » pour lui donner un alias lisible par l’homme. Une image ou un artefact peut avoir zéro ou plusieurs balises associées , et chaque balise identifie l’image de manière unique. Une collection d’images qui partagent le même nom, mais qui ont des balises différentes, est appelée dépôt.

Pour plus d’informations, consultez Concepts de Container Registry.

Exemples

Exemples de synchronisation

Opérations de Registre :
Opérations d’objet blob et de manifeste :

Opérations du registre

Cette section contient ContainerRegistryClient des exemples.

Lister les noms des référentiels

Itérez au sein de la collection de référentiels dans le registre.

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

Répertorier les balises d’artefact avec accès anonyme

RegistryArtifact image = anonymousClient.getArtifact(repositoryName, digest);

PagedIterable<ArtifactTagProperties> tags = image.listTagProperties();

System.out.printf(String.format("%s has the following aliases:", image.getFullyQualifiedReference()));

for (ArtifactTagProperties tag : tags) {
    System.out.printf(String.format("%s/%s:%s", anonymousClient.getEndpoint(), repositoryName, tag.getName()));
}

Définir les propriétés des artefacts

RegistryArtifact image = registryClient.getArtifact(repositoryName, digest);

image.updateTagProperties(
    tag,
    new ArtifactTagProperties()
        .setWriteEnabled(false)
        .setDeleteEnabled(false));

Supprimer des images

final int imagesCountToKeep = 3;
for (String repositoryName : registryClient.listRepositoryNames()) {
    final ContainerRepository repository = registryClient.getRepository(repositoryName);

    // Obtain the images ordered from newest to oldest
    PagedIterable<ArtifactManifestProperties> imageManifests =
        repository.listManifestProperties(
            ArtifactManifestOrder.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();
        });
}

Supprimer un dépôt avec des levées d’accès anonyme

final String endpoint = getEndpoint();
final String repositoryName = getRepositoryName();

ContainerRegistryClient anonymousClient = new ContainerRegistryClientBuilder()
    .endpoint(endpoint)
    .buildClient();

try {
    anonymousClient.deleteRepository(repositoryName);
    System.out.println("Unexpected Success: Delete is not allowed on anonymous access");
} catch (ClientAuthenticationException ex) {
    System.out.println("Expected exception: Delete is not allowed on anonymous access");
}

Opérations d’objet blob et de manifeste

Cette section contient des exemples qui ContainerRegistryContentClient montrent comment charger et télécharger des images.

Tout d’abord, nous devons créer un client d’objet blob.

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
ContainerRegistryContentClient contentClient = new ContainerRegistryContentClientBuilder()
    .endpoint(endpoint)
    .credential(credential)
    .repositoryName(repository)
    .buildClient();

Charger des images

Pour charger une image complète, nous devons charger des couches et une configuration individuelles. Après cela, nous pouvons charger un manifeste qui décrit une image ou un artefact et lui attribuer une balise.

BinaryData configContent = BinaryData.fromObject(Collections.singletonMap("hello", "world"));

UploadRegistryBlobResult configUploadResult = contentClient.uploadBlob(configContent);
System.out.printf("Uploaded config: digest - %s, size - %s\n", configUploadResult.getDigest(), configContent.getLength());

OciDescriptor configDescriptor = new OciDescriptor()
    .setMediaType("application/vnd.unknown.config.v1+json")
    .setDigest(configUploadResult.getDigest())
    .setSizeInBytes(configContent.getLength());

BinaryData layerContent = BinaryData.fromString("Hello Azure Container Registry");
UploadRegistryBlobResult layerUploadResult = contentClient.uploadBlob(layerContent);
System.out.printf("Uploaded layer: digest - %s, size - %s\n", layerUploadResult.getDigest(), layerContent.getLength());

OciImageManifest manifest = new OciImageManifest()
    .setConfiguration(configDescriptor)
    .setSchemaVersion(2)
    .setLayers(Collections.singletonList(
        new OciDescriptor()
            .setDigest(layerUploadResult.getDigest())
            .setSizeInBytes(layerContent.getLength())
            .setMediaType("application/octet-stream")));

SetManifestResult manifestResult = contentClient.setManifest(manifest, "latest");
System.out.printf("Uploaded manifest: digest - %s\n", manifestResult.getDigest());

Télécharger des images

Pour télécharger une image complète, nous devons télécharger son manifeste, puis télécharger les couches et la configuration individuelles.

GetManifestResult manifestResult = contentClient.getManifest("latest");

OciImageManifest manifest = manifestResult.getManifest().toObject(OciImageManifest.class);
System.out.printf("Got manifest:\n%s\n", PRETTY_PRINT.writeValueAsString(manifest));

String configFileName = manifest.getConfiguration().getDigest() + ".json";
contentClient.downloadStream(manifest.getConfiguration().getDigest(), createFileChannel(configFileName));
System.out.printf("Got config: %s\n", configFileName);

for (OciDescriptor layer : manifest.getLayers()) {
    contentClient.downloadStream(layer.getDigest(), createFileChannel(layer.getDigest()));
    System.out.printf("Got layer: %s\n", layer.getDigest());
}

Supprimer un objet blob

GetManifestResult manifestResult = contentClient.getManifest("latest");

OciImageManifest manifest = manifestResult.getManifest().toObject(OciImageManifest.class);
for (OciDescriptor layer : manifest.getLayers()) {
    contentClient.deleteBlob(layer.getDigest());
}

Supprimer le manifeste

GetManifestResult manifestResult = contentClient.getManifest("latest");
contentClient.deleteManifest(manifestResult.getDigest());

Dépannage

Consultez notre guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Étapes suivantes

Aller plus loin avec azure-containers-containerregistry et nos exemples
Regardez une vidéo de démonstration ou de plongée approfondie
En savoir plus sur le service Azure Container Registry

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions