Mulai cepat: Pustaka klien penyimpanan Azure Blob v11 untuk .NET

Mulai menggunakan pustaka klien Azure Blob Storage v11 untuk .NET. Azure Blob Storage adalah solusi penyimpanan objek Microsoft untuk cloud. Ikuti langkah-langkah untuk menginstal paket dan cobalah contoh kode untuk tugas dasar. Penyimpanan blob dioptimalkan untuk menyimpan data tidak terstruktur dalam jumlah besar.

Catatan

Panduan mulai cepat ini menggunakan versi lama dari pustaka klien penyimpanan Azure Blob. Untuk mulai menggunakan versi terbaru, lihat Mulai Cepat: Pustaka klien penyimpanan Azure Blob v12 untuk .NET.

Gunakan pustaka klien Azure Blob Storage v12 untuk .NET untuk:

  • Membuat kontainer
  • Mengatur izin pada kontainer
  • Membuat blob di Azure Storage
  • Mengunduh blob ke komputer lokal Anda
  • Mencantumkan semua blob dalam kontainer
  • Menghapus kontainer

Sumber daya tambahan:

Prasyarat

Persiapan

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

Buat proyek

Pertama, buat aplikasi .NET Core bernama blob-quickstart.

  1. Di jendela konsol (seperti cmd, PowerShell, atau Bash), gunakan perintah dotnet new untuk membuat aplikasi konsol baru bernama blob-quickstart. Perintah ini membuat proyek C# "Halo Dunia" sederhana dengan satu file sumber: Program.cs.

    dotnet new console -n blob-quickstart
    
  2. Beralihlah ke folder blob-quickstart yang baru dibuat dan bangun aplikasi untuk memastikan semua berjalan dengan baik.

    cd blob-quickstart
    
    dotnet build
    

Output yang diharapkan dari build akan terlihat seperti ini:

C:\QuickStarts\blob-quickstart> dotnet build
Microsoft (R) Build Engine version 16.0.450+ga8dc7f1d34 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 44.31 ms for C:\QuickStarts\blob-quickstart\blob-quickstart.csproj.
  blob-quickstart -> C:\QuickStarts\blob-quickstart\bin\Debug\netcoreapp2.1\blob-quickstart.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:03.08

Instal paketnya

Saat masih dalam direktori aplikasi, instal pustaka klien Azure Blob Storage untuk paket .NET dengan menggunakan perintah dotnet add package.

dotnet add package Microsoft.Azure.Storage.Blob

Siapkan kerangka kerja aplikasi

Dari direktori proyek:

  1. Buka file Program.cs di editor Anda
  2. Hapus pernyataan Console.WriteLine
  3. Tambahkan direktif using
  4. Buat metode ProcessAsync sebagai tempat kode utama untuk contoh
  5. Panggil ProcessAsync metode dari Main secara asinkron

Berikut kodenya:

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.Azure.Storage;
using Microsoft.Azure.Storage.Blob;

namespace blob_quickstart
{
    class Program
    {
        public static async Task Main()
        {
            Console.WriteLine("Azure Blob Storage - .NET quickstart sample\n");

            await ProcessAsync();

            Console.WriteLine("Press any key to exit the sample application.");
            Console.ReadLine();
        }

        private static async Task ProcessAsync()
        {
        }
    }
}

Salin kredensial Anda dari portal Microsoft Azure

Saat aplikasi contoh membuat permintaan ke Azure Storage, aplikasi contoh harus diotorisasi. Untuk mengotorisasi permintaan, tambahkan kredensial akun penyimpanan Anda ke aplikasi sebagai string koneksi. Lihat kredensial akun penyimpanan Anda dengan mengikuti langkah-langkah berikut:

  1. Navigasikan ke portal Microsoft Azure.

  2. Temukan akun penyimpanan Anda.

  3. Di bagian Pengaturan dari ringkasan akun penyimpanan, pilih Kunci akses. Kunci akses akun Anda muncul, serta string koneksi lengkap untuk setiap kunci.

  4. Temukan nilai String koneksi di bawah key1, dan pilih tombol Salin untuk menyalin string koneksi. Anda akan menambah nilai string koneksi ke variabel lingkungan di langkah berikutnya.

    Cuplikan layar memperlihatkan cara menyalin string koneksi dari portal Microsoft Azure

Konfigurasikan string koneksi penyimpanan Anda

Setelah Anda menyalin string koneksi Anda, tuliskan ke variabel lingkungan baru di komputer lokal yang menjalankan aplikasi. Untuk mengatur variabel lingkungan, buka jendela konsol, dan ikuti petunjuk untuk sistem operasi Anda. Ganti <yourconnectionstring> dengan string koneksi aktual Anda.

Windows

setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"

Setelah menambahkan variabel lingkungan di Windows, Anda harus memulai instans baru dari jendela perintah.

Linux

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

MacOS

export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"

Setelah Anda menambah variabel lingkungan, mulai ulang program berjalan yang perlu membaca variabel lingkungan. Misalnya, mulai ulang lingkungan atau editor pengembangan Anda sebelum melanjutkan.

Model objek

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

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

Diagram berikut menunjukkan hubungan antara ketiga sumber daya ini.

Diagram arsitektur penyimpanan Blob

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

  • CloudStorageAccount: Kelas CloudStorageAccount mewakili akun penyimpanan Azure Anda. Gunakan kelas ini untuk mengotorisasi akses ke penyimpanan Blob menggunakan kunci akses akun Anda.
  • CloudBlobClient: Kelas CloudBlobClient menyediakan titik akses ke Blob service dalam kode Anda.
  • CloudBlobContainer: Kelas CloudBlobContainer mewakili kontainer blob dalam kode Anda.
  • CloudBlockBlob: Objek CloudBlockBlob mewakili blob balok dalam kode Anda. Blob balok terdiri dari balok data yang dapat dikelola sendiri-sendiri.

Contoh kode

Contoh cuplikan kode ini menunjukkan cara melakukan tugas berikut dengan pustaka klien Azure Blob Storage untuk .NET:

Autentikasi klien

Kode berikut memeriksa bahwa variabel lingkungan berisi string koneksi yang dapat dipilah untuk membuat objek CloudStorageAccount yang menunjuk ke akun penyimpanan. Untuk memeriksa apakah string koneksinya valid, gunakan metode TryParse. Jika TryParse berhasil, sampel menginisialisasi storageAccount variabel dan mengembalikan true.

Tambahkan kode ini ke dalam metode ProcessAsync:

// Retrieve the connection string for use with the application. The storage 
// connection string is stored in an environment variable on the machine 
// running the application called AZURE_STORAGE_CONNECTION_STRING. If the 
// environment variable is created after the application is launched in a 
// console or with Visual Studio, the shell or application needs to be closed
// and reloaded to take the environment variable into account.
string storageConnectionString = Environment.GetEnvironmentVariable("AZURE_STORAGE_CONNECTION_STRING");

// Check whether the connection string can be parsed.
CloudStorageAccount storageAccount;
if (CloudStorageAccount.TryParse(storageConnectionString, out storageAccount))
{
    // If the connection string is valid, proceed with operations against Blob
    // storage here.
    // ADD OTHER OPERATIONS HERE
}
else
{
    // Otherwise, let the user know that they need to define the environment variable.
    Console.WriteLine(
        "A connection string has not been defined in the system environment variables. " +
        "Add an environment variable named 'AZURE_STORAGE_CONNECTION_STRING' with your storage " +
        "connection string as a value.");
    Console.WriteLine("Press any key to exit the application.");
    Console.ReadLine();
}

Catatan

Untuk melakukan sisa operasi di artikel ini, ganti kode // ADD OTHER OPERATIONS HERE di atas dengan cuplikan kode di bagian berikut.

Membuat kontainer

Untuk membuat kontainer, pertama-tama buat instans objek CloudBlobClient, yang menunjuk ke penyimpanan Blob di akun penyimpanan Anda. Selanjutnya, buat objek CloudBlobContainer, lalu buat kontainernya.

Dalam hal ini, kode memanggil metode CreateAsync untuk membuat kontainer. Nilai GUID ditambahkan ke nama kontainer untuk memastikan bahwa kode tersebut unik. Dalam lingkungan produksi, seringkali lebih baik menggunakan metode CreateIfNotExistsAsync untuk membuat kontainer jika belum ada.

Penting

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

// Create the CloudBlobClient that represents the 
// Blob storage endpoint for the storage account.
CloudBlobClient cloudBlobClient = storageAccount.CreateCloudBlobClient();

// Create a container called 'quickstartblobs' and 
// append a GUID value to it to make the name unique.
CloudBlobContainer cloudBlobContainer = 
    cloudBlobClient.GetContainerReference("quickstartblobs" + 
        Guid.NewGuid().ToString());
await cloudBlobContainer.CreateAsync();

Mengatur izin pada kontainer

Atur izin pada kontainer sehingga setiap blob dalam kontainer bersifat publik. Jika blob bersifat publik, itu dapat diakses secara anonim oleh klien mana pun.

// Set the permissions so the blobs are public.
BlobContainerPermissions permissions = new BlobContainerPermissions
{
    PublicAccess = BlobContainerPublicAccessType.Blob
};
await cloudBlobContainer.SetPermissionsAsync(permissions);

Unggah blob ke kontainer

Cuplikan kode berikut dirujuk ke CloudBlockBlob objek dengan memanggil metode GetBlockBlobReference pada kontainer yang dibuat di bagian sebelumnya. Lalu mengunggah file lokal yang dipilih ke blob dengan memanggil metode UploadFromFileAsync. Metode ini membuat blob jika belum ada, dan menimpanya jika ada blob.

// Create a file in your local MyDocuments folder to upload to a blob.
string localPath = Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments);
string localFileName = "QuickStart_" + Guid.NewGuid().ToString() + ".txt";
string sourceFile = Path.Combine(localPath, localFileName);
// Write text to the file.
File.WriteAllText(sourceFile, "Hello, World!");

Console.WriteLine("Temp file = {0}", sourceFile);
Console.WriteLine("Uploading to Blob storage as blob '{0}'", localFileName);

// Get a reference to the blob address, then upload the file to the blob.
// Use the value of localFileName for the blob name.
CloudBlockBlob cloudBlockBlob = cloudBlobContainer.GetBlockBlobReference(localFileName);
await cloudBlockBlob.UploadFromFileAsync(sourceFile);

Cantumkan blob di kontainer

Cantumkan blob dalam kontainer dengan menggunakan metode ListBlobsSegmentedAsync. Dalam kasus ini, hanya satu blob yang telah ditambahkan ke kontainer, sehingga operasi pencantuman hanya mengembalikan satu blob itu.

Jika ada terlalu banyak blob yang dikembalikan dalam satu panggilan (secara default, lebih dari 5000), maka metode ListBlobsSegmentedAsync mengembalikan segmen dari total hasil yang ditetapkan dan token kelanjutan. Untuk mengambil segmen blob berikutnya, sediakan token kelanjutan yang dikembalikan oleh panggilan sebelumnya, dan selanjutnya, sampai token kelanjutannya null. Token kelanjutan null menunjukkan bahwa semua blob telah diambil. Kodenya menunjukkan cara menggunakan token kelanjutan demi praktik terbaik.

// List the blobs in the container.
Console.WriteLine("List blobs in container.");
BlobContinuationToken blobContinuationToken = null;
do
{
    var results = await cloudBlobContainer.ListBlobsSegmentedAsync(null, blobContinuationToken);
    // Get the value of the continuation token returned by the listing call.
    blobContinuationToken = results.ContinuationToken;
    foreach (IListBlobItem item in results.Results)
    {
        Console.WriteLine(item.Uri);
    }
} while (blobContinuationToken != null); // Loop while the continuation token is not null.

Unduh blob

Unduh blob yang dibuat sebelumnya ke sistem file lokal Anda dengan menggunakan metode DownloadToFileAsync. Contoh kode menambahkan akhiran "_DOWNLOADED" ke nama file sehingga Anda dapat melihat kedua file dalam sistem file lokal.

// Download the blob to a local file, using the reference created earlier.
// Append the string "_DOWNLOADED" before the .txt extension so that you 
// can see both files in MyDocuments.
string destinationFile = sourceFile.Replace(".txt", "_DOWNLOADED.txt");
Console.WriteLine("Downloading blob to {0}", destinationFile);
await cloudBlockBlob.DownloadToFileAsync(destinationFile, FileMode.Create);

Menghapus kontainer

Kode berikut membersihkan sumber daya yang dibuat aplikasi dengan menghapus seluruh kontainer menggunakan CloudBlobContainer.DeleteAsync. Anda juga bisa menghapus file lokal jika ingin.

Console.WriteLine("Press the 'Enter' key to delete the example files, " +
    "example container, and exit the application.");
Console.ReadLine();
// Clean up resources. This includes the container and the two temp files.
Console.WriteLine("Deleting the container");
if (cloudBlobContainer != null)
{
    await cloudBlobContainer.DeleteIfExistsAsync();
}
Console.WriteLine("Deleting the source, and downloaded files");
File.Delete(sourceFile);
File.Delete(destinationFile);

Jalankan kode

Aplikasi ini membuat file uji di folder MyDocuments 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.

Navigasikan ke direktori aplikasi, lalu buat dan jalankan aplikasi.

dotnet build
dotnet run

Output aplikasi mirip dengan contoh berikut:

Azure Blob storage - .NET Quickstart example

Created container 'quickstartblobs33c90d2a-eabd-4236-958b-5cc5949e731f'

Temp file = C:\Users\myusername\Documents\QuickStart_c5e7f24f-a7f8-4926-a9da-96
97c748f4db.txt
Uploading to Blob storage as blob 'QuickStart_c5e7f24f-a7f8-4926-a9da-9697c748f
4db.txt'

Listing blobs in container.
https://storagesamples.blob.core.windows.net/quickstartblobs33c90d2a-eabd-4236-
958b-5cc5949e731f/QuickStart_c5e7f24f-a7f8-4926-a9da-9697c748f4db.txt

Downloading blob to C:\Users\myusername\Documents\QuickStart_c5e7f24f-a7f8-4926
-a9da-9697c748f4db_DOWNLOADED.txt

Press any key to delete the example files and example container.

Saat Anda menekan tombol Enter, aplikasi akan menghapus kontainer penyimpanan dan file. Sebelum menghapusnya, periksa folder MyDocuments Anda untuk kedua file tersebut. Anda dapat membukanya dan mengamati bahwa keduanya identik. Salin URL blob dari jendela konsol dan tempelkan ke browser untuk melihat konten blob.

Setelah memverifikasi file, tekan tombol apa saja untuk menyelesaikan demo dan menghapus file uji.

Langkah berikutnya

Di mulai cepat ini, Anda belajar cara mengunggah, mengunduh, dan mencantumkan blob menggunakan .NET.

Untuk mempelajari cara membuat aplikasi web yang mengunggah gambar ke penyimpanan Blob, lanjutkan ke: