Bagikan melalui

Mulai cepat: Pustaka klien Azure Blob Storage untuk Node.js dengan TypeScript

Mulai menggunakan pustaka klien Azure Blob Storage untuk Node.js dengan TypeScript untuk mengelola blob dan kontainer.

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

Referensi API | Kode sumber pustaka | Paket (npm) | Sampel

Prasyarat

Persiapan

Bagian ini memancang Anda menyiapkan proyek untuk bekerja dengan pustaka klien Azure Blob Storage untuk Node.js.

Membuat proyek Node.js Anda

Buat aplikasi TypeScript bernama blob-quickstart.

  1. Di jendela konsol (seperti cmd, PowerShell, atau Bash), buat direktori baru untuk proyek:

    mkdir blob-quickstart

  2. Beralih ke direktori blob-quickstart yang baru dibuat:

    cd blob-quickstart

  3. Buat file package.json :

    npm init -y

  4. Buka proyek di Visual Studio Code:

    code .

  5. Edit file package.json untuk menambahkan properti berikut untuk mendukung ESM dengan TypeScript:

    "type": "module",

Menginstal paket

Dari direktori proyek, instal paket berikut menggunakan npm install perintah .

  1. Pasang paket npm Azure Storage:

    npm install @azure/storage-blob

  2. Instal dependensi lain yang digunakan dalam mulai cepat ini:

    npm install uuid dotenv @types/node @types/uuid

  3. Buat tsconfig.json file di direktori proyek dengan konten berikut.

    {
    "compilerOptions": {
      "target": "es2022",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
      "module": "ESNext",                                /* Specify what module code is generated. */
      "moduleResolution": "node",                     /* Specify how TypeScript looks up a file from a given module specifier. */
      "outDir": "dist",                                   /* Specify an output folder for all emitted files. */
      "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
      "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
      "strict": true,                                      /* Enable all strict type-checking options. */
      "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
    }
  }

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 di dalam kontainer

Diagram berikut menunjukkan hubungan antara ketiga sumber daya ini.

Diagram arsitektur Blob Storage.

Gunakan kelas JavaScript berikut untuk berinteraksi dengan sumber daya ini:

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

Contoh kode

Contoh cuplikan kode ini menunjukkan kepada Anda cara melakukan tugas berikut dengan pustaka klien Azure Blob Storage untuk JavaScript:

Kode sampel juga tersedia di GitHub.

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 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 info masuk Azure CLI Anda 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. Untuk informasi selengkapnya tentang peran Kontributor Data Blob Penyimpanan , lihat Kontributor Data Blob Penyimpanan. Untuk informasi selengkapnya tentang cakupan yang tersedia untuk penetapan peran, lihat Memahami cakupan untuk Azure RBAC.

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. Pastikan Anda diautentikasi dengan akun Microsoft Entra yang sama dengan yang Anda tetapkan perannya di akun penyimpanan Anda. Anda dapat mengautentikasi melalui Azure CLI, Visual Studio Code, atau Azure PowerShell.

    Masuk ke Azure melalui Azure CLI menggunakan perintah berikut:

    az login

  2. Untuk menggunakan DefaultAzureCredential, pastikan bahwa paket @azure\identity diinstal, dan kelas diimpor:

    import { DefaultAzureCredential } from '@azure/identity';

  3. Tambahkan kode ini di try dalam blok. Saat kode berjalan di stasiun kerja lokal Anda, DefaultAzureCredential menggunakan kredensial pengembang alat yang diprioritaskan yang Anda masuki untuk mengautentikasi ke Azure. Contoh alat ini termasuk Azure CLI atau Visual Studio Code.

    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
if (!accountName) throw Error('Azure Storage accountName not found');

// Add `Storage Blob Data Contributor` role assignment to the identity
const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);

  4. Pastikan untuk memperbarui nama akun penyimpanan, AZURE_STORAGE_ACCOUNT_NAME, dalam .env file atau variabel lingkungan 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. Contoh kode berikut mengambil objek BlobServiceClient dan memanggil metode getContainerClient untuk mendapatkan referensi ke kontainer. Kemudian, kode memanggil metode buat untuk benar-benar membuat kontainer di akun penyimpanan Anda.

Tambahkan kode ini ke akhir blok try:

  const containerName = 'quickstart' + uuidv4();

  console.log('\nCreating container...');
  console.log('\t', containerName);

  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse: ContainerCreateResponse = await containerClient.create();
  console.log(
    `Container was created successfully.\n\trequestId:${createContainerResponse.requestId}\n\tURL: ${containerClient.url}`
  );

Untuk mempelajari selengkapnya tentang membuat kontainer, dan untuk menjelajahi sampel kode lainnya, lihat Membuat kontainer blob dengan JavaScript.

Penting

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

Unggah blob ke kontainer

Unggah blob ke kontainer. Kode berikut mendapatkan referensi ke objek BlockBlobClient dengan memanggil metode getBlockBlobClient pada ContainerClient dari bagian Buat kontainer.

Mengunggah data string teks ke blob dengan memanggil metode unggahan.

Tambahkan kode ini ke akhir blok try:

  const blobName = 'quickstart' + uuidv4(); + '.txt';
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  console.log(
    `\nUploading to Azure storage as blob\n\tname: ${blobName}:\n\tURL: ${blockBlobClient.url}`
  );

  const data = 'Hello, World!';
  const uploadBlobResponse: BlockBlobUploadResponse = await blockBlobClient.upload(data, data.length);
  console.log(
    `Blob was uploaded successfully. requestId: ${uploadBlobResponse.requestId}`
  );

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

Cantumkan blob di kontainer

Cantumkan blob dalam kontainer. Kode berikut memanggil metode listBlobsFlat . Dalam hal ini, hanya satu blob yang ada dalam kontainer, sehingga operasi pencantuman mengembalikan hanya satu blob.

Tambahkan kode ini ke akhir blok try:

  console.log('\nListing blobs...');

  for await (const blob of containerClient.listBlobsFlat()) {
    const tempBlockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blob.name);

    console.log(
      `\n\tname: ${blob.name}\n\tURL: ${tempBlockBlobClient.url}\n`
    );
  }

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

Unduh blob

Unduh blob dan tampilkan kontennya. Kode berikut memanggil metode unduh untuk mengunduh blob.

Tambahkan kode ini ke akhir blok try:

  const offset = 0;         // start at beginning
  const length = undefined; // read all

  const downloadBlockBlobResponse: BlobDownloadResponseParsed = await blockBlobClient.download(offset, length);
  console.log('\nDownloaded blob content...');
  console.log(
    '\t',
    await streamToText(downloadBlockBlobResponse.readableStreamBody as NodeJS.ReadableStream)
  );

Kode berikut mengonversi aliran kembali menjadi string untuk menampilkan konten.

Tambahkan kode ini setelahmain fungsi:

// Convert stream to text
async function streamToText(readable: NodeJS.ReadableStream): Promise<string> {
  readable.setEncoding('utf8');
  let data = '';
  for await (const chunk of readable) {
    data += chunk;
  }
  return data;
}

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

Menghapus kontainer

Hapus kontainer dan semua blob dalam kontainer. Kode berikut membersihkan sumber daya yang dibuat oleh aplikasi dengan menghapus seluruh kontainer menggunakan metode hapus .

Tambahkan kode ini ke akhir blok try:

  console.log('\nDeleting container...');

  const deleteContainerResponse: ContainerDeleteResponse = await containerClient.delete();
  console.log(
    'Container was deleted successfully. requestId: ',
    deleteContainerResponse.requestId
  );

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

Menjalankan kode

  1. Dari terminal Visual Studio Code, buat aplikasi.

    tsc

  2. Jalankan aplikasi.

    node dist/index.js

  3. Output aplikasi mirip dengan contoh berikut:

    Azure Blob storage - JavaScript quickstart sample

Creating container...
    quickstart4a0780c0-fb72-11e9-b7b9-b387d3c488da

Uploading to Azure Storage as blob:
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Listing blobs...
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Downloaded blob content...
    Hello, World!

Deleting container...
Done

Telusuri kode di debugger Anda dan periksa portal Microsoft Azure Anda sepanjang proses. Periksa untuk memastikan bahwa kontainer sedang dibuat. Anda dapat membuka blob di dalam kontainer dan melihat isinya.

Membersihkan sumber daya

  1. Setelah selesai dengan mulai cepat ini, hapus blob-quickstart direktori.
  2. Jika Anda selesai menggunakan sumber daya Azure Storage Anda, gunakan Azure CLI untuk menghapus sumber daya Storage.

Langkah selanjutnya

Sampel Azure Storage dan panduan pengembang untuk JavaScript dan TypeScript

  • Last updated on