Aracılığıyla paylaş

.NET kullanarak zaman uyumsuz zamanlamayla blob kopyalama

  • Makale

Bu makalede, .NET için Azure Depolama istemci kitaplığını kullanarak zaman uyumsuz zamanlamayla bir blobu kopyalama işlemi gösterilmektedir. Blobu aynı depolama hesabındaki bir kaynaktan, farklı bir depolama hesabındaki bir kaynaktan veya belirli bir URL'deki HTTP GET isteği aracılığıyla alınan erişilebilir nesnelerden kopyalayabilirsiniz. Bekleyen kopyalama işlemini de durdurabilirsiniz.

Bu makalede ele alınan istemci kitaplığı yöntemleri, Blob REST API'sini Kopyalama işlemini kullanır ve zaman uyumsuz zamanlamayla bir kopyalama gerçekleştirmek istediğinizde kullanılabilir. Verileri depolama hesabına taşımak istediğiniz ve kaynak nesnenin URL'sine sahip olmak istediğiniz çoğu kopyalama senaryosu için bkz . .NET ile kaynak nesne URL'sinden blob kopyalama.

Önkoşullar

Ortamınızı ayarlama

Var olan bir projeniz yoksa, bu bölümde bir projenin .NET için Azure Blob Depolama istemci kitaplığıyla çalışacak şekilde nasıl ayarlanacağı gösterilir. Adımlar arasında paket yükleme, yönergeler ekleme using ve yetkili istemci nesnesi oluşturma yer alır. Ayrıntılar için bkz. Azure Blob Depolama ve .NET'i kullanmaya başlama.

Paketleri yükleme

Proje dizininizden komutunu kullanarak dotnet add package Azure Blob Depolama ve Azure Identity istemci kitaplıkları için paketleri yükleyin. Azure hizmetlerine parolasız bağlantılar için Azure.Identity paketi gereklidir.

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

Yönerge ekleme using

Kod dosyanızın en üstüne şu using yönergeleri ekleyin:

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

Bu makaledeki bazı kod örnekleri için ek using yönergeler gerekebilir.

İstemci nesnesi oluşturma

Bir uygulamayı Blob Depolama'ya bağlamak için bir BlobServiceClient örneği oluşturun. Aşağıdaki örnekte yetkilendirme için kullanarak DefaultAzureCredential bir istemci nesnesinin nasıl oluşturulacağı gösterilmektedir:

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

    return client;
}

Bir .NET uygulamasına bağımlılık ekleme için bir hizmet istemcisi kaydedebilirsiniz.

Ayrıca, belirli kapsayıcılar veya bloblar için istemci nesneleri de oluşturabilirsiniz. İstemci nesneleri oluşturma ve yönetme hakkında daha fazla bilgi edinmek için bkz . Veri kaynaklarıyla etkileşim kuran istemci nesneleri oluşturma ve yönetme.

Yetkilendirme

Yetkilendirme mekanizması, kopyalama işlemini gerçekleştirmek veya bekleyen bir kopyayı durdurmak için gerekli izinlere sahip olmalıdır. Microsoft Entra Id ile yetkilendirme için (önerilen), en az ayrıcalıklı Azure RBAC yerleşik rolü çeşitli faktörlere göre değişir. Daha fazla bilgi edinmek için Bkz. Blob Kopyalama (REST API) veya Kopyalamayı Durdur Blobu (REST API) için yetkilendirme kılavuzu.

Zaman uyumsuz zamanlamayla blobları kopyalama hakkında

İşlem Copy Blob zaman uyumsuz olarak tamamlanabilir ve en iyi çaba temelinde gerçekleştirilir. Bu, işlemin belirtilen zaman çerçevesi içinde hemen başlatılması veya tamamlanmasının garanti olmadığı anlamına gelir. Kopyalama işlemi arka planda zamanlanır ve sunucuda kullanılabilir kaynaklar olduğundan gerçekleştirilir. Kopyalama aynı depolama hesabında gerçekleşirse işlem zaman uyumlu olarak tamamlanabilir.

Bir Copy Blob işlem aşağıdaki eylemlerden herhangi birini gerçekleştirebilir:

  • Kaynak blobu farklı bir adla hedef bloba kopyalayın. Hedef blob aynı blob türünde (blok, ekleme veya sayfa) var olan bir blob olabileceği gibi, kopyalama işlemi tarafından oluşturulan yeni bir blob da olabilir.
  • Kaynak blobu hedef blob yerine aynı ada sahip bir hedef bloba kopyalayın. Bu tür kopyalama işlemi, kaydedilmemiş blokları kaldırır ve hedef blobun meta verilerinin üzerine yazar.
  • Azure Dosya hizmetindeki bir kaynak dosyayı hedef bloba kopyalayın. Hedef blob mevcut bir blok blobu veya kopyalama işlemi tarafından oluşturulan yeni bir blok blobu olabilir. Dosyalardan sayfa bloblarına veya ekleme bloblarına kopyalama desteklenmez.
  • Bir anlık görüntüyü temel blobu üzerinden kopyalayın. Anlık görüntüyü temel blobun konumuna yükseltme yoluyla blobun önceki bir sürümünü geri yükleyebilirsiniz.
  • Bir anlık görüntüyü farklı bir adla hedef bloba kopyalayın. Sonuçta elde edilen hedef blob, anlık görüntü değil yazılabilir bir blobdur.

Özellikler, dizin etiketleri, meta veriler ve faturalama gibi işlemler hakkında Copy Blob daha fazla bilgi edinmek için bkz . Blob açıklamalarını kopyalama.

