Azure Container Registry Clientbibliothek für Java– Version 1.2.2

Artikel
10/21/2023

Azure Container Registry ermöglicht Ihnen das Speichern und Verwalten von Containerimages und Artefakten in einer privaten Registrierung für alle Arten von Containerbereitstellungen.

Verwenden Sie die Clientbibliothek für Azure Container Registry für Folgendes:

Auflisten von Images oder Artefakten in einer Registrierung
Abrufen von Metadaten für Bilder und Artefakte, Repositorys und Tags
Festlegen von Lese-/Schreib-/Löscheigenschaften für Registrierungselemente
Löschen von Bildern und Artefakten, Repositorys und Tags

Quellcode | Paket (Maven) | Produktdokumentation | Proben

Erste Schritte

Voraussetzungen

Java Development Kit (JDK), Version 8 oder höher.
Azure-Abonnement
Erstellen von Containerregistrierungen

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie azure-sdk-bom in Ihr Projekt ein, um von der Allgemeinverfügbarkeitsversion der Bibliothek abhängig zu sein. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur BOM finden Sie in der INFODATEI FÜR AZURE SDK-STÜCKLISTEN.

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

und fügen Sie dann die direkte Abhängigkeit wie unten dargestellt ohne das Versionstag in den Abschnitt abhängigkeiten ein.

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

Direkte Abhängigkeiten einfügen

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

Authentifizieren von Clients

Die Azure Identity-Bibliothek bietet einfache Azure Active Directory-Unterstützung für die Authentifizierung. Beachten Sie alle folgenden Beispiele, dass Sie über einen Endpunkt verfügen, bei dem es sich um die URL mit dem Namen des Anmeldeservers und dem https:// Präfix handelt. Weitere Informationen unter Azure Container Registry Portal

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

Weitere Informationen zur Verwendung von AAD mit Azure Container Registry finden Sie in der Authentifizierungsübersicht des Diensts.

Authentifizieren mit ARM-AAD-Token

Standardmäßig verwendet das Container Registry SDK für Java ACR-Zugriffstoken. Wenn Sie sich mit DEM ARM-AAD-Token authentifizieren möchten und die entsprechende Richtlinie aktiviert ist, müssen Sie beim Erstellen des Containerregistrierungsclients die Zielgruppe festlegen. Informationen zum Überprüfen der KONFIGURATION der ARM-Authentifizierungsrichtlinie finden Sie in der ACR CLI-Referenz .

ContainerRegistryAudience value ist spezifisch für die 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));

Nationale Clouds

Um sich bei einer Registrierung in einer nationalen Cloud zu authentifizieren, müssen Sie die folgenden Ergänzungen zu Ihrer Clientkonfiguration vornehmen:

Legen Sie im Anmeldeinformations-Generator nach der authorityHostDokumentation zur Identitätsclientbibliothek fest.
Wenn die ACR-Zugriffstokenauthentifizierung für Ihre Containerregistrierungsressource deaktiviert ist, müssen Sie die Zielgruppe im Container Registry-Client-Generator konfigurieren.

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

Unterstützung für anonymen Zugriff

Wenn der Generator ohne Anmeldeinformationen instanziiert wird, erstellt das SDK den Dienstclient für den anonymen Pullmodus. Der Benutzer muss diese Einstellung für eine Registrierung verwenden, die für anonymes Pullen aktiviert wurde. In diesem Modus kann der Benutzer nur die listRepositoryNames-Methode und die zugehörige Überladung aufrufen. Alle anderen Aufrufe schlagen fehl. Weitere Informationen finden Sie unter Anonymer Pullzugriff.

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

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

Wichtige Begriffe

Eine Registrierung speichert Docker-Images und OCI-Artefakte. Ein Image oder Artefakt besteht aus einem Manifest und Ebenen. Das Manifest eines Bilds beschreibt die Ebenen, aus denen das Bild besteht, und wird durch den Digest eindeutig identifiziert. Ein Bild kann auch "markiert" werden, um ihm einen lesbaren Alias zu geben. Einem Bild oder Artefakt können null oder mehr Tags zugeordnet sein, und jedes Tag identifiziert das Bild eindeutig. Eine Sammlung von Bildern, die denselben Namen haben, aber unterschiedliche Tags aufweisen, wird als Repository bezeichnet.

Weitere Informationen finden Sie unter Container Registry-Konzepte.

Beispiele

Registrierungsvorgänge

Dieser Abschnitt enthält ContainerRegistryClient Beispiele.

Auflisten der Repositorynamen

Durchlaufen Sie die Sammlung von Repositorys in der Registrierung:

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

Auflisten von Artefakttags mit anonymem Zugriff

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

Festlegen von Artefakteigenschaften

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

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

Löschen von Bildern

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

Löschen eines Repositorys mit anonymen Zugriffsschürfen

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

Blob- und Manifestvorgänge

Dieser Abschnitt enthält Beispiele für ContainerRegistryContentClient das Hochladen und Herunterladen von Bildern.

Zunächst müssen wir einen Blobclient erstellen.

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

Hochladen von Bildern

Um ein vollständiges Bild hochzuladen, müssen wir einzelne Ebenen und die Konfiguration hochladen. Danach können wir ein Manifest hochladen, das ein Bild oder Artefakt beschreibt, und ihm ein Tag zuweisen.

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

Herunterladen von Bildern

Zum Herunterladen eines vollständigen Images müssen wir das Manifest herunterladen und dann einzelne Ebenen und die Konfiguration herunterladen.

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

Löschen eines Blobs

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

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

Manifest löschen

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

Problembehandlung

Weitere Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung .

Nächste Schritte

Gehen Sie mit azure-containers-containerregistry und unseren Beispielen weiter.
Sehen Sie sich eine Demo oder ein ausführliches Video an
Weitere Informationen zum Azure Container Registry-Dienst

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe

Freigeben über