Bagikan melalui

Mulai Cepat: Pustaka klien Azure Blob Storage untuk .NET

  • Artikel

Catatan

Opsi Build from scratch memandu Anda selangkah demi selangkah melalui proses pembuatan proyek baru, menginstal paket, menulis kode, dan menjalankan aplikasi konsol dasar. Pendekatan ini direkomendasikan jika Anda ingin memahami semua detail yang terlibat dalam membuat aplikasi yang terhubung ke Azure Blob Storage. Jika Anda lebih suka mengotomatiskan tugas penyebaran dan memulai dengan proyek yang telah selesai, pilih Mulai dengan templat.

Catatan

Opsi Mulai dengan templat menggunakan Azure Developer CLI untuk mengotomatiskan tugas penyebaran dan memulai Anda dengan proyek yang telah selesai. Pendekatan ini direkomendasikan jika Anda ingin menjelajahi kode secepat mungkin tanpa melalui tugas penyiapan. Jika Anda lebih suka instruksi langkah demi langkah untuk membangun aplikasi, pilih Bangun dari awal.

Mulai menggunakan pustaka klien Azure Blob Storage untuk .NET. Azure Blob Storage adalah solusi penyimpanan objek Microsoft untuk cloud, dan dioptimalkan untuk menyimpan sejumlah besar data tidak terstruktur.

Dalam artikel ini, Anda mengikuti langkah-langkah untuk menginstal paket dan mencoba contoh kode untuk tugas dasar.

Dalam artikel ini, Anda menggunakan Azure Developer CLI untuk menyebarkan sumber daya Azure dan menjalankan aplikasi konsol lengkap hanya dengan beberapa perintah.

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

Video ini menunjukkan kepada Anda cara mulai menggunakan pustaka klien Azure Blob Storage untuk .NET.

Langkah-langkah dalam video juga dijelaskan di bagian berikut.

Prasyarat

Menyiapkan

Bagian ini akan memandu Anda dalam menyiapkan proyek untuk dikerjakan dengan pustaka klien Azure Blob Storage untuk .NET.

Membuat proyek

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

  1. Di bagian atas Visual Studio, buka File>Baru>Proyek..

  2. Di jendela dialog, masukkan aplikasi konsol ke dalam kotak pencarian templat proyek dan pilih hasil pertama. Pilih Berikutnya di bagian bawah dialog.

    Cuplikan layar yang menunjukkan cara membuat proyek baru menggunakan Visual Studio.

  3. Untuk Nama Proyek, masukkan BlobQuickstart. Biarkan nilai default di bidang lain dan pilih Berikutnya.

  4. Untuk Framework, pastikan versi terbaru yang diinstal dari .NET dipilih. Kemudian pilih Buat. Proyek baru terbuka di dalam lingkungan Visual Studio.

Pasang paket

Untuk berinteraksi dengan Azure Blob Storage, instal pustaka klien Azure Blob Storage untuk .NET.

  1. Di Penjelajah Solusi, klik kanan node Dependensi proyek Anda. Pilih Kelola Paket NuGet.

  2. Di jendela yang ditampilkan, cari Azure.Storage.Blobs. Pilih hasil yang sesuai, lalu pilih Instal.

    Cuplikan layar yang menunjukkan cara menambahkan paket baru menggunakan Visual Studio.

Menyiapkan kode aplikasi

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

using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

Dengan Azure Developer CLI terinstal, Anda dapat membuat akun penyimpanan dan menjalankan kode sampel hanya dengan beberapa perintah. Anda dapat menjalankan proyek di lingkungan pengembangan lokal Anda, atau di DevContainer.

Menginisialisasi templat Azure Developer CLI dan menyebarkan sumber daya

