Azure Container Registry Clientbibliothek für Python – Version 1.2.0

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 (Pypi) | Paket (Conda) | API-Referenzdokumentation | DOKUMENTATION | ZUR REST-APIProduktdokumentation

Haftungsausschluss

Die Unterstützung von Python-Paketen für Das Azure SDK für Python 2.7 wurde am 01. Januar 2022 eingestellt. Weitere Informationen und Fragen finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 oder höher ist erforderlich, um dieses Paket zu verwenden. Weitere Informationen finden Sie unter Supportrichtlinie für Azure SDK für Python-Versionen.

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Container Registry-Clientbibliothek für Python mit pip:

pip install --pre azure-containerregistry

Voraussetzungen

• Für die Verwendung dieses Pakets ist Python 3.7 oder höher erforderlich.
• Sie benötigen ein Azure-Abonnement und ein Container Registry-Konto , um dieses Paket verwenden zu können.

Um eine neue Container Registry zu erstellen, können Sie das Azure-Portal, Azure PowerShell oder die Azure CLI verwenden. Beispiel für die Verwendung der Azure-Befehlszeilenschnittstelle:

az acr create --name MyContainerRegistry --resource-group MyResourceGroup --location westus --sku Basic

Authentifizieren des Clients

Die Azure Identity-Bibliothek bietet einfache Azure Active Directory-Unterstützung für die Authentifizierung. Geht DefaultAzureCredential davon aus, dass die AZURE_CLIENT_IDUmgebungsvariablen , AZURE_TENANT_IDund AZURE_CLIENT_SECRET festgelegt sind. Weitere Informationen finden Sie im Abschnitt Azure Identity-Umgebungsvariablen.

# Create a ContainerRegistryClient that will authenticate through Active Directory
from azure.containerregistry import ContainerRegistryClient
from azure.identity import DefaultAzureCredential

endpoint = "https://mycontainerregistry.azurecr.io"
audience = "https://management.azure.com"
client = ContainerRegistryClient(endpoint, DefaultAzureCredential(), audience=audience)

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 "getaggt" werden, um ihm einen lesbaren Alias zu verleihen. 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 Konzepte der Containerregistrierung.

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der häufigsten ACR-Dienstaufgaben behandeln, einschließlich:

• Registrierungsvorgänge:
  • Auflisten von Repositorys
  • Listentags mit anonymem Zugriff
  • Festlegen von Artefakteigenschaften
  • Löschen von Images
• Blob- und Manifestvorgänge:
  • Hochladen von Bildern
  • Bilder herunterladen
  • Manifest löschen
  • Löschen eines Blobs

Beachten Sie, dass jedes Beispiel davon ausgeht, dass eine CONTAINERREGISTRY_ENDPOINT Umgebungsvariable auf eine Zeichenfolge festgelegt ist, die das https:// Präfix und den Namen des Anmeldeservers enthält, z. B. "https://myregistry.azurecr.io"". Beispiele für anonymen Zugriff erhalten Endpunktwerte aus der UmgebungsvariableCONTAINERREGISTRY_ANONREGISTRY_ENDPOINT.

Auflisten von Repositorys

Durchlaufen Sie die Sammlung von Repositorys in der Registrierung:

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    # Iterate through all the repositories
    for repository_name in client.list_repository_names():
        print(repository_name)

Listentags mit anonymem Zugriff

Durchlaufen Sie die Sammlung von Tags im Repository mit anonymem Zugriff.

with ContainerRegistryClient(endpoint) as anon_client:
    manifest = anon_client.get_manifest_properties("library/hello-world", "latest")
    print(f"Tags of {manifest.repository_name}: ")
    # Iterate through all the tags
    for tag in manifest.tags:
        print(tag)

Festlegen von Artefakteigenschaften

Legen Sie die Eigenschaften eines Artefakts fest.

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    # Set permissions on image "library/hello-world:v1"
    client.update_manifest_properties(
        "library/hello-world",
        "v1",
        can_write=False,
        can_delete=False
    )

Löschen von Images

Löschen Sie Bilder, die älter als die ersten drei im Repository sind.

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    for repository in client.list_repository_names():
        # Keep the three most recent images, delete everything else
        manifest_count = 0
        for manifest in client.list_manifest_properties(
            repository, order_by=ArtifactManifestOrder.LAST_UPDATED_ON_DESCENDING
        ):
            manifest_count += 1
            if manifest_count > 3:
                # Make sure will have the permission to delete the manifest later
                client.update_manifest_properties(
                    repository,
                    manifest.digest,
                    can_write=True,
                    can_delete=True
                )
                print(f"Deleting {repository}:{manifest.digest}")
                client.delete_manifest(repository, manifest.digest)

Hochladen von Bildern

Zum Hochladen eines vollständigen Bilds müssen einzelne Ebenen und Konfigurationen hochgeladen werden. Danach können wir ein Manifest hochladen, das ein Bild oder Artefakt beschreibt, und ihm ein Tag zuweisen.

self.repository_name = "sample-oci-image"
layer = BytesIO(b"Sample layer")
config = BytesIO(json.dumps(
    {
        "sample config": "content",
    }).encode())
with ContainerRegistryClient(self.endpoint, self.credential) as client:
    # Upload a layer
    layer_digest, layer_size = client.upload_blob(self.repository_name, layer)
    print(f"Uploaded layer: digest - {layer_digest}, size - {layer_size}")
    # Upload a config
    config_digest, config_size = client.upload_blob(self.repository_name, config)
    print(f"Uploaded config: digest - {config_digest}, size - {config_size}")
    # Create an oci image with config and layer info
    oci_manifest = {
        "config": {
            "mediaType": "application/vnd.oci.image.config.v1+json",
            "digest": config_digest,
            "sizeInBytes": config_size,
        },
        "schemaVersion": 2,
        "layers": [
            {
                "mediaType": "application/vnd.oci.image.layer.v1.tar",
                "digest": layer_digest,
                "size": layer_size,
                "annotations": {
                    "org.opencontainers.image.ref.name": "artifact.txt",
                },
            },
        ],
    }
    # Set the image with tag "latest"
    manifest_digest = client.set_manifest(self.repository_name, oci_manifest, tag="latest")
    print(f"Uploaded manifest: digest - {manifest_digest}")

Bilder herunterladen

Um ein vollständiges Image herunterzuladen, müssen wir das Manifest herunterladen und dann einzelne Ebenen und die Konfiguration herunterladen.

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    # Get the image
    get_manifest_result = client.get_manifest(self.repository_name, "latest")
    received_manifest = get_manifest_result.manifest
    print(f"Got manifest:\n{received_manifest}")
    
    # Download and write out the layers
    for layer in received_manifest["layers"]:
        # Remove the "sha256:" prefix from digest
        layer_file_name = layer["digest"].split(":")[1]
        try:
            stream = client.download_blob(self.repository_name, layer["digest"])
            with open(layer_file_name, "wb") as layer_file:
                for chunk in stream:
                    layer_file.write(chunk)
        except DigestValidationError:
            print(f"Downloaded layer digest value did not match. Deleting file {layer_file_name}.")
            os.remove(layer_file_name)
        print(f"Got layer: {layer_file_name}")
    # Download and write out the config
    config_file_name = "config.json"
    try:
        stream = client.download_blob(self.repository_name, received_manifest["config"]["digest"])
        with open(config_file_name, "wb") as config_file:
            for chunk in stream:
                config_file.write(chunk)
    except DigestValidationError:
        print(f"Downloaded config digest value did not match. Deleting file {config_file_name}.")
        os.remove(config_file_name)
    print(f"Got config: {config_file_name}")

Manifest löschen

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    get_manifest_result = client.get_manifest(self.repository_name, "latest")
    # Delete the image
    client.delete_manifest(self.repository_name, get_manifest_result.digest)

Löschen eines Blobs

with ContainerRegistryClient(self.endpoint, self.credential) as client:
    get_manifest_result = client.get_manifest(self.repository_name, "latest")
    received_manifest = get_manifest_result.manifest
    # Delete the layers
    for layer in received_manifest["layers"]:
        client.delete_blob(self.repository_name, layer["digest"])
    # Delete the config
    client.delete_blob(self.repository_name, received_manifest["config"]["digest"])

Problembehandlung

Informationen zur Problembehandlung finden Sie im Leitfaden zur Problembehandlung.

Allgemein

Die ACR-Clientbibliothek löst in Azure Core definierte Ausnahmen aus.

Protokollierung

Diese Bibliothek verwendet die Standardprotokollierungsbibliothek für die Protokollierung.

Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf Ebene INFO protokolliert.

Die detaillierte DEBUG Protokollierung auf Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf dem Client oder pro Vorgang mit dem logging_enable argument Schlüsselwort (keyword) aktiviert werden.

Sehen Sie sich die vollständige SDK-Protokollierungsdokumentation mit Beispielen hier an.

Optionale Konfiguration

Optionale Schlüsselwort (keyword) Argumente können auf Client- und Vorgangsebene übergeben werden. Die azure-core-Referenzdokumentation beschreibt verfügbare Konfigurationen für Wiederholungen, Protokollierung, Transportprotokolle und vieles mehr.

Nächste Schritte

• Gehen Sie mit azure.containerregistry und unseren Beispielen weiter.
• Sehen Sie sich eine Demo oder ein ausführliches Tauchvideo an.
• Erfahren Sie mehr über den 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.