Mulai cepat: Membuat dan menetapkan tugas penyimpanan dengan menggunakan .NET

2025-05-07

Dalam panduan kilat ini, Anda mempelajari cara menggunakan pustaka klien Azure Storage Actions di .NET untuk membuat tugas penyimpanan data dan menetapkannya ke akun Azure Storage. Kemudian, Anda akan meninjau hasil pelaksanaan. Tugas penyimpanan menerapkan kebijakan kekekalan berbasis waktu pada dokumen Microsoft Word apa pun yang ada di akun penyimpanan.

Dokumentasi referensi API | Kode sumber pustaka | Paket (NuGet) | Sampel

Prasyarat

Langganan Azure - buat akun secara gratis
Akun penyimpanan Azure. Lihat membuat akun penyimpanan. Saat Anda membuat akun, pastikan untuk mengaktifkan dukungan kekekalan tingkat versi dan Anda tidak mengaktifkan fitur namespace hierarkis.
Peran Pemilik Data Blob Penyimpanan ditetapkan ke identitas pengguna milik Anda dalam konteks akun penyimpanan atau grup sumber daya.
Peran khusus yang ditetapkan ke identitas pengguna Anda di dalam konteks grup sumber daya yang berisi tindakan RBAC yang dibutuhkan untuk menetapkan tugas ke akun penyimpanan data. Lihat Izin yang diperlukan untuk menetapkan tugas.
Terpasang .NET Framework versi 4.7.2 atau lebih tinggi. Untuk informasi selengkapnya, lihat Mengunduh .NET Framework.

Persiapan

Bagian ini memandu Anda menyiapkan proyek.

Membuat proyek

Buat aplikasi konsol .NET menggunakan .NET CLI atau Visual Studio 2022.

Visual Studio 2022
.NET CLI

Di bagian atas Visual Studio, buka File>Baru>Proyek..
Di jendela dialog, masukkan aplikasi konsol ke dalam kotak pencarian templat proyek dan pilih hasil pertama. Pilih Berikutnya di bagian bawah dialog.
Untuk Nama Proyek, masukkan StorageTaskQuickstart. Biarkan nilai default di bidang lain dan pilih Berikutnya.
Untuk Framework, pastikan versi terbaru yang diinstal dari .NET dipilih. Lalu pilih Buat. Proyek baru terbuka di dalam lingkungan Visual Studio.

Di jendela konsol (seperti cmd, PowerShell, atau Bash), gunakan dotnet new perintah untuk membuat aplikasi konsol baru dengan nama BlobQuickstart. Perintah ini membuat proyek C# "Hello World" yang sederhana dengan satu file sumber: Program.cs.
```
dotnet new console -n StorageTaskQuickstart
```
Beralih ke direktori StorageTaskQuickstart yang baru dibuat.
```
cd StorageTaskQuickstart
```
Buka proyek di editor kode yang Anda inginkan. Untuk membuka proyek di:
- Visual Studio, temukan file StorageTaskQuickstart.csproj dan klik dua kali.
- Visual Studio Code, jalankan perintah berikut:
```
code .
```

Di Penjelajah Solusi, klik kanan node Dependensi proyek Anda. Pilih Kelola Paket NuGet.
Di jendela yang dihasilkan, pilih kotak centang Sertakan prarilis , lalu cari Azure.ResourceManager.StorageActions. Pilih hasil yang sesuai, lalu pilih Instal.
Selanjutnya, cari Azure.ResourceManager.Storage. Pilih hasil yang sesuai, lalu pilih Instal.
Cari Azure.ResourceManager.Authorization*. Pilih hasil yang sesuai, lalu pilih Instal.

Gunakan perintah berikut untuk menginstal Azure.ResourceManager.StorageActions paket:

dotnet add package Azure.ResourceManager.StorageActions --prerelease

Gunakan perintah berikut untuk menginstal Azure.ResourceManager.Storage paket:

dotnet add package Azure.ResourceManager.Storage

Gunakan perintah berikut untuk menginstal Azure.ResourceManager.Authorization paket:

dotnet add package Azure.ResourceManager.Authorization

Jika salah satu perintah ini gagal, ikuti langkah-langkah berikut:

Pastikan bahwa nuget.org ditambahkan sebagai sumber paket. Anda dapat mencantumkan sumber paket menggunakan dotnet nuget list source perintah :
```
dotnet nuget list source
```
Jika Anda tidak melihat nuget.org dalam daftar, Anda dapat menambahkannya menggunakan dotnet nuget add source perintah :
```
dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org
```

Sekarang setelah sumber paket diperbarui, jalankan perintah untuk menginstal paket.

Menyiapkan kode aplikasi

Ganti kode awal dalam Program.cs file sehingga cocok dengan contoh berikut, yang menyertakan pernyataan yang diperlukan using untuk Mulai Cepat ini.

using Azure;
using Azure.Core;
using Azure.ResourceManager;
using Azure.ResourceManager.Models;
using Azure.ResourceManager.Resources;
using Azure.ResourceManager.StorageActions;
using Azure.ResourceManager.StorageActions.Models;
using Azure.ResourceManager.Storage.Models;
using Azure.ResourceManager.Storage;
using Azure.ResourceManager.Authorization;
using Azure.ResourceManager.Authorization.Models;

Untuk pengembangan lokal, pastikan Anda diautentikasi dengan akun Microsoft Entra yang sama dengan yang Anda tetapkan perannya. Anda dapat mengautentikasi melalui alat pengembangan populer, seperti Azure CLI atau Azure PowerShell. Alat pengembangan yang dapat Anda autentikasi bervariasi di seluruh bahasa.
Masuk ke Azure melalui Azure CLI menggunakan perintah berikut:
```
az login
```
Pilih tombol Masuk di kanan atas Visual Studio.

Masuk menggunakan akun Microsoft Entra yang telah Anda tetapkan perannya sebelumnya.
Anda harus menginstal Azure CLI untuk bekerja dengan DefaultAzureCredential melalui Visual Studio Code.

Di menu utama Visual Studio Code, buka Terminal > Terminal Baru.

Masuk ke Azure melalui Azure CLI menggunakan perintah berikut:
```
az login
```
Masuk ke Azure menggunakan PowerShell melalui perintah berikut:
```
Connect-AzAccount
```
Untuk menggunakan DefaultAzureCredential, tambahkan paket Azure.Identity ke aplikasi Anda.
- Visual Studio
- .NET CLI
1. Di Penjelajah Solusi, klik kanan node Dependensi proyek Anda. Pilih Kelola Paket NuGet.
2. Di jendela yang ditampilkan, cari Azure.Identity. Pilih hasil yang sesuai, lalu pilih Instal.
```
dotnet add package Azure.Identity
```
Tambahkan pernyataan penggunaan berikut ke file Program.cs*:
```
using Azure.Identity;
```
Tambahkan kode berikut ke file Program.cs . Saat dijalankan di stasiun kerja lokal Anda selama pengembangan, kode akan menggunakan kredensial pengembang di alat yang diprioritaskan yang Anda masukkan untuk mengautentikasi ke Azure, seperti Azure CLI atau Visual Studio.
```
TokenCredential cred = new DefaultAzureCredential();
ArmClient client = new ArmClient(cred);
```

Membuat tugas penyimpanan

Pilih grup sumber daya di langganan tempat Anda ingin membuat tugas penyimpanan. Kemudian, dapatkan kumpulan tugas penyimpanan dari grup sumber daya tersebut.

<subscription-id> Ganti nilai tempat penampung dalam contoh ini dengan ID langganan Anda.
Ganti nilai <resource-group> ini dalam contoh ini dengan nama grup sumber daya.

 string subscriptionId = "<subscription-id>";
 string resourceGroupName = "<resource-group>";

 ResourceIdentifier resourceGroupResourceId = 
     ResourceGroupResource.CreateResourceIdentifier(subscriptionId, resourceGroupName);

 ResourceGroupResource resourceGroupResource = 
     client.GetResourceGroupResource(resourceGroupResourceId);

 StorageTaskCollection storageTaskcollection = resourceGroupResource.GetStorageTasks();

Tentukan klausa kondisi dengan menggunakan JSON. Kondisi memiliki kumpulan satu atau beberapa klausa. Klausa berisi properti, nilai, dan operator. Dalam JSON berikut, propertinya adalah Name, nilainya adalah .docx, dan operatornya adalah endsWith. Klausa ini hanya memungkinkan operasi pada dokumen Microsoft Word.
```
string clause = "[[endsWith(Name, '.docx')]]"
```
Untuk daftar lengkap properti dan operator, lihat Kondisi tugas penyimpanan.

Petunjuk / Saran

Anda dapat menambahkan beberapa kondisi ke string yang sama dan memisahkannya dengan koma.

Tentukan kondisi lengkap dengan menyertakan klausa yang sebelumnya Anda tentukan serta melibatkan dua operasi. Operasi pertama dalam definisi ini menetapkan kebijakan imutabilitas. Operasi kedua mengatur tag indeks blob dalam metadata dokumen Word.

 StorageTaskIfCondition condition = new(clause, new StorageTaskOperationInfo[]
 {
     new StorageTaskOperationInfo(StorageTaskOperationName.SetBlobImmutabilityPolicy)
     {
         Parameters =
         {
             ["untilDate"] = "2025-10-20T22:30:40",
             ["mode"] = "locked"
         },
         OnSuccess = OnSuccessAction.Continue,
         OnFailure = OnFailureAction.Break,
     },        
     new StorageTaskOperationInfo(StorageTaskOperationName.SetBlobTags)
     {
         Parameters =
         {
             ["tagsetImmutabilityUpdatedBy"] = "StorageTaskQuickstart"
         },
         OnSuccess = OnSuccessAction.Continue,
         OnFailure = OnFailureAction.Break,
     }

 });

Buat tugas penyimpanan lalu tambahkan ke kumpulan tugas penyimpanan.

 StorageTaskProperties storageTaskProperties = 
     new(true, "My storage task", new StorageTaskAction(condition));

 StorageTaskData storageTaskData = new(
     new AzureLocation("westus"), 
     new ManagedServiceIdentity("SystemAssigned"), 
     storageTaskProperties);

 var storageTaskResult = (storageTaskcollection.CreateOrUpdate
     (WaitUntil.Completed, "mystoragetask", storageTaskData)).Value;

 Console.WriteLine($"Succeeded on id: {storageTaskResult.Data.Id}");

Membuat penugasan

Untuk menggunakan tugas penyimpanan, Anda harus membuat penugasan tugas penyimpanan. Penugasan disimpan sebagai bagian dari instans sumber daya akun penyimpanan, dan mendefinisikan di antara pengaturan lain, subset objek yang akan ditargetkan, kapan dan seberapa sering tugas berjalan terhadap objek tersebut, dan di mana laporan eksekusi disimpan.

Tentukan filter awalan, frekuensi eksekusi, waktu mulai dengan membuat konteks eksekusi. Contoh berikut menargetkan mycontainer kontainer dan dijadwalkan untuk dijalankan dalam 10 menit dari waktu sekarang.

ExecutionTriggerParameters executionTriggerParameters = new()
{
    StartOn = DateTime.Now.AddMinutes(10).ToUniversalTime()
};

ExecutionTrigger executionTrigger = 
    new(ExecutionTriggerType.RunOnce, executionTriggerParameters);

StorageTaskAssignmentExecutionContext storageTaskAssignmentExecutionContext = 
    new(executionTrigger)
{
    Target = new ExecutionTarget
    {
        Prefix = { "mycontainer/" },
        ExcludePrefix = { },
    }
};

Buat penetapan tugas penyimpanan lalu tambahkan ke kumpulan penetapan tugas penyimpanan. Penetapan berikut menyertakan konteks eksekusi yang Anda buat di langkah sebelumnya. Ini juga menentukan akun penyimpanan target dan dikonfigurasi untuk menyimpan laporan eksekusi ke folder bernama storage-tasks-report.

string accountName = "mystorageaccount";

ResourceIdentifier storageAccountResourceId = 
    StorageAccountResource.CreateResourceIdentifier
    (subscriptionId, resourceGroupName, accountName);

StorageAccountResource storageAccount = 
    client.GetStorageAccountResource(storageAccountResourceId);

StorageTaskAssignmentCollection storageTaskAssignmentcollection = 
    storageAccount.GetStorageTaskAssignments();

StorageTaskAssignmentProperties storageTaskAssignmentProperties = new(
    new ResourceIdentifier(storageTaskResult.Data.Id.ToString()), true, 
    "My Storage task assignment",
    storageTaskAssignmentExecutionContext,
    new("storage-tasks-report"));

// Create and execute the storage task assignment
storageTaskAssignmentcollection.CreateOrUpdate(
WaitUntil.Started,
"myStorageTaskAssignment",
new StorageTaskAssignmentData(storageTaskAssignmentProperties));

Berikan izin tugas penyimpanan untuk melakukan operasi pada akun penyimpanan target. Tetapkan peran Storage Blob Data Owner ke identitas terkelola yang ditetapkan oleh sistem dari pekerjaan penyimpanan.


var roleDefId = $"/subscriptions/" + subscriptionId + "/providers/Microsoft.Authorization/roleDefinitions/<b7e6dc6d-f1e8-4753-8033-0f276bb0955b>";

var operationContent = new RoleAssignmentCreateOrUpdateContent(
    new ResourceIdentifier(roleDefId),
    storageTaskResult.Data.Identity.PrincipalId ?? throw new InvalidOperationException("PrincipalId is null"))
{
    PrincipalType = RoleManagementPrincipalType.ServicePrincipal
};

ResourceIdentifier roleAssignmentResourceId = RoleAssignmentResource.CreateResourceIdentifier(storageAccount.Id, Guid.NewGuid().ToString());

RoleAssignmentResource roleAssignment = client.GetRoleAssignmentResource(roleAssignmentResourceId);

ArmOperation <RoleAssignmentResource> lro = await roleAssignment.UpdateAsync(WaitUntil.Completed, operationContent);
RoleAssignmentResource result = lro.Value;
RoleAssignmentData resourceData = result.Data;
Console.WriteLine($"Succeeded on id: {resourceData.Id}");

Menjalankan kode

Jika Anda menggunakan Visual Studio, tekan F5 untuk membangun dan menjalankan kode serta berinteraksi dengan aplikasi konsol. Jika Anda menggunakan .NET CLI, buka direktori aplikasi Anda, lalu bangun dan jalankan aplikasi.

dotnet build

dotnet run

Menampilkan hasil eksekusi tugas

Setelah tugas selesai berjalan, dapatkan ringkasan laporan eksekusi untuk setiap tugas.

    ResourceIdentifier storageTaskResourceId = StorageTaskResource.CreateResourceIdentifier
        (subscriptionId, resourceGroupName, "mystoragetask");
    StorageTaskResource storageTask = client.GetStorageTaskResource(storageTaskResourceId);
    // invoke the operation and iterate over the result
    await foreach (Azure.ResourceManager.StorageActions.Models.StorageTaskReportInstance item in storageTask.GetStorageTasksReportsAsync())
    {
        Console.WriteLine($"Succeeded: {item.Properties.SummaryReportPath}");
    }

Bidang SummaryReportPath dari setiap ringkasan laporan berisi jalur ke laporan terperinci. Laporan tersebut berisi daftar yang dipisahkan koma dari kontainer, blob, dan operasi yang dilakukan, bersama dengan status.

Membersihkan sumber daya

Hapus semua aset yang telah dibuat. Cara termudah untuk menghapus aset adalah dengan menghapus grup sumber daya. Menghapus grup sumber daya juga menghapus semua sumber daya yang disertakan dalam grup. Pada contoh berikut, menghapus grup sumber daya akan menghapus akun penyimpanan dan grup sumber daya itu sendiri.

Remove-AzResourceGroup -Name $ResourceGroup

Langkah selanjutnya

Apa itu Azure Storage Actions?