Pustaka klien Azure Storage File Share untuk JavaScript

Artikel
07/24/2024

Azure Files menawarkan berbagi file yang dikelola sepenuhnya di cloud yang dapat diakses melalui protokol Server Message Block (SMB) standar industri. Berbagi file Azure dapat dipasang secara bersamaan oleh penyebaran cloud atau lokal Windows, Linux, dan macOS. Selain itu, berbagi file Azure dapat di-cache di Windows Server dengan Azure File Sync untuk akses cepat di dekat tempat data digunakan.

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

Gunakan pustaka klien dalam paket ini untuk:

Mendapatkan/Mengatur Properti Layanan File
Membuat/Mencantumkan/Menghapus Berbagi File
Membuat/Mencantumkan/Menghapus Direktori File
Membuat/Membaca/Mencantumkan/Memperbarui/Menghapus File

Catatan: Paket ini sebelumnya diterbitkan dengan nama @azure/storage-file. Ini telah diganti namanya menjadi @azure/storage-file-share agar lebih selaras dengan paket baru yang akan datang untuk Azure Storage Files DataLake dan menyediakan sekumpulan API yang konsisten untuk bekerja dengan file di Azure.

Tautan kunci:

Kode sumber
Paket (npm)
Dokumentasi Referensi API
dokumentasi produk
Sampel
REST API File Azure Storage

Persiapan

Lingkungan yang saat ini didukung

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

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

langganan Azure
Akun Penyimpanan

Menginstal paket

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

npm install @azure/storage-file-share

Mengautentikasi klien

Azure Storage mendukung beberapa cara untuk mengautentikasi. Untuk berinteraksi dengan layanan Azure Storage File Share, Anda harus membuat instans klien Storage - ShareServiceClient, ShareClient, atau ShareDirectoryClient misalnya. Lihat sampel untuk membuat ShareServiceClient untuk mempelajari selengkapnya tentang autentikasi.

Kunci Bersama
Tanda tangan akses bersama

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 file menyimpan data terkompresi dalam format gzip atau deflate dan pengodean kontennya diatur dengan benar, perilaku pengunduhan berbeda antara Node.js dan browser. Dalam Node.js klien penyimpanan akan mengunduh file dalam format terkompresinya, sementara di browser data akan diunduh dalam format dekompresi.

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

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

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

N/A

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

Komponen berikut dan pustaka klien terkait membentuk layanan Azure Storage File Share:

Akun penyimpanan itu sendiri, yang diwakili oleh ShareServiceClient
berbagi file dalam akun penyimpanan, yang diwakili oleh
Hierarki direktori opsional yang dalam berbagi file, yang diwakili oleh instans ShareDirectoryClient
File dalam berbagi file, yang mungkin berukuran hingga 1 TiB, diwakili oleh ShareFileClient

Contoh

Impor paket
Membuat klien layanan berbagi
Mencantumkan berbagi di akun
Membuat berbagi baru dan direktori
Buat file azure lalu unggah ke file tersebut
Mencantumkan file dan direktori di bawah direktori
Mengunduh file dan mengonversinya menjadi string (Node.js)
Mengunduh file dan mengonversinya menjadi string (Browser)

Impor paket

Untuk menggunakan klien, impor paket ke dalam file Anda:

const AzureStorageFileShare = require("@azure/storage-file-share");

Atau, secara selektif hanya mengimpor jenis yang Anda butuhkan:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

ShareServiceClient memerlukan URL ke layanan berbagi file dan kredensial akses. Ini juga secara opsional menerima beberapa pengaturan dalam parameter options.

menggunakan string koneksi

Atau, Anda dapat membuat instans ShareServiceClient menggunakan metode statis fromConnectionString() dengan string koneksi lengkap sebagai argumen. (String koneksi dapat diperoleh dari portal microsoft Azure.)

const { ShareServiceClient } = require("@azure/storage-file-share");

const connStr = "<connection string>";

const shareServiceClient = ShareServiceClient.fromConnectionString(connStr);

dengan `StorageSharedKeyCredential`

Berikan StorageSharedKeyCredential dengan nama akun dan kunci akun Anda. (Nama akun dan kunci akun dapat diperoleh dari portal microsoft Azure.)

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

// 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 credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  // When using AnonymousCredential, following url should include a valid SAS
  `https://${account}.file.core.windows.net`,
  credential
);

dengan Token SAS

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

const { ShareServiceClient } = require("@azure/storage-file-share");

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

const serviceClientWithSAS = new ShareServiceClient(
  `https://${account}.file.core.windows.net${sas}`
);

Mencantumkan berbagi di akun

Gunakan ShareServiceClient.listShares() untuk berbagi iterator di akun ini, dengan sintaks for-await-of baru:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  let shareIter = serviceClient.listShares();
  let i = 1;
  for await (const share of shareIter) {
    console.log(`Share${i}: ${share.name}`);
    i++;
  }
}

main();

Atau tanpa for-await-of:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  let shareIter = serviceClient.listShares();
  let i = 1;
  let shareItem = await shareIter.next();
  while (!shareItem.done) {
    console.log(`Share ${i++}: ${shareItem.value.name}`);
    shareItem = await shareIter.next();
  }
}

main();

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