Dari direktori kosong, ikuti langkah-langkah ini untuk menginisialisasi azd templat, memprovisikan sumber daya Azure, dan mulai menggunakan kode:

  • Kloning aset repositori mulai cepat dari GitHub dan inisialisasi templat secara lokal:

    azd init --template blob-storage-quickstart-dotnet

    Anda akan dimintai informasi berikut:

    • Nama lingkungan: Nilai ini digunakan sebagai awalan untuk semua sumber daya Azure yang dibuat oleh Azure Developer CLI. Nama harus unik di semua langganan Azure dan panjangnya harus antara 3 dan 24 karakter. Nama hanya dapat berisi angka dan huruf kecil.

  • Masuk ke Azure:

    azd auth login

  • Provisikan dan sebarkan sumber daya ke Azure:

    azd up

    Anda akan dimintai informasi berikut:

    • Langganan: Langganan Azure tempat sumber daya Anda disebarkan.
    • Lokasi: Wilayah Azure tempat sumber daya Anda disebarkan.

    Penyebaran mungkin perlu waktu beberapa menit untuk diselesaikan. Output dari azd up perintah mencakup nama akun penyimpanan yang baru dibuat, yang akan Anda perlukan nanti untuk menjalankan kode.

Jalankan kode sampel

Pada titik ini, sumber daya disebarkan ke Azure dan proyek siap dijalankan. Ikuti langkah-langkah ini untuk memperbarui nama akun penyimpanan dalam kode dan menjalankan aplikasi konsol sampel:

  • Perbarui nama akun penyimpanan: Navigasikan ke src direktori dan edit Program.cs. <storage-account-name> Temukan tempat penampung dan ganti dengan nama aktual akun penyimpanan yang dibuat oleh azd up perintah . Simpan perubahan.
  • Jalankan proyek: Jika Anda menggunakan Visual Studio, tekan F5 untuk membuat dan menjalankan kode dan berinteraksi dengan aplikasi konsol. Jika Anda menggunakan .NET CLI, navigasikan ke direktori aplikasi Anda, buat proyek menggunakan dotnet build, dan jalankan aplikasi menggunakan dotnet run.
  • Amati output: Aplikasi ini membuat file pengujian di folder data lokal Anda dan mengunggahnya ke kontainer di akun penyimpanan. Contoh kemudian mencantumkan blob dalam kontainer dan mengunduh file dengan nama baru sehingga Anda dapat membandingkan file lama dan baru.

Untuk mempelajari selengkapnya tentang cara kerja kode sampel, lihat Contoh kode.

Setelah selesai menguji kode, lihat bagian Bersihkan sumber daya untuk menghapus sumber daya yang azd up dibuat oleh perintah .

Model objek

Azure Blob Storage dioptimalkan untuk menyimpan data tidak terstruktur dalam jumlah besar. Data yang tidak terstruktur tidak mematuhi model atau definisi data tertentu, seperti teks atau data biner. Penyimpanan Blob menawarkan tiga jenis sumber daya:

  • Akun penyimpanan
  • Kontainer di akun penyimpanan
  • Blob di dalam kontainer

Diagram berikut menunjukkan hubungan antara ketiga sumber daya ini.

Diagram arsitektur Blob Storage.

Gunakan kelas .NET berikut untuk berinteraksi dengan sumber daya ini:

  • BlobServiceClient: Kelas BlobServiceClient memungkinkan Anda memanipulasi sumber daya Microsoft Azure Storage dan kontainer blob.
  • BlobContainerClient: Kelas BlobContainerClient ini memungkinkan Anda memanipulasi kontainer Azure Storage dan blobnya.
  • BlobClient: Kelas BlobClient ini memungkinkan Anda memanipulasi blob Azure Storage.

Contoh kode

Cuplikan kode sampel di bagian berikut menunjukkan cara melakukan tugas berikut dengan pustaka klien Azure Blob Storage untuk .NET:

Penting

Pastikan Anda telah menginstal paket NuGet yang benar dan menambahkan yang diperlukan menggunakan pernyataan agar sampel kode berfungsi, seperti yang dijelaskan di bagian penyusupan .

Catatan

