Pustaka klien Azure Storage Blob untuk JavaScript - versi 12.18.0

Artikel
05/13/2024

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 data atau definisi tertentu, seperti teks atau data biner.

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

Gunakan pustaka klien dalam paket ini untuk:

Dapatkan/Atur Properti Blob Service
Create/Daftar/Hapus Kontainer
Create/Baca/Daftar/Perbarui/Hapus Blob Blok
Create/Baca/Daftar/Perbarui/Hapus Blob Halaman
Create/Baca/Daftar/Perbarui/Hapus Blob Tambahan

Tautan kunci

Memulai

Lingkungan yang didukung saat ini

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

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

Instal paketnya

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 Penyimpanan - BlobServiceClient, , ContainerClientatau 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 ini @azure/identity menyediakan berbagai jenis kredensial yang dapat digunakan aplikasi Anda untuk melakukan ini. Silakan lihat README untuk @azure/identity detail lebih lanjut dan sampel untuk memulai.

Kompatibilitas

Pustaka ini kompatibel dengan Node.js dan browser, dan divalidasi terhadap versi LTS Node.js (>=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, pekerja web mana yang tidak tersedia 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 gzip format atau deflate dan pengodean kontennya diatur sesuai, 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 de-terkompresi.

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 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 harap 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 diperbolehkan: *
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
Blob dalam kontainer yang digunakan melaluiBlobClient

Contoh

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

Mengimpor 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 options parameter .

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

Cara yang disarankan 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 Access control (IAM) tab (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 bahwa tidak berfungsi.
- 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 sampel 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 fromConnectionString() metode statis dengan string koneksi lengkap sebagai argumen . (String koneksi dapat diperoleh dari portal microsoft Azure.) [HANYA TERSEDIA DI 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 meneruskan nama akun dan kunci akun sebagai argumen. (Nama akun dan kunci akun dapat diperoleh dari portal microsoft Azure.) [HANYA TERSEDIA DI 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 BlobServiceClient.listContainers() fungsi untuk mengulangi kontainer, dengan sintaks baru 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 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 daftar 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, silakan lihat samples/v12/typescript/src/listContainers.ts.

Create 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, silakan lihat samples/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 lihat bagian Bundel JavaScript untuk informasi lebih lanjut 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 menemukan 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 penyimpanan untuk informasi tambahan tentang menyiapkan lingkungan pengujian untuk pustaka penyimpanan.

Tayangan

Share via

Pustaka klien Azure Storage Blob untuk JavaScript - versi 12.18.0

Memulai

Lingkungan yang didukung saat ini

Prasyarat

Instal paketnya

Mengautentikasi klien

Azure Active Directory

Kompatibilitas

Pekerja Web

Perbedaan antara Node.js dan browser

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

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

Bundel JavaScript

CORS

Konsep utama

Contoh

Mengimpor paket

Membuat klien layanan blob

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

menggunakan string koneksi

Dengan `StorageSharedKeyCredential`

dengan Token SAS

Membuat kontainer baru

Mencantumkan kontainer

Create blob dengan mengunggah data

Mencantumkan blob di dalam kontainer

Mengunduh blob dan mengonversinya menjadi string (Node.js)

Unduh blob dan konversikan ke string (Browser).

Pemecahan Masalah

Langkah berikutnya

Berkontribusi

Saran dan Komentar

Sumber Daya Tambahan:

Share via

Pustaka klien Azure Storage Blob untuk JavaScript - versi 12.18.0

Memulai

Lingkungan yang didukung saat ini

Prasyarat

Instal paketnya

Mengautentikasi klien

Azure Active Directory

Kompatibilitas

Pekerja Web

Perbedaan antara Node.js dan browser

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

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

Bundel JavaScript

CORS

Konsep utama

Contoh

Mengimpor paket

Membuat klien layanan blob

dengan DefaultAzureCredential dari @azure/identity paket

menggunakan string koneksi

Dengan StorageSharedKeyCredential

dengan Token SAS

Membuat kontainer baru

Mencantumkan kontainer

Create blob dengan mengunggah data

Mencantumkan blob di dalam kontainer

Mengunduh blob dan mengonversinya menjadi string (Node.js)

Unduh blob dan konversikan ke string (Browser).

Pemecahan Masalah

Langkah berikutnya

Berkontribusi

Saran dan Komentar

Sumber Daya Tambahan:

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

Dengan `StorageSharedKeyCredential`