Bagikan melalui

Pustaka klien Azure Storage Blob untuk JavaScript - versi 12.24.0

  • Artikel

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
  • Membuat/Mencantumkan/Menghapus Kontainer
  • Buat/Baca/Daftar/Perbarui/Hapus Blob Blok
  • Buat/Baca/Daftar/Perbarui/Hapus Blob Halaman
  • Buat/Baca/Daftar/Perbarui/Hapus Tambahkan Blob

Tautan kunci

Persiapan

Lingkungan yang saat ini didukung

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

  • langganan Azure
  • Akun Penyimpanan

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

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.

Kompatibilitas

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 digunakan melalui BlobServiceClient
  • Kontainer di akun penyimpanan yang digunakan melalui ContainerClient
  • blob dalam kontainer yang digunakan melalui

Contoh

Impor paket

Untuk menggunakan klien, impor paket ke dalam file Anda:

const AzureStorageBlob = require("@azure/storage-blob");

Atau, secara selektif hanya mengimpor jenis yang Anda butuhkan:

const { BlobServiceClient, StorageSharedKeyCredential } = require("@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 - /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) - /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 - /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).
const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@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]

const { BlobServiceClient } = require("@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]

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

// Enter your storage account name and shared key
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().

const { BlobServiceClient } = require("@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.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  // 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);
}

main();

Mencantumkan kontainer

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

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

Atau tanpa menggunakan for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

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

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

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

main();

Untuk sampel lengkap tentang kontainer iterasi, lihat sampel/v12/typescript/src/listContainers.ts.

Membuat blob dengan mengunggah data

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

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

main();

Mencantumkan blob di dalam kontainer

Mirip dengan mencantumkan kontainer.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

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

main();

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

Mengunduh blob dan mengonversinya menjadi string (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";
const blobName = "<blob name>";

async function main() {
  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();
  const downloaded = (
    await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
  ).toString();
  console.log("Downloaded blob content:", downloaded);

  // [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
  async function streamToBuffer(readableStream) {
    return new Promise((resolve, reject) => {
      const chunks = [];
      readableStream.on("data", (data) => {
        chunks.push(data instanceof Buffer ? data : Buffer.from(data));
      });
      readableStream.on("end", () => {
        resolve(Buffer.concat(chunks));
      });
      readableStream.on("error", reject);
    });
  }
}

main();

Unduh blob dan konversikan ke string (Browser).

Silakan merujuk ke bagian Bundel JavaScript untuk informasi selengkapnya tentang penggunaan pustaka ini di browser.

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";

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

async function main() {
  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 downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
  console.log("Downloaded blob content", downloaded);

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob) {
    const fileReader = new FileReader();
    return new Promise((resolve, reject) => {
      fileReader.onloadend = (ev) => {
        resolve(ev.target.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

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

Pemecahan masalah

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:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Langkah berikutnya

Sampel kode lainnya:

Berkontribusi

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.

Tayangan