Templat Azure Developer CLI menyertakan proyek dengan kode sampel yang sudah ada. Contoh berikut memberikan detail untuk setiap bagian kode sampel. Templat mengimplementasikan metode autentikasi tanpa kata sandi yang direkomendasikan, seperti yang dijelaskan di bagian Autentikasi ke Azure . Metode string koneksi ditampilkan sebagai alternatif, tetapi tidak digunakan dalam templat dan tidak disarankan untuk kode produksi.

Mengautentikasi ke Azure dan mengotorisasi akses ke data blob

Permintaan aplikasi ke Azure Blob Storage harus diotorisasi. Menggunakan kelas yang DefaultAzureCredential disediakan oleh pustaka klien Azure Identity adalah pendekatan yang direkomendasikan untuk menerapkan koneksi tanpa kata sandi ke layanan Azure dalam kode Anda, termasuk Blob Storage.

Anda juga dapat mengotorisasi permintaan untuk Azure Blob Storage menggunakan kunci akses akun. Namun, pendekatan ini harus digunakan dengan hati-hati. Pengembang harus rajin untuk tidak pernah mengekspos kunci akses di lokasi yang tidak aman. Siapa pun yang memiliki kunci akses dapat mengotorisasi permintaan terhadap akun penyimpanan, dan secara efektif memiliki akses ke semua data. DefaultAzureCredential menawarkan keuntungan pengelolaan dan keamanan yang ditingkatkan melalui kunci akun untuk memungkinkan autentikasi tanpa kata sandi. Kedua opsi diperlihatkan dalam contoh berikut.

DefaultAzureCredential adalah kelas yang disediakan oleh pustaka klien Azure Identity untuk .NET, yang dapat Anda pelajari lebih lanjut di ringkasan DefaultAzureCredential. DefaultAzureCredential mendukung beberapa metode autentikasi dan menentukan metode autentikasi yang harus digunakan saat runtime bahasa umum. Pendekatan ini memungkinkan aplikasi Anda menggunakan metode autentikasi yang berbeda di lingkungan yang berbeda (lokal vs. produksi) tanpa menerapkan kode spesifik per lingkungan.

Urutan dan lokasi tempat DefaultAzureCredential mencari kredensial dapat ditemukan di ringkasan pustaka Azure Identity.

Misalnya, aplikasi Anda dapat mengautentikasi menggunakan kredensial masuk Visual Studio saat mengembangkan secara lokal. Aplikasi Anda kemudian dapat menggunakan identitas terkelola setelah disebarkan ke Azure. Tidak diperlukan perubahan kode untuk transisi ini.

Menetapkan peran ke akun pengguna Microsoft Entra Anda

Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang mengakses data blob memiliki izin yang benar. Anda akan memerlukan Kontributor Data Blob Penyimpanan untuk membaca dan menulis data blob. Untuk menetapkan sendiri peran ini, Anda harus diberi peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan Microsoft.Authorization/roleAssignments/write . Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Anda dapat mempelajari selengkapnya tentang cakupan yang tersedia untuk penetapan peran di halaman gambaran umum cakupan.

Dalam skenario ini, Anda akan menetapkan izin ke akun pengguna, yang tercakup ke akun penyimpanan, untuk mengikuti Prinsip Hak Istimewa Paling Rendah. Praktik ini hanya memberi pengguna izin minimum yang diperlukan dan menciptakan lingkungan produksi yang lebih aman.

Contoh berikut akan menetapkan peran Kontributor Data Blob Penyimpanan ke akun pengguna Anda, yang menyediakan akses baca dan tulis ke data blob di akun penyimpanan Anda.

Penting

Dalam kebanyakan kasus, dibutuhkan satu atau dua menit agar penetapan peran disebarluaskan di Azure, tetapi dalam kasus yang jarang terjadi mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

  1. Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Di halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.

    Cuplikan layar yang menampilkan cara menetapkan peran.

  5. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Kontributor Data Blob Penyimpanan dan pilih hasil yang cocok, lalu pilih Berikutnya.

  6. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

  7. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

  8. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Masuk dan sambungkan kode aplikasi Anda ke Azure menggunakan DefaultAzureCredential

Anda dapat mengotorisasi akses ke data di akun penyimpanan Anda menggunakan langkah-langkah berikut:

  1. 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

  2. Untuk menggunakan DefaultAzureCredential, tambahkan paket Azure.Identity ke aplikasi Anda.

    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.

      Cuplikan layar yang menunjukkan cara menambahkan paket identitas.

  3. Perbarui kode Program.cs Anda agar sesuai dengan contoh berikut. 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.

    using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using System;
using System.IO;
using Azure.Identity;

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

  4. Pastikan untuk memperbarui nama akun penyimpanan di URI BlobServiceClient Anda. Nama akun penyimpanan dapat ditemukan di halaman gambaran umum portal Azure.

    Cuplikan layar yang menampilkan cara menemukan nama akun penyimpanan.

    Catatan

    Saat disebarkan ke Azure, kode yang sama ini dapat digunakan untuk mengotorisasi permintaan ke Azure Storage dari aplikasi yang berjalan di Azure. Namun, Anda harus mengaktifkan identitas terkelola di aplikasi Anda di Azure. Kemudian konfigurasikan akun penyimpanan Anda untuk memungkinkan identitas terkelola tersebut tersambung. Untuk petunjuk detail tentang mengonfigurasi koneksi ini antara layanan Azure, lihat tutorial Auth dari aplikasi yang dihosting Azure.

Membuat kontainer

Buat kontainer baru di akun penyimpanan Anda dengan memanggil metode CreateBlobContainerAsync pada blobServiceClient objek. Dalam contoh ini, kode menambahkan nilai GUID ke nama kontainer untuk memastikan bahwa kode tersebut unik.

Tambahkan kode berikut ke akhir Program.cs file:

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

Untuk mempelajari selengkapnya tentang membuat kontainer, dan untuk menjelajahi lebih banyak sampel kode, lihat Membuat kontainer blob dengan .NET.

Penting

Nama kontainer harus menggunakan huruf kecil. Untuk informasi selengkapnya tentang penamaan kontainer dan blob, lihat Menamai dan Mereferensikan Kontainer, Blob, dan Metadata.

Mengunggah blob ke dalam kontainer

Unggah blob ke kontainer menggunakan UploadAsync. Kode contoh membuat file teks di direktori data lokal untuk diunggah ke kontainer.

Tambahkan kode berikut ke akhir Program.cs file:

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file, overwrite the blob if it already exists
await blobClient.UploadAsync(localFilePath, true);

Untuk mempelajari selengkapnya tentang mengunggah blob, dan untuk menjelajahi sampel kode lainnya, lihat Mengunggah blob dengan .NET.

Menampilkan blob dalam kontainer

Cantumkan blob dalam kontainer dengan memanggil metode GetBlobsAsync.

Tambahkan kode berikut ke akhir Program.cs file:

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

Untuk mempelajari selengkapnya tentang mencantumkan blob, dan untuk menjelajahi sampel kode lainnya, lihat Mencantumkan blob dengan .NET.

Mengunduh blob

Unduh blob yang kami buat sebelumnya dengan memanggil metode DownloadToAsync . Contoh kode menambahkan string "DOWNLOADED" ke nama file sehingga Anda dapat melihat kedua file dalam sistem file lokal.

Tambahkan kode berikut ke akhir Program.cs file:

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

Untuk mempelajari selengkapnya tentang mengunduh blob, dan untuk menjelajahi sampel kode lainnya, lihat Mengunduh blob dengan .NET.

Menghapus kontainer

Kode berikut membersihkan sumber daya yang dibuat aplikasi dengan menghapus kontainer menggunakan DeleteAsync. Contoh kode juga menghapus file lokal yang dibuat oleh aplikasi.

Aplikasi berhenti sejenak untuk input pengguna dengan memanggil Console.ReadLine sebelum menghapus blob, kontainer, dan file lokal. Ini adalah kesempatan yang baik untuk memverifikasi bahwa sumber daya dibuat dengan benar, sebelum dihapus.