Zaman uyumsuz zamanlamayla blob kopyalama

Bu bölümde, zaman uyumsuz zamanlamayla kopyalama işlemi gerçekleştirmek üzere .NET için Azure Depolama istemci kitaplığı tarafından sağlanan yöntemlere genel bir bakış sunulmaktadır.

Aşağıdaki yöntemler Blobu Kopyalama REST API'sini sarmalar ve kaynak blobdan zaman uyumsuz bir veri kopyası başlatır:

ve StartCopyFromUriAsync yöntemleri, StartCopyFromUri kopyalama işlemi hakkında bilgi içeren bir CopyFromUriOperation nesnesi döndürür. Bu yöntemler, bir kopyalama işlemi için zaman uyumsuz zamanlama istediğinizde kullanılır.

Azure'da bir kaynaktan blob kopyalama

Aynı depolama hesabı içindeki bir blobu kopyalıyorsanız işlem zaman uyumlu bir şekilde tamamlanabilir. Kaynak bloba erişim Microsoft Entra Kimliği, paylaşılan erişim imzası (SAS) veya hesap anahtarı aracılığıyla yetkilendirilebilir. Değişiklikli zaman uyumlu kopyalama işlemi için bkz . .NET ile kaynak nesne URL'sinden blob kopyalama.

Kopyalama kaynağı farklı bir depolama hesabındaki bir blobsa işlem zaman uyumsuz olarak tamamlanabilir. Kaynak blob genel veya SAS belirteci aracılığıyla yetkilendirilmelidir. SAS belirtecinin Okuma ('r') iznini içermesi gerekir. SAS belirteçleri hakkında daha fazla bilgi edinmek için bkz . Paylaşılan erişim imzalarıyla temsilci erişimi.

Aşağıdaki örnekte, zaman uyumsuz zamanlamayla farklı bir depolama hesabından kaynak blob kopyalamaya yönelik bir senaryo gösterilmektedir. Bu örnekte, eklenen kullanıcı temsilcisi SAS belirteciyle bir kaynak blob URL'si oluşturacağız. Örnekte, istemci kitaplığını kullanarak SAS belirtecinin nasıl oluşturulacağı gösterilmektedir, ancak kendiniz de sağlayabilirsiniz. Örnek ayrıca farklı bir istemciden blobda değişiklik yapılmasını önlemek için kopyalama işlemi sırasında kaynak blobu kiralamayı da gösterir. Kopyalama Copy Blob işlemi başladığında işlem kaynak blobun değerini kaydeder ETag . ETag Kopyalama işlemi tamamlanmadan önce değer değiştirilirse işlem başarısız olur.

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

Not

Kullanıcı temsilcisi SAS belirteçleri, hesap anahtarı yerine Microsoft Entra kimlik bilgileriyle imzalanmış olduğundan daha fazla güvenlik sunar. Kullanıcı temsilcisi SAS belirteci oluşturmak için Microsoft Entra güvenlik sorumlusunun uygun izinlere sahip olması gerekir. Yetkilendirme gereksinimleri için bkz . Kullanıcı Temsilcisi Anahtarı Alma.

Azure dışındaki bir kaynaktan blob kopyalama

Azure dışındaki erişilebilir nesneler de dahil olmak üzere belirli bir URL'de HTTP GET isteği aracılığıyla alınabilen herhangi bir kaynak nesne üzerinde kopyalama işlemi gerçekleştirebilirsiniz. Aşağıdaki örnekte, erişilebilir bir kaynak nesne URL'sinden blob kopyalamaya yönelik bir senaryo gösterilmektedir.

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

Kopyalama işleminin durumunu denetleme

Bir Copy Blob işlemin durumunu denetlemek için UpdateStatusAsync'i çağırabilir ve yanıtı ayrıştırarak üst bilgi değerini x-ms-copy-status alabilirsiniz.

Aşağıdaki kod örneği, kopyalama işleminin durumunu denetlemeyi gösterir:

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

Kopyalama işlemini durdurma

Bekleyen Copy Blob bir işlemin durdurularak sıfır uzunlukta bir hedef blob elde edilir. Ancak hedef blob için meta veriler, kaynak blobdan kopyalanan veya kopyalama işlemi sırasında açıkça ayarlanan yeni değerlere sahiptir. Özgün meta verileri kopyalamadan önce tutmak için, kopyalama yöntemlerinden birini çağırmadan önce hedef blobun anlık görüntüsünü alın.

Bekleyen kopyalama işlemini durdurmak için aşağıdaki işlemlerden birini çağırın:

Bu yöntemler Bekleyen işlemi Copy Blob iptal eden Blob Kopyalamayı Durdur REST API işlemini sarmalar. Aşağıdaki kod örneğinde bekleyen Copy Blob bir işlemin nasıl durdurulacakları gösterilmektedir:

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

Kaynaklar

.NET için Azure Blob Depolama istemci kitaplığını kullanarak blobları kopyalama hakkında daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın.

REST API işlemleri

.NET için Azure SDK, Azure REST API'sinin üzerinde derlenmiş kitaplıklar içerir ve tanıdık .NET paradigmalarıyla REST API işlemleriyle etkileşim kurmanızı sağlar. Bu makalede ele alınan istemci kitaplığı yöntemleri aşağıdaki REST API işlemlerini kullanır:

  • Blobu Kopyalama (REST API)
  • Blob Kopyalamayı Durdur (REST API)

Kod örnekleri

İstemci kitaplığı kaynakları