Sdílet prostřednictvím

Kopírování objektu blob s asynchronním plánováním pomocí .NET

  • Článek

Tento článek ukazuje, jak zkopírovat objekt blob s asynchronním plánováním pomocí klientské knihovny Azure Storage pro .NET. Objekt blob můžete zkopírovat ze zdroje ve stejném účtu úložiště, ze zdroje v jiném účtu úložiště nebo z libovolného přístupného objektu načteného prostřednictvím požadavku HTTP GET na dané adrese URL. Můžete také přerušit čekající operaci kopírování.

Metody klientské knihovny popsané v tomto článku používají operaci copy blob REST API a lze ji použít, když chcete provést kopírování s asynchronním plánováním. Ve většině scénářů kopírování, ve kterých chcete přesunout data do účtu úložiště a mít adresu URL zdrojového objektu, najdete v tématu Kopírování objektu blob z adresy URL zdrojového objektu pomocí .NET.

Požadavky

Nastavení prostředí

Pokud nemáte existující projekt, v této části se dozvíte, jak nastavit projekt pro práci s klientskou knihovnou Azure Blob Storage pro .NET. Kroky zahrnují instalaci balíčku, přidání using direktiv a vytvoření autorizovaného objektu klienta. Podrobnosti najdete v tématu Začínáme se službou Azure Blob Storage a .NET.

Instalace balíčků

Z adresáře projektu nainstalujte balíčky pro klientské knihovny Azure Blob Storage a Azure Identity pomocí dotnet add package příkazu. Balíček Azure.Identity je potřeba pro připojení bez hesla ke službám Azure.

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

Přidání using direktiv

Na začátek souboru kódu přidejte tyto using direktivy:

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

Některé příklady kódu v tomto článku mohou vyžadovat další using direktivy.

Vytvoření objektu klienta

Pokud chcete připojit aplikaci ke službě Blob Storage, vytvořte instanci BlobServiceClient. Následující příklad ukazuje, jak vytvořit objekt klienta pro DefaultAzureCredential autorizaci:

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

    return client;
}

Klienta služby můžete zaregistrovat pro injektáž závislostí v aplikaci .NET.

Můžete také vytvořit klientské objekty pro konkrétní kontejnery nebo objekty blob. Další informace o vytváření a správě klientských objektů najdete v tématu Vytváření a správa klientských objektů, které pracují s datovými prostředky.

Autorizace

Autorizační mechanismus musí mít potřebná oprávnění k provedení operace kopírování nebo k přerušení čekající kopie. Pro autorizaci pomocí Microsoft Entra ID (doporučeno) se nejméně privilegovaná předdefinovaná role Azure RBAC liší v závislosti na několika faktorech. Další informace najdete v pokynech k autorizaci pro kopírování objektů blob (REST API) nebo přerušení kopírování objektu blob (REST API).

Kopírování objektů blob pomocí asynchronního plánování

Operace Copy Blob se může dokončit asynchronně a provádí se na základě maximálního úsilí, což znamená, že není zaručeno, že se operace spustí okamžitě nebo dokončí v zadaném časovém rámci. Operace kopírování se naplánuje na pozadí a provede se tak, jak má server dostupné prostředky. Operace může být dokončena synchronně, pokud se kopie vyskytuje ve stejném účtu úložiště.

Copy Blob Operace může provádět některou z následujících akcí:

  • Zkopírujte zdrojový objekt blob do cílového objektu blob s jiným názvem. Cílovým objektem blob může být existující objekt blob stejného typu objektu blob (blok, připojení nebo stránka), nebo může být novým objektem blob vytvořeným operací kopírování.
  • Zkopírujte zdrojový objekt blob do cílového objektu blob se stejným názvem, který nahradí cílový objekt blob. Tento typ operace kopírování odebere všechny nepotvrzené bloky a přepíše metadata cílového objektu blob.
  • Zkopírujte zdrojový soubor ve službě Azure File Service do cílového objektu blob. Cílovým objektem blob může být existující objekt blob bloku nebo může být nový objekt blob bloku vytvořený operací kopírování. Kopírování ze souborů do objektů blob stránky nebo doplňovacích objektů blob se nepodporuje.
  • Zkopírujte snímek nad jeho základní objekt blob. Zvýšením úrovně snímku na pozici základního objektu blob můžete obnovit starší verzi objektu blob.
  • Zkopírujte snímek do cílového objektu blob s jiným názvem. Výsledný cílový objekt blob je zapisovatelný objekt blob, nikoli snímek.

Další informace o Copy Blob operaci, včetně informací o vlastnostech, značkách indexu, metadatech a fakturaci, najdete v tématu Kopírování poznámek k objektům blob.

Kopírování objektu blob s asynchronním plánováním

Tato část poskytuje přehled metod poskytovaných klientskou knihovnou azure Storage pro .NET k provedení operace kopírování s asynchronním plánováním.

Následující metody zabalí operaci copy blob REST API a spustí asynchronní kopii dat ze zdrojového objektu blob:

Metody StartCopyFromUri StartCopyFromUriAsync vrátí CopyFromUriOperation objekt obsahující informace o operaci kopírování. Tyto metody se používají, když chcete asynchronní plánování operace kopírování.

Kopírování objektu blob ze zdroje v Azure

Pokud kopírujete objekt blob ve stejném účtu úložiště, operace se může dokončit synchronně. Přístup ke zdrojovému objektu blob je možné autorizovat prostřednictvím ID Microsoft Entra, sdíleného přístupového podpisu (SAS) nebo klíče účtu. Operace alterativní synchronní kopírování najdete v tématu Kopírování objektu blob ze zdrojové adresy URL objektu pomocí .NET.

Pokud je zdrojem kopírování objekt blob v jiném účtu úložiště, může operace asynchronně dokončit. Zdrojový objekt blob musí být veřejný nebo autorizovaný prostřednictvím tokenu SAS. Token SAS musí obsahovat oprávnění ke čtení ('r' ). Další informace o tokenech SAS najdete v tématu Delegování přístupu pomocí sdílených přístupových podpisů.

Následující příklad ukazuje scénář kopírování zdrojového objektu blob z jiného účtu úložiště s asynchronním plánováním. V tomto příkladu vytvoříme adresu URL zdrojového objektu blob s připojeným tokenem SAS delegování uživatele. Příklad ukazuje, jak vygenerovat token SAS pomocí klientské knihovny, ale můžete také zadat vlastní. Příklad také ukazuje, jak zapůjčení zdrojového objektu blob během operace kopírování, aby se zabránilo změnám objektu blob z jiného klienta. Operace Copy Blob uloží ETag hodnotu zdrojového objektu blob při spuštění operace kopírování. ETag Pokud se hodnota změní před dokončením operace kopírování, operace selže.

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

Poznámka:

Tokeny SAS delegování uživatelů nabízejí větší zabezpečení, protože jsou podepsané pomocí přihlašovacích údajů Microsoft Entra místo klíče účtu. K vytvoření tokenu SAS delegování uživatele potřebuje objekt zabezpečení Microsoft Entra příslušná oprávnění. Požadavky na autorizaci najdete v tématu Získání klíče delegování uživatele.

Kopírování objektu blob ze zdroje mimo Azure

Operaci kopírování můžete provést u libovolného zdrojového objektu, který lze načíst prostřednictvím požadavku HTTP GET na danou adresu URL, včetně přístupných objektů mimo Azure. Následující příklad ukazuje scénář kopírování objektu blob z adresy URL přístupného zdrojového objektu.

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

Kontrola stavu operace kopírování

Pokud chcete zkontrolovat stav Copy Blob operace, můžete volat UpdateStatusAsync a parsovat odpověď a získat hodnotu hlavičky x-ms-copy-status .

Následující příklad kódu ukazuje, jak zkontrolovat stav operace kopírování:

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

Přerušení operace kopírování

Přerušení čekající Copy Blob operace způsobí, že cílový objekt blob má nulovou délku. Metadata cílového objektu blob ale mají nové hodnoty zkopírované ze zdrojového objektu blob nebo explicitně nastavené během operace kopírování. Chcete-li zachovat původní metadata před kopií, vytvořte snímek cílového objektu blob před voláním jedné z metod kopírování.

Pokud chcete přerušit čekající operaci kopírování, zavolejte jednu z následujících operací:

Tyto metody zabalí operaci Abort Copy Blob REST API, která zruší čekající Copy Blob operaci. Následující příklad kódu ukazuje, jak přerušit čekající Copy Blob operaci:

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

Zdroje informací

Další informace o kopírování objektů blob pomocí klientské knihovny azure Blob Storage pro .NET najdete v následujících zdrojích informací.

Ukázky kódu

Operace rozhraní REST API

Sada Azure SDK pro .NET obsahuje knihovny, které jsou postavené na rozhraní Azure REST API a umožňují interakci s operacemi rozhraní REST API prostřednictvím známých paradigmat .NET. Metody klientské knihovny popsané v tomto článku používají následující operace rozhraní REST API:

Prostředky klientské knihovny

Související obsah

  • Tento článek je součástí příručky pro vývojáře služby Blob Storage pro .NET. Další informace najdete v úplném seznamu článků příručky pro vývojáře na webu Sestavení aplikace .NET.