Udostępnij za pośrednictwem

Kopiowanie obiektu blob z planowaniem asynchronicznym przy użyciu platformy .NET

  • Artykuł

W tym artykule pokazano, jak skopiować obiekt blob z planowaniem asynchronicznym przy użyciu biblioteki klienta usługi Azure Storage dla platformy .NET. Obiekt blob można skopiować ze źródła na tym samym koncie magazynu, ze źródła na innym koncie magazynu lub z dowolnego dostępnego obiektu pobranego za pośrednictwem żądania HTTP GET dla danego adresu URL. Możesz również przerwać oczekującą operację kopiowania.

Metody biblioteki klienta omówione w tym artykule korzystają z operacji kopiowania interfejsu API REST obiektów blob i mogą być używane, gdy chcesz wykonać kopię za pomocą planowania asynchronicznego. W przypadku większości scenariuszy kopiowania, w których chcesz przenieść dane na konto magazynu i mieć adres URL obiektu źródłowego, zobacz Kopiowanie obiektu blob z adresu URL obiektu źródłowego przy użyciu platformy .NET.

Wymagania wstępne

Konfigurowanie środowiska

Jeśli nie masz istniejącego projektu, w tej sekcji pokazano, jak skonfigurować projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla platformy .NET. Kroki obejmują instalację pakietu, dodawanie using dyrektyw i tworzenie autoryzowanego obiektu klienta. Aby uzyskać szczegółowe informacje, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i .NET.

Instalowanie pakietów

Z katalogu projektu zainstaluj pakiety dla bibliotek klienta usługi Azure Blob Storage i tożsamości platformy Azure przy użyciu dotnet add package polecenia . Pakiet Azure.Identity jest wymagany w przypadku połączeń bez hasła z usługami platformy Azure.

dotnet add package Azure.Storage.Blobs
dotnet add package Azure.Identity

Dodawanie using dyrektyw

Dodaj te using dyrektywy na początku pliku kodu:

using Azure.Identity;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Blobs.Specialized;

Niektóre przykłady kodu w tym artykule mogą wymagać dodatkowych using dyrektyw.

Tworzenie obiektu klienta

Aby połączyć aplikację z usługą Blob Storage, utwórz wystąpienie klasy BlobServiceClient. W poniższym przykładzie pokazano, jak utworzyć obiekt klienta przy użyciu DefaultAzureCredential autoryzacji:

public BlobServiceClient GetBlobServiceClient(string accountName)
{
    BlobServiceClient client = new(
        new Uri($"https://{accountName}.blob.core.windows.net"),
        new DefaultAzureCredential());

    return client;
}

Możesz zarejestrować klienta usługi na potrzeby wstrzykiwania zależności w aplikacji .NET.

Można również tworzyć obiekty klienta dla określonych kontenerów lub obiektów blob. Aby dowiedzieć się więcej na temat tworzenia obiektów klienta i zarządzania nimi, zobacz Tworzenie obiektów klienta korzystających z zasobów danych i zarządzanie nimi.

Autoryzacja

Mechanizm autoryzacji musi mieć uprawnienia niezbędne do wykonania operacji kopiowania lub przerwania oczekującej kopii. W przypadku autoryzacji przy użyciu identyfikatora Entra firmy Microsoft (zalecane) najmniej uprzywilejowana rola wbudowana RBAC platformy Azure różni się w zależności od kilku czynników. Aby dowiedzieć się więcej, zobacz wskazówki autoryzacji dotyczące kopiowania obiektów blob (interfejs API REST) lub Abort Copy Blob (INTERFEJS API REST) .

Informacje o kopiowaniu obiektów blob za pomocą planowania asynchronicznego

Operacja Copy Blob może zakończyć się asynchronicznie i jest wykonywana na podstawie najlepszego nakładu pracy, co oznacza, że operacja nie gwarantuje natychmiastowego uruchomienia ani ukończenia w określonym przedziale czasu. Operacja kopiowania jest zaplanowana w tle i wykonywana jako serwer ma dostępne zasoby. Operacja może zakończyć się synchronicznie, jeśli kopia występuje na tym samym koncie magazynu.

Operacja Copy Blob może wykonać dowolną z następujących akcji:

  • Skopiuj źródłowy obiekt blob do docelowego obiektu blob o innej nazwie. Docelowy obiekt blob może być istniejącym obiektem blob tego samego typu obiektu blob (blok, dołączanie lub strona) albo może być nowym obiektem blob utworzonym przez operację kopiowania.
  • Skopiuj źródłowy obiekt blob do docelowego obiektu blob o takiej samej nazwie, który zastępuje docelowy obiekt blob. Ten typ operacji kopiowania usuwa wszystkie niezatwierdzone bloki i zastępuje metadane docelowego obiektu blob.
  • Skopiuj plik źródłowy w usłudze Azure File do docelowego obiektu blob. Docelowy obiekt blob może być istniejącym blokowym obiektem blob lub może być nowym blokowym obiektem blob utworzonym przez operację kopiowania. Kopiowanie z plików do stronicowych obiektów blob lub uzupełnialnych obiektów blob nie jest obsługiwane.
  • Skopiuj migawkę na podstawowy obiekt blob. Promując migawkę do pozycji podstawowego obiektu blob, można przywrócić starszą wersję obiektu blob.
  • Skopiuj migawkę do docelowego obiektu blob o innej nazwie. Wynikowy docelowy obiekt blob jest zapisywalnym obiektem blob, a nie migawką.

Aby dowiedzieć się więcej o Copy Blob operacji, w tym o właściwościach, tagach indeksu, metadanych i rozliczeniach, zobacz Kopiowanie uwag dotyczących obiektu blob.

Kopiowanie obiektu blob za pomocą planowania asynchronicznego

Ta sekcja zawiera omówienie metod udostępnianych przez bibliotekę klienta usługi Azure Storage dla platformy .NET w celu wykonania operacji kopiowania przy użyciu planowania asynchronicznego.

Następujące metody opakowuje operację interfejsu API REST kopiowania obiektów blob i rozpoczynają asynchroniczną kopię danych ze źródłowego obiektu blob:

Metody StartCopyFromUri i StartCopyFromUriAsync zwracają obiekt CopyFromUriOperation zawierający informacje o operacji kopiowania. Te metody są używane w przypadku planowania asynchronicznego dla operacji kopiowania.

Kopiowanie obiektu blob ze źródła na platformie Azure

Jeśli kopiujesz obiekt blob na tym samym koncie magazynu, operacja może zakończyć się synchronicznie. Dostęp do źródłowego obiektu blob można autoryzować za pośrednictwem identyfikatora Firmy Microsoft, sygnatury dostępu współdzielonego (SAS) lub klucza konta. Aby uzyskać informacje na temat operacji kopiowania synchronicznego, zobacz Kopiowanie obiektu blob z adresu URL obiektu źródłowego za pomocą platformy .NET.

Jeśli źródło kopiowania jest obiektem blob na innym koncie magazynu, operacja może zakończyć się asynchronicznie. Źródłowy obiekt blob musi być publiczny lub autoryzowany za pośrednictwem tokenu SAS. Token SAS musi zawierać uprawnienie Odczyt ('r'). Aby dowiedzieć się więcej na temat tokenów SAS, zobacz Delegowanie dostępu za pomocą sygnatur dostępu współdzielonego.

Poniższy przykład przedstawia scenariusz kopiowania źródłowego obiektu blob z innego konta magazynu z asynchronicznym planowaniem. W tym przykładzie utworzymy źródłowy adres URL obiektu blob z dołączonym tokenem SAS delegowania użytkownika. W przykładzie pokazano, jak wygenerować token SAS przy użyciu biblioteki klienta, ale możesz również podać własne. W przykładzie pokazano również, jak dzierżawić źródłowy obiekt blob podczas operacji kopiowania, aby zapobiec zmianom obiektu blob z innego klienta. Operacja Copy Blob zapisuje ETag wartość źródłowego obiektu blob po uruchomieniu operacji kopiowania. Jeśli wartość zostanie zmieniona ETag przed zakończeniem operacji kopiowania, operacja zakończy się niepowodzeniem.

//-------------------------------------------------
// Copy a blob from a different storage account
//-------------------------------------------------
public static async Task CopyAcrossStorageAccountsAsync(
    BlobClient sourceBlob,
    BlockBlobClient destinationBlob)
{
    // Lease the source blob to prevent changes during the copy operation
    BlobLeaseClient sourceBlobLease = new(sourceBlob);

    // Create a Uri object with a SAS token appended - specify Read (r) permissions
    Uri sourceBlobSASURI = await GenerateUserDelegationSAS(sourceBlob);

    try
    {
        await sourceBlobLease.AcquireAsync(BlobLeaseClient.InfiniteLeaseDuration);

        // Start the copy operation and wait for it to complete
        CopyFromUriOperation copyOperation = await destinationBlob.StartCopyFromUriAsync(sourceBlobSASURI);
        await copyOperation.WaitForCompletionAsync();
    }
    catch (RequestFailedException ex)
    {
        // Handle the exception
    }
    finally
    {
        // Release the lease once the copy operation completes
        await sourceBlobLease.ReleaseAsync();
    }
}

async static Task<Uri> GenerateUserDelegationSAS(BlobClient sourceBlob)
{
    BlobServiceClient blobServiceClient =
        sourceBlob.GetParentBlobContainerClient().GetParentBlobServiceClient();

    // Get a user delegation key for the Blob service that's valid for 1 day
    UserDelegationKey userDelegationKey =
        await blobServiceClient.GetUserDelegationKeyAsync(DateTimeOffset.UtcNow,
                                                          DateTimeOffset.UtcNow.AddDays(1));

    // Create a SAS token that's also valid for 1 day
    BlobSasBuilder sasBuilder = new BlobSasBuilder()
    {
        BlobContainerName = sourceBlob.BlobContainerName,
        BlobName = sourceBlob.Name,
        Resource = "b",
        StartsOn = DateTimeOffset.UtcNow,
        ExpiresOn = DateTimeOffset.UtcNow.AddDays(1)
    };

    // Specify read permissions for the SAS
    sasBuilder.SetPermissions(BlobSasPermissions.Read);

    // Add the SAS token to the blob URI
    BlobUriBuilder blobUriBuilder = new BlobUriBuilder(sourceBlob.Uri)
    {
        // Specify the user delegation key
        Sas = sasBuilder.ToSasQueryParameters(userDelegationKey,
                                              blobServiceClient.AccountName)
    };

    return blobUriBuilder.ToUri();
}

Uwaga

Tokeny SAS delegowania użytkownika zapewniają większe bezpieczeństwo, ponieważ są podpisane przy użyciu poświadczeń firmy Microsoft Entra zamiast klucza konta. Aby utworzyć token SAS delegowania użytkownika, podmiot zabezpieczeń firmy Microsoft entra potrzebuje odpowiednich uprawnień. Aby uzyskać wymagania dotyczące autoryzacji, zobacz Pobieranie klucza delegowania użytkownika.

Kopiowanie obiektu blob ze źródła spoza platformy Azure

Operację kopiowania można wykonać na dowolnym obiekcie źródłowym, który można pobrać za pośrednictwem żądania HTTP GET dla danego adresu URL, w tym obiektów dostępnych poza platformą Azure. Poniższy przykład przedstawia scenariusz kopiowania obiektu blob z dostępnego adresu URL obiektu źródłowego.

//-------------------------------------------------
// Copy a blob from an external source
//-------------------------------------------------
public static async Task CopyFromExternalSourceAsync(
    string sourceLocation,
    BlockBlobClient destinationBlob)
{
    Uri sourceUri = new(sourceLocation);

    // Start the copy operation and wait for it to complete
    CopyFromUriOperation copyOperation = await destinationBlob.StartCopyFromUriAsync(sourceUri);
    await copyOperation.WaitForCompletionAsync();
}

Sprawdzanie stanu operacji kopiowania

Aby sprawdzić stan operacji, możesz wywołać metodę Copy Blob UpdateStatusAsync i przeanalizować odpowiedź, aby uzyskać wartość nagłówkax-ms-copy-status.

Poniższy przykład kodu pokazuje, jak sprawdzić stan operacji kopiowania:

public static async Task CheckCopyStatusAsync(CopyFromUriOperation copyOperation)
{
    // Check for the latest status of the copy operation
    Response response = await copyOperation.UpdateStatusAsync();

    // Parse the response to find x-ms-copy-status header
    if (response.Headers.TryGetValue("x-ms-copy-status", out string value))
        Console.WriteLine($"Copy status: {value}");
}

Przerywanie operacji kopiowania

Przerwanie oczekującej Copy Blob operacji powoduje utworzenie docelowego obiektu blob o zerowej długości. Jednak metadane docelowego obiektu blob mają nowe wartości skopiowane ze źródłowego obiektu blob lub ustawione jawnie podczas operacji kopiowania. Aby zachować oryginalne metadane przed kopią, przed wywołaniem jednej z metod kopiowania utwórz migawkę docelowego obiektu blob.

Aby przerwać oczekującą operację kopiowania, wywołaj jedną z następujących operacji:

Te metody opakowuje operację interfejsu API REST kopiowania obiektów blob , która anuluje oczekującą Copy Blob operację. Poniższy przykład kodu pokazuje, jak przerwać oczekującą Copy Blob operację:

public static async Task AbortBlobCopyAsync(
    CopyFromUriOperation copyOperation,
    BlobClient destinationBlob)
{
    // Check for the latest status of the copy operation
    Response response = await copyOperation.UpdateStatusAsync();

    // Parse the response to find x-ms-copy-status header
    if (response.Headers.TryGetValue("x-ms-copy-status", out string value))
    {
        if (value == "pending")
        {
            await destinationBlob.AbortCopyFromUriAsync(copyOperation.Id);
            Console.WriteLine($"Copy operation {copyOperation.Id} aborted");
        }
    }
}

Zasoby

Aby dowiedzieć się więcej na temat kopiowania obiektów blob przy użyciu biblioteki klienta usługi Azure Blob Storage dla platformy .NET, zobacz następujące zasoby.

Przykłady kodu

Operacje interfejsu API REST

Zestaw Azure SDK dla platformy .NET zawiera biblioteki, które są oparte na interfejsie API REST platformy Azure, co umożliwia interakcję z operacjami interfejsu API REST za pomocą znanych paradygmatów platformy .NET. Metody biblioteki klienta opisane w tym artykule korzystają z następujących operacji interfejsu API REST:

Zasoby biblioteki klienta

Powiązana zawartość

  • Ten artykuł jest częścią przewodnika dla deweloperów usługi Blob Storage dla platformy .NET. Aby dowiedzieć się więcej, zobacz pełną listę artykułów z przewodnika dla deweloperów w temacie Tworzenie aplikacji platformy .NET.