Kopieren eines Blobs mit asynchroner Planung mithilfe von Go

  • Artikel

In diesem Artikel wird gezeigt, wie Sie ein Blob mit asynchroner Planung mithilfe des Azure Storage-Clientmoduls für Go kopieren. Sie können ein Blob aus einer Quelle innerhalb desselben Speicherkontos, aus einer Quelle in einem anderen Speicherkonto oder aus einem beliebigen zugänglichen Objekt kopieren, das über eine HTTP GET-Anforderung für eine bestimmte URL abgerufen wird. Sie können einen ausstehenden Kopiervorgang auch abbrechen.

Bei den in diesem Artikel behandelten Methoden wird der REST-API-Vorgang Copy Blob verwendet. Sie können verwendet werden, wenn Sie einen Kopiervorgang mit asynchroner Planung ausführen möchten. Informationen zu den meisten Kopierszenarien, in denen Sie Daten in ein Speicherkonto verschieben möchten und über eine URL für das Quellobjekt verfügen, finden Sie unter Kopieren eines Blobs über eine Quellobjekt-URL mit Go.

Voraussetzungen

Erstellen Ihrer Umgebung

Wenn Sie nicht über ein vorhandenes Projekt verfügen, wird in diesem Abschnitt gezeigt, wie Sie ein Projekt für die Arbeit mit dem Azure Blob Storage-Clientmodul für Go einrichten. Die Schritte umfassen die Modulinstallation, das Hinzufügen von import-Pfaden und das Erstellen eines autorisierten Clientobjekts. Ausführlichere Informationen finden Sie unter Erste Schritte mit Azure Blob Storage und Go.

Installieren von Modulen

Verwenden Sie den folgenden Befehl, um das Modul azblob zu installieren:

go get github.com/Azure/azure-sdk-for-go/sdk/storage/azblob

Um sich mit Microsoft Entra ID zu authentifizieren (empfohlen), installieren Sie das azidentity-Modul mit dem folgenden Befehl:

go get github.com/Azure/azure-sdk-for-go/sdk/azidentity

Hinzufügen von Importpfaden

Fügen Sie in der Codedatei die folgenden Importpfade hinzu:

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/storage/azblob"
)

Dies sind die Importpfade, die mindestens für die ersten Schritte erforderlich sind. Einige Codebeispiele in diesem Artikel erfordern möglicherweise zusätzliche Importpfade. Spezifische Details und eine Beispielverwendung finden Sie unter Codebeispiele.

Erstellen eines Clientobjekts

Um eine App mit Blob Storage zu verbinden, erstellen Sie ein Clientobjekt mithilfe von azblob.NewClient. Das folgende Beispiel zeigt, wie Sie ein Clientobjekt mithilfe von DefaultAzureCredential für die Autorisierung erstellen:

func getServiceClientTokenCredential(accountURL string) *azblob.Client {
    // Create a new service client with token credential
    credential, err := azidentity.NewDefaultAzureCredential(nil)
    handleError(err)

    client, err := azblob.NewClient(accountURL, credential, nil)
    handleError(err)

    return client
}

Autorisierung

Der Autorisierungsmechanismus muss über die benötigten Berechtigungen zum Ausführen eines Kopiervorgangs oder zum Abbrechen einer ausstehenden Kopie verfügen. Für die Autorisierung mit Microsoft Entra ID (empfohlen) benötigen Sie mindestens die integrierte Azure RBAC-Rolle Mitwirkender an Storage-Blobdaten. Weitere Informationen finden Sie im Autorisierungsleitfaden für Copy Blob oder Abort Copy Blob.

Informationen zum Kopieren von Blobs mit asynchroner Planung

Der Copy Blob-Vorgang kann asynchron abgeschlossen werden und wird auf Grundlage der besten Leistung ausgeführt, d. h., es wird nicht garantiert, dass der Vorgang sofort beginnt oder innerhalb eines bestimmten Zeitrahmens abgeschlossen wird. Der Kopiervorgang wird im Hintergrund geplant und ausgeführt, sobald der Server über verfügbare Ressourcen verfügt. Der Vorgang kann synchron abgeschlossen werden, wenn der Kopiervorgang innerhalb desselben Speicherkontos erfolgt.

Ein Vorgang vom Typ Copy Blob kann jede der folgenden Aktionen ausführen:

  • Kopieren Sie ein Quellblob in ein Zielblob mit einem anderen Namen. Das Zielblob kann ein vorhandenes Blob desselben Blobtyps (Blockblob, Anfügeblob oder Seitenblob) sein, oder es kann sich um ein neues Blob handeln, das durch den Kopiervorgang erstellt wurde.
  • Kopieren Sie ein Quellblob in ein Zielblob mit demselben Namen. Dadurch wird das Zielblob ersetzt. Diese Art von Kopiervorgang entfernt alle Blöcke ohne Commit und überschreibt die Metadaten des Zielblobs.
  • Kopieren Sie eine Quelldatei im Azure-Dateidienst in ein Zielblob. Das Zielblob kann ein vorhandenes Blockblob oder ein neues Blockblob sein, das durch den Kopiervorgang erstellt wurde. Das Kopieren von Dateien in Seitenblobs oder Anfügeblobs wird nicht unterstützt.
  • Kopieren Sie eine Momentaufnahme über das zugehörige Basis-Blob. Indem Sie eine Momentaufnahme zu einem Basis-Blob heraufstufen, können Sie eine frühere Version eines Blobs wiederherstellen.
  • Kopieren Sie eine Momentaufnahme in ein Zielblob mit einem anderen Namen. Das resultierende Zielblob ist ein beschreibbares Blob und keine Momentaufnahme.

Das Quellblob für einen Kopiervorgang kann von einem der folgenden Typen sein: Blockblob, Anfügeblob, Seitenblob, Blobmomentaufnahme oder Blobversion. Der Kopiervorgang kopiert immer das gesamte Quellblob oder die gesamte Datei. Das Kopieren eines Bytebereichs oder einer Gruppe von Blöcken wird nicht unterstützt.

Wenn das Zielblob bereits vorhanden ist, muss es denselben Blobtyp wie das Quellblob aufweisen, und das vorhandene Zielblob wird überschrieben. Das Zielblob kann beim Ausführen eines Kopiervorgangs nicht geändert werden, und für ein Zielblob kann es nur einen ausstehenden Kopiervorgang geben.

Weitere Informationen zum Copy Blob-Vorgang, einschließlich Informationen zu Eigenschaften, Indextags, Metadaten und Abrechnung, finden Sie unter Bemerkungen.

Kopieren eines Blobs mit asynchroner Planung

Dieser Abschnitt enthält eine Übersicht über die Methoden, die von dem Azure Storage-Clientmodul für Go bereitgestellt werden, um einen Kopiervorgang mit asynchroner Planung auszuführen.

Die folgenden Methoden umschließen den REST-API-Vorgang Copy Blob und starten einen asynchronen Kopiervorgang von Daten aus dem Quellblob:

Kopieren eines Blobs aus einer Quelle in Azure

Wenn Sie ein Blob innerhalb desselben Speicherkontos kopieren, kann der Vorgang synchron abgeschlossen werden. Der Zugriff auf den Quellblob kann über Microsoft Entra ID (empfohlen), Shared Access Signature (SAS) oder einen Kontoschlüssel autorisiert werden. Einen alternativen synchronen Kopiervorgang finden Sie unter Kopieren eines Blob aus einer Quellobjekt-URL mit Go.

Wenn die Kopierquelle ein Blob in einem anderen Speicherkonto ist, kann der Vorgang asynchron abgeschlossen werden. Der Quellblob muss entweder öffentlich oder über ein SAS-Token autorisiert sein. Das SAS-Token muss die Berechtigung zum Lesen (Read ('r')) enthalten. Weitere Informationen zu SAS-Token finden Sie unter Gewähren von eingeschränktem Zugriff auf Azure Storage-Ressourcen mithilfe von SAS (Shared Access Signature).