async function main() {
  const shareName = `newshare${new Date().getTime()}`;
  const shareClient = serviceClient.getShareClient(shareName);
  await shareClient.create();
  console.log(`Create share ${shareName} successfully`);

  const directoryName = `newdirectory${new Date().getTime()}`;
  const directoryClient = shareClient.getDirectoryClient(directoryName);
  await directoryClient.create();
  console.log(`Create directory ${directoryName} successfully`);
}

main();

Buat file azure lalu unggah ke file tersebut

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  const content = "Hello World!";
  const fileName = "newfile" + new Date().getTime();
  const fileClient = directoryClient.getFileClient(fileName);
  await fileClient.create(content.length);
  console.log(`Create file ${fileName} successfully`);

  // Upload file range
  await fileClient.uploadRange(content, 0, content.length);
  console.log(`Upload file range "${content}" to ${fileName} successfully`);
}

main();

Mencantumkan file dan direktori di bawah direktori

Gunakan DirectoryClient.listFilesAndDirectories() untuk iterator melalui file dan direktori, dengan sintaks for-await-of baru. Properti kind dapat digunakan untuk mengidentifikasi apakah iterm adalah direktori atau file.

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  let dirIter = directoryClient.listFilesAndDirectories();
  let i = 1;
  for await (const item of dirIter) {
    if (item.kind === "directory") {
      console.log(`${i} - directory\t: ${item.name}`);
    } else {
      console.log(`${i} - file\t: ${item.name}`);
    }
    i++;
  }
}

main();

Atau tanpa menggunakan for-await-of:

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const directoryName = "<directory name>";

async function main() {
  const directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

  let dirIter = directoryClient.listFilesAndDirectories();
  let i = 1;
  let item = await dirIter.next();
  while (!item.done) {
    if (item.value.kind === "directory") {
      console.log(`${i} - directory\t: ${item.value.name}`);
    } else {
      console.log(`${i} - file\t: ${item.value.name}`);
    }
    item = await dirIter.next();
  }
}

main();

Untuk sampel lengkap tentang iterasi, silakan lihat sampel /v12/typescript/src/listFilesAndDirectories.ts.

Mengunduh file dan mengonversinya menjadi string (Node.js)

const { ShareServiceClient, StorageSharedKeyCredential } = require("@azure/storage-file-share");

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

const credential = new StorageSharedKeyCredential(account, accountKey);
const serviceClient = new ShareServiceClient(
  `https://${account}.file.core.windows.net`,
  credential
);

const shareName = "<share name>";
const fileName = "<file name>";

// [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);
  });
}

async function main() {
  const fileClient = serviceClient
    .getShareClient(shareName)
    .rootDirectoryClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadFileResponse.readableStreamBody
  const downloadFileResponse = await fileClient.download();
  console.log(
    `Downloaded file content: ${(
      await streamToBuffer(downloadFileResponse.readableStreamBody)
    ).toString()}`
  );
}

main();

Mengunduh file dan mengonversinya menjadi string (Browser)

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

const { ShareServiceClient } = require("@azure/storage-file-share");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const shareName = "<share name>";
const fileName = "<file name>";

const serviceClient = new ShareServiceClient(`https://${account}.file.core.windows.net${sas}`);

async function main() {
  const fileClient = serviceClient
    .getShareClient(shareName)
    .rootDirectoryClient.getFileClient(fileName);

  // Get file content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadFileResponse.blobBody
  const downloadFileResponse = await fileClient.download(0);
  console.log(
    `Downloaded file content: ${await blobToString(await downloadFileResponse.blobBody)}`
  );
}

// [Browser 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 ShareServiceClient sederhana ada di sampel/v12/typescript/src/shareSerivceClient.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

File Share Storage Samples (JavaScript)
File Share Storage Samples (TypeScript)
Kasus Pengujian Penyimpanan Berbagi File

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

Bagikan melalui

Persiapan

Lingkungan yang saat ini didukung

Prasyarat

Menginstal paket

Mengautentikasi klien

Kompatibilitas

Pekerja Web

Perbedaan antara Node.js dan browser

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

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

Bundel JavaScript

CORS

Konsep utama

Contoh

Impor paket

menggunakan string koneksi

dengan `StorageSharedKeyCredential`

dengan Token SAS

Mencantumkan berbagi di akun

Buat file azure lalu unggah ke file tersebut

Mencantumkan file dan direktori di bawah direktori

Mengunduh file dan mengonversinya menjadi string (Node.js)

Mengunduh file dan mengonversinya menjadi string (Browser)

Pemecahan masalah

Langkah berikutnya

Berkontribusi

Sumber Daya Tambahan:

Bagikan melalui

Pustaka klien Azure Storage File Share untuk JavaScript - versi 12.24.0

Persiapan

Lingkungan yang saat ini didukung

Prasyarat

Menginstal paket

Mengautentikasi klien

Kompatibilitas

Pekerja Web

Perbedaan antara Node.js dan browser

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

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

Bundel JavaScript

CORS

Konsep utama

Contoh

Impor paket

Membuat klien layanan berbagi

menggunakan string koneksi

dengan StorageSharedKeyCredential

dengan Token SAS

Mencantumkan berbagi di akun

Membuat berbagi baru dan direktori

Buat file azure lalu unggah ke file tersebut

Mencantumkan file dan direktori di bawah direktori

Mengunduh file dan mengonversinya menjadi string (Node.js)

Mengunduh file dan mengonversinya menjadi string (Browser)

Pemecahan masalah

Langkah berikutnya

Berkontribusi

Sumber Daya Tambahan:

dengan `StorageSharedKeyCredential`