Pustaka klien Azure Storage Blob untuk JavaScript - versi 12.29.1

Azure Storage Blob adalah solusi penyimpanan objek Microsoft untuk cloud. Penyimpanan blob dioptimalkan untuk menyimpan sejumlah besar data yang tidak terstruktur. Data yang tidak terstruktur adalah data yang tidak mematuhi model atau definisi data tertentu, seperti teks atau data biner.

Proyek ini menyediakan pustaka klien di JavaScript yang memudahkan penggunaan layanan Microsoft Azure Storage Blob.

Gunakan pustaka klien dalam paket ini untuk:

Mendapatkan/Mengatur Properti Blob Service
Buat/Daftarkan/Hapus Kontainer
Buat/Baca/Daftar/Perbarui/Hapus Blob Blok
Buat/Baca/Daftar/Perbarui/Hapus Blob Halaman
Buat/Baca/Daftar/Perbarui/Hapus Tambahkan Blob

Tautan utama

Kode sumber
Paket (npm)
Dokumentasi Referensi API
dokumentasi produk
Samples
AZURE Storage Blob REST API

Memulai Langkah Pertama

Lingkungan yang saat ini didukung

versi LTS Node.js
Versi terbaru Safari, Chrome, Edge, dan Firefox.

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prerequisites

Menginstal paket

Cara yang disukai untuk menginstal pustaka klien Azure Storage Blob untuk JavaScript adalah dengan menggunakan manajer paket npm. Ketik berikut ini ke dalam jendela terminal:

npm install @azure/storage-blob

Mengautentikasi klien

Azure Storage mendukung beberapa cara untuk mengautentikasi. Untuk berinteraksi dengan layanan Azure Blob Storage, Anda harus membuat instans klien Storage - BlobServiceClient, ContainerClient, atau BlobClient misalnya. Lihat sampel untuk membuat BlobServiceClient untuk mempelajari selengkapnya tentang autentikasi.

Azure Active Directory
Kunci Bersama
Tanda tangan akses bersama

Azure Active Directory

Layanan Azure Blob Storage mendukung penggunaan Azure Active Directory untuk mengautentikasi permintaan ke API-nya. Paket @azure/identity menyediakan berbagai jenis kredensial yang dapat digunakan aplikasi Anda untuk melakukan ini. Silakan lihat README untuk @azure/identity untuk detail dan sampel selengkapnya untuk memulai.

Compatibility

Pustaka ini kompatibel dengan Node.js dan browser, dan divalidasi terhadap versi Node.js LTS (>=8.16.0) dan versi terbaru Chrome, Firefox, dan Edge.

Pekerja Web

Pustaka ini mengharuskan objek DOM tertentu tersedia secara global ketika digunakan di browser, yang tidak tersedia oleh pekerja web secara default. Anda perlu melakukan polifill ini untuk membuat pustaka ini berfungsi di pekerja web.

Untuk informasi selengkapnya, lihat dokumentasi kami untuk menggunakan Azure SDK untuk JS di Pekerja Web

Pustaka ini bergantung pada API DOM berikut yang memerlukan polifill eksternal yang dimuat saat digunakan dalam pekerja web:

Perbedaan antara Node.js dan browser

Ada perbedaan antara runtime Node.js dan browser. Saat memulai pustaka ini, perhatikan API atau kelas yang ditandai dengan "HANYA TERSEDIA DI NODE.JS RUNTIME" atau "HANYA TERSEDIA DI BROWSER".

Jika blob menyimpan data terkompresi dalam format gzip atau deflate dan pengodean kontennya diatur, perilaku pengunduhan berbeda antara Node.js dan browser. Dalam Node.js klien penyimpanan akan mengunduh blob dalam format terkompresinya, sementara di browser data akan diunduh dalam format dekompresi.

Fitur, antarmuka, kelas, atau fungsi hanya tersedia di Node.js

Otorisasi Kunci Bersama berdasarkan nama akun dan kunci akun
- StorageSharedKeyCredential
Pembuatan Tanda Tangan Akses Bersama (SAS)
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Pengunggahan dan pengunduhan paralel. Perhatikan bahwa BlockBlobClient.uploadData() tersedia di Node.js dan browser.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Fitur, antarmuka, kelas, atau fungsi hanya tersedia di browser

Pengunggahan dan pengunduhan paralel
- BlockBlobClient.uploadBrowserData()

Bundel JavaScript

Untuk menggunakan pustaka klien ini di browser, pertama-tama Anda perlu menggunakan bunder. Untuk detail tentang cara melakukan ini, silakan lihat dokumentasi bundling kami.

CORS

Anda perlu menyiapkan aturan Berbagi Sumber Daya Lintas Asal (CORS) untuk akun penyimpanan Anda jika Anda perlu mengembangkan browser. Buka portal Microsoft Azure dan Azure Storage Explorer, temukan akun penyimpanan Anda, buat aturan CORS baru untuk layanan blob/antrean/file/tabel.

Misalnya, Anda dapat membuat pengaturan CORS berikut untuk penelusuran kesalahan. Tetapi silakan sesuaikan pengaturan dengan hati-hati sesuai dengan kebutuhan Anda di lingkungan produksi.

Asal yang diizinkan: *
Kata kerja yang diizinkan: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Header yang diizinkan: *
Header yang diekspos: *
Usia maksimum (detik): 86400

Konsep utama

Penyimpanan blob dirancang untuk:

Menyajikan gambar atau dokumen langsung ke browser.
Menyimpan file untuk akses terdistribusi.
Streaming video dan audio.
Menulis ke file log.
Menyimpan data untuk pencadangan dan pemulihan, pemulihan bencana, dan pengarsipan.
Menyimpan data untuk analisis oleh layanan lokal atau yang dihosting Azure.

Penyimpanan blob menawarkan tiga jenis sumber daya:

Akun penyimpanan yang digunakan melaluiBlobServiceClient
Kontainer di akun penyimpanan yang digunakan melaluiContainerClient
Gumpalan dalam kontainer yang digunakan melaluiBlobClient

Examples

Impor paket
Membuat klien layanan blob
Membuat kontainer baru
Mencantumkan kontainer
Membuat blob dengan mengunggah data
Mencantumkan blob di dalam kontainer
Mengunduh blob dan mengonversinya menjadi string (Node.js)
Unduh blob dan konversikan ke string (Browser)

Impor paket

Untuk menggunakan klien, impor paket ke dalam file Anda:

import * as AzureStorageBlob from "@azure/storage-blob";

Atau, secara selektif hanya mengimpor jenis yang Anda butuhkan:

import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";

Membuat klien layanan blob

BlobServiceClient memerlukan URL ke layanan blob dan kredensial akses. Ini juga secara opsional menerima beberapa pengaturan dalam parameter options.

dengan `DefaultAzureCredential` dari paket `@azure/identity`

Cara yang direkomendasikan untuk membuat instans BlobServiceClient

Penyiapan: Referensi - Mengotorisasi akses ke blob dan antrean dengan Azure Active Directory dari aplikasi klien - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-app

Daftarkan aplikasi AAD baru dan berikan izin untuk mengakses Azure Storage atas nama pengguna yang masuk
- Mendaftarkan aplikasi baru di Azure Active Directory (di azure-portal) - https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app
- Di bagian API permissions, pilih Add a permission dan pilih Microsoft APIs.
- Pilih Azure Storage dan pilih kotak centang di samping user_impersonation lalu klik Add permissions. Ini akan memungkinkan aplikasi untuk mengakses Azure Storage atas nama pengguna yang masuk.
Memberikan akses ke data Azure Blob dengan RBAC di Portal Microsoft Azure
- Peran RBAC untuk blob dan antrean - https://learn.microsoft.com/azure/storage/common/storage-auth-aad-rbac-portal.
- Di portal microsoft Azure, buka akun penyimpanan Anda dan tetapkan peran Kontributor Data Blob Penyimpanan ke aplikasi AAD terdaftar dari tab Access control (IAM) (di bilah navigasi sisi kiri akun penyimpanan Anda di azure-portal).
Penyiapan lingkungan untuk sampel
- Dari halaman gambaran umum Aplikasi AAD Anda, catat CLIENT ID dan TENANT ID. Di tab "Sertifikat & Rahasia", buat rahasia dan catat itu.
- Pastikan Anda memiliki AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET sebagai variabel lingkungan untuk berhasil menjalankan sampel (Dapat memanfaatkan process.env).

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  defaultAzureCredential,
);

Lihat contoh Azure AD Auth untuk contoh lengkap menggunakan metode ini.

[Catatan - Langkah-langkah di atas hanya untuk Node.js]

menggunakan string koneksi

Atau, Anda dapat membuat instans BlobServiceClient menggunakan metode statis fromConnectionString() dengan string koneksi lengkap sebagai argumen. (String koneksi dapat diperoleh dari portal microsoft Azure.) [HANYA TERSEDIA DALAM RUNTIME NODE.JS]

import { BlobServiceClient } from "@azure/storage-blob";

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

dengan `StorageSharedKeyCredential`

Atau, Anda membuat instans BlobServiceClient dengan StorageSharedKeyCredential dengan meneruskan nama akun dan kunci akun sebagai argumen. (Nama akun dan kunci akun dapat diperoleh dari portal microsoft Azure.) [HANYA TERSEDIA DALAM RUNTIME NODE.JS]

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential,
);

dengan Token SAS

Selain itu, Anda dapat membuat instans BlobServiceClient dengan tanda tangan akses bersama (SAS). Anda bisa mendapatkan token SAS dari Portal Microsoft Azure atau membuatnya menggunakan generateAccountSASQueryParameters().

import { BlobServiceClient } from "@azure/storage-blob";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const blobServiceClient = new BlobServiceClient(`https://${account}.blob.core.windows.net?${sas}`);

Membuat kontainer baru

Gunakan BlobServiceClient.getContainerClient() untuk mendapatkan instans klien kontainer lalu buat sumber daya kontainer baru.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

// Create a container
const containerName = `newcontainer${new Date().getTime()}`;
const containerClient = blobServiceClient.getContainerClient(containerName);
const createContainerResponse = await containerClient.create();
console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);

Mencantumkan kontainer

Gunakan fungsi BlobServiceClient.listContainers() untuk mengulangi kontainer, dengan sintaks for-await-of baru:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const containers = blobServiceClient.listContainers();
for await (const container of containers) {
  console.log(`Container ${i++}: ${container.name}`);
}

Atau tanpa menggunakan for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const iter = blobServiceClient.listContainers();
let { value, done } = await iter.next();
while (!done) {
  console.log(`Container ${i++}: ${value.name}`);
  ({ value, done } = await iter.next());
}

Selain itu, penomoran halaman juga didukung untuk pencantuman melalui byPage():

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const page of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
  for (const container of page.containerItems) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

Untuk sampel lengkap tentang wadah iterasi, silakan lihat samples/v12/typescript/src/listContainers.ts.

Membuat blob dengan mengunggah data

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

const content = "Hello world!";
const blobName = `newblob ${+new Date()}`;
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(
  `Upload block blob ${blobName} successfully with request ID: ${uploadBlobResponse.requestId}`,
);

Mencantumkan blob di dalam kontainer

Mirip dengan mencantumkan kontainer.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

let i = 1;
const blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

Untuk sampel lengkap tentang iterasi blob, silakan lihat samples/v12/typescript/src/listBlobsFlat.ts.

Mengunduh blob dan mengonversinya menjadi string (Node.js)

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);

// Get blob content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
const downloadBlockBlobResponse = await blobClient.download();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

Unduh blob dan konversikan ke string (Browser).

Silakan lihat bagian Bundel JavaScript untuk informasi lebih lanjut tentang penggunaan pustaka ini di browser.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
const containerClient = blobServiceClient.getContainerClient(containerName);
const blobClient = containerClient.getBlobClient(blobName);

// Get blob content from position 0 to the end
// In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
const downloadBlockBlobResponse = await blobClient.download();
const blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

Contoh lengkap skenario sederhana ada di samples/v12/typescript/src/sharedKeyAuth.ts.

Troubleshooting

Mengaktifkan pengelogan dapat membantu mengungkap informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Langkah selanjutnya

Sampel kode lainnya:

Blob Storage Samples (JavaScript)
Sampel Penyimpanan Blob (TypeScript)
Kasus Pengujian Blob Storage

Contributing

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

Lihat juga panduan khusus Storage untuk informasi tambahan tentang menyiapkan lingkungan pengujian untuk pustaka penyimpanan.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-17