Tambahkan kode berikut ke akhir Program.cs file:

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Untuk mempelajari selengkapnya tentang menghapus kontainer, dan untuk menjelajahi sampel kode lainnya, lihat Menghapus dan memulihkan kontainer blob dengan .NET.

Kode yang telah selesai

Setelah menyelesaikan langkah-langkah ini, kode dalam file Anda Program.cs sekarang akan menyerupai berikut ini:

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

// TODO: Replace <storage-account-name> with your actual storage account name
var blobServiceClient = new BlobServiceClient(
        new Uri("https://<storage-account-name>.blob.core.windows.net"),
        new DefaultAzureCredential());

//Create a unique name for the container
string containerName = "quickstartblobs" + Guid.NewGuid().ToString();

// Create the container and return a container client object
BlobContainerClient containerClient = await blobServiceClient.CreateBlobContainerAsync(containerName);

// Create a local file in the ./data/ directory for uploading and downloading
string localPath = "data";
Directory.CreateDirectory(localPath);
string fileName = "quickstart" + Guid.NewGuid().ToString() + ".txt";
string localFilePath = Path.Combine(localPath, fileName);

// Write text to the file
await File.WriteAllTextAsync(localFilePath, "Hello, World!");

// Get a reference to a blob
BlobClient blobClient = containerClient.GetBlobClient(fileName);

Console.WriteLine("Uploading to Blob storage as blob:\n\t {0}\n", blobClient.Uri);

// Upload data from the local file
await blobClient.UploadAsync(localFilePath, true);

Console.WriteLine("Listing blobs...");

// List all blobs in the container
await foreach (BlobItem blobItem in containerClient.GetBlobsAsync())
{
    Console.WriteLine("\t" + blobItem.Name);
}

// Download the blob to a local file
// Append the string "DOWNLOADED" before the .txt extension 
// so you can compare the files in the data directory
string downloadFilePath = localFilePath.Replace(".txt", "DOWNLOADED.txt");

Console.WriteLine("\nDownloading blob to\n\t{0}\n", downloadFilePath);

// Download the blob's contents and save it to a file
await blobClient.DownloadToAsync(downloadFilePath);

// Clean up
Console.Write("Press any key to begin clean up");
Console.ReadLine();

Console.WriteLine("Deleting blob container...");
await containerClient.DeleteAsync();

Console.WriteLine("Deleting the local source and downloaded files...");
File.Delete(localFilePath);
File.Delete(downloadFilePath);

Console.WriteLine("Done");

Menjalankan kode

Aplikasi ini membuat file uji di folder data lokal Anda dan mengunggahnya ke penyimpanan Blob. Contoh kemudian mencantumkan blob dalam kontainer dan mengunduh file dengan nama baru sehingga Anda dapat membandingkan file lama dan baru.

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

Output aplikasi mirip dengan contoh berikut (nilai GUID dihilangkan untuk keterbacaan):

Azure Blob Storage - .NET quickstart sample

Uploading to Blob storage as blob:
         https://mystorageacct.blob.core.windows.net/quickstartblobsGUID/quickstartGUID.txt

Listing blobs...
        quickstartGUID.txt

Downloading blob to
        ./data/quickstartGUIDDOWNLOADED.txt

Press any key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done

Sebelum Anda memulai proses pembersihan, periksa folder data Anda untuk dua file tersebut. Anda dapat membukanya dan mengamati bahwa keduanya identik.

Membersihkan sumber daya

Setelah Anda memverifikasi file dan menyelesaikan pengujian, tekan tombol Enter untuk menghapus file pengujian bersama dengan kontainer yang Anda buat di akun penyimpanan. Anda juga dapat menggunakan Azure CLI untuk menghapus sumber daya.

Setelah selesai dengan mulai cepat, Anda dapat membersihkan sumber daya yang Anda buat dengan menjalankan perintah berikut:

azd down

Anda akan diminta untuk mengonfirmasi penghapusan sumber daya. Masukkan y untuk mengonfirmasi.

Langkah selanjutnya

Sampel Azure Storage dan panduan pengembang untuk .NET