Das folgende Beispiel zeigt ein Szenario für das Kopieren eines Quellblob aus einem anderen Speicherkonto mit asynchroner Planung. In diesem Beispiel wird eine Quellblob-URL mit einem angehängten SAS-Token für die Benutzerdelegierung erstellt. Im Beispiel wird davon ausgegangen, dass Sie Ihre eigene SAS bereitstellen. Das Beispiel zeigt auch, wie der Quellblob während des Kopiervorgangs geleast werden kann, um Änderungen am Blob durch einen anderen Client zu verhindern. Der Copy Blob-Vorgang speichert den ETag-Wert des Quellblobs, wenn der Kopiervorgang gestartet wird. Wenn der ETag-Wert geändert wird, bevor der Kopiervorgang abgeschlossen ist, ist der Vorgang nicht erfolgreich. Außerdem legen wir die Zugriffsebene für das Ziel-BLOB mithilfe der Struktur StartCopyFromURLOptions auf Cool fest.

func copyFromSourceAsync(srcBlob *blockblob.Client, destBlob *blockblob.Client) {
    // Lease the source blob during copy to prevent other clients from modifying it
    blobLeaseClient, err := lease.NewBlobClient(srcBlob, nil)
    handleError(err)

    _, err = blobLeaseClient.AcquireLease(context.TODO(), int32(60), nil)
    handleError(err)

    // Retrieve the SAS token for the source blob and append it to the URL
    sas := "<sas-token>"
    url := srcBlob.URL() + "?" + sas

    // Set copy options
    copyOptions := blob.StartCopyFromURLOptions{
        Tier: to.Ptr(blob.AccessTierCool),
    }

    // Copy the blob from the source URL to the destination blob
    startCopy, err := destBlob.StartCopyFromURL(context.TODO(), url, &copyOptions)
    handleError(err)

    // If startCopy.CopyStatus returns a status of "pending", the operation has started asynchronously
    // You can optionally add logic to poll the copy status and wait for the operation to complete
    // Example:
    copyStatus := *startCopy.CopyStatus
    for copyStatus == blob.CopyStatusTypePending {
        time.Sleep(time.Second * 2)

        properties, err := destBlob.GetProperties(context.TODO(), nil)
        handleError(err)

        copyStatus = *properties.CopyStatus
    }

    // Release the lease on the source blob
    _, err = blobLeaseClient.ReleaseLease(context.TODO(), nil)
    handleError(err)
}

Das folgende Beispiel zeigt die Beispielsyntax:

// TODO: replace <storage-account-name> placeholders with actual storage account names
srcURL := "https://<src-storage-account-name>.blob.core.windows.net/"
destURL := "https://<dest-storage-account-name>.blob.core.windows.net/"

credential, err := azidentity.NewDefaultAzureCredential(nil)
handleError(err)

srcClient, err := azblob.NewClient(srcURL, credential, nil)
handleError(err)
destClient, err := azblob.NewClient(destURL, credential, nil)
handleError(err)

srcBlob := srcClient.ServiceClient().NewContainerClient("source-container").NewBlockBlobClient("source-blob")
destBlob := destClient.ServiceClient().NewContainerClient("destination-container").NewBlockBlobClient("destination-blob-1")

copyFromSourceAsync(srcBlob, destBlob)

Hinweis

SAS-Token für die Benutzerdelegierung bieten mehr Sicherheit, da sie mit Microsoft Entra-Anmeldeinformationen anstelle eines Kontoschlüssels signiert sind. Um ein SAS-Token für die Benutzerdelegierung zu erstellen, benötigt der Microsoft Entra-Sicherheitsprinzipal entsprechende Berechtigungen. Informationen zu den Berechtigungsanforderungen finden Sie unter Benutzerdelegierungsschlüssel abrufen.

Kopieren eines Blobs aus einer Quelle außerhalb von Azure

Sie können einen Kopiervorgang für jedes Quellobjekt ausführen, das über eine HTTP GET-Anforderung für eine bestimmte URL abgerufen werden kann, einschließlich zugänglicher Objekte außerhalb von Azure. Im folgenden Beispiel wird ein Szenario zum Kopieren eines Blobs über eine URL für zugängliche Quellobjekte gezeigt:

func copyFromExternalSourceAsync(srcURL string, destBlob *blockblob.Client) {
    // Set copy options
    copyOptions := blob.StartCopyFromURLOptions{
        Tier: to.Ptr(blob.AccessTierCool),
    }

    // Copy the blob from the source URL to the destination blob
    startCopy, err := destBlob.StartCopyFromURL(context.TODO(), srcURL, &copyOptions)
    handleError(err)

    // If startCopy.CopyStatus returns a status of "pending", the operation has started asynchronously
    // You can optionally add logic to poll the copy status and wait for the operation to complete
    // Example:
    copyStatus := *startCopy.CopyStatus
    for copyStatus == blob.CopyStatusTypePending {
        time.Sleep(time.Second * 2)

        properties, err := destBlob.GetProperties(context.TODO(), nil)
        handleError(err)

        copyStatus = *properties.CopyStatus
    }
}

Das folgende Beispiel zeigt die Beispielsyntax:

externalURL := "<source-url>"

destBlob = destClient.ServiceClient().NewContainerClient("destination-container").NewBlockBlobClient("destination-blob-2")

copyFromExternalSourceAsync(externalURL, destBlob)

Überprüfen des Status eines Kopiervorgangs

Um den Status eines asynchronen Copy Blob-Vorgangs zu überprüfen, können Sie die GetProperties-Methode abfragen und den Status des Kopiervorgangs überprüfen.

Das folgende Codebeispiel zeigt, wie der Status eines Kopiervorgangs überprüft wird:

func checkCopyStatus(destBlob *blockblob.Client) {
    // Retrieve the properties from the destination blob
    properties, err := destBlob.GetProperties(context.TODO(), nil)
    handleError(err)

    copyID := *properties.CopyID
    copyStatus := *properties.CopyStatus

    fmt.Printf("Copy operation %s is %s\n", copyID, copyStatus)
}

Abbrechen eines Kopiervorgangs

Ein Abbrechen eines ausstehenden Copy Blob-Vorgangs führt zu einem Zielblob der Länge null. Die Metadaten für das Zielblob weisen jedoch die neuen Werte auf, die aus dem Quellblob kopiert oder explizit während des Kopiervorgangs festgelegt wurden. Zur Beibehaltung der ursprünglichen, vor dem Kopiervorgang vorliegenden Metadaten erstellen Sie eine Momentaufnahme des Zielblobs, bevor Sie eine der Kopiermethoden aufrufen.

Rufen Sie zum Abbrechen eines ausstehenden Kopiervorgangs den folgenden Vorgang auf:

Diese Methode umschließt den REST-API-Vorgang Abort Copy Blob, wodurch ein ausstehender Copy Blob-Vorgang abgebrochen wird. Das folgende Codebeispiel zeigt, wie ein ausstehender Copy Blob-Vorgang abgebrochen wird:

func abortCopy(destBlob *blockblob.Client) {
    // Retrieve the copy ID from the destination blob
    properties, err := destBlob.GetProperties(context.TODO(), nil)
    handleError(err)

    copyID := *properties.CopyID
    copyStatus := *properties.CopyStatus

    // Abort the copy operation if it's still pending
    if copyStatus == blob.CopyStatusTypePending {
        _, err := destBlob.AbortCopyFromURL(context.TODO(), copyID, nil)
        handleError(err)

        fmt.Printf("Copy operation %s aborted\n", copyID)
    }
}

Ressourcen

Weitere Informationen zum Kopieren von Blobs mit asynchroner Planung mithilfe des Azure Blob Storage-Clientmoduls für Go finden Sie in den folgenden Ressourcen.

Codebeispiele

REST-API-Vorgänge

Das Azure SDK für Go enthält Bibliotheken, die auf der Azure-REST-API basieren, und ermöglicht Ihnen dadurch die Interaktion mit REST-API-Vorgängen über vertraute Go-Paradigmen. Die in diesem Artikel behandelten Methoden verwenden die folgenden REST-API-Vorgänge:

Clientmodulressourcen

Zugehöriger Inhalt

  • Dieser Artikel ist Teil des Blob Storage-Entwicklerleitfadens für Go. Weitere Informationen finden Sie in der vollständigen Liste der Entwicklerleitfadenartikel unter Erstellen Ihrer Go-App.