Pustaka klien Azure Storage File Data Lake untuk JavaScript - versi 12.28.1

Azure Data Lake Storage (ADLS) mencakup semua kemampuan yang diperlukan untuk memudahkan pengembang, ilmuwan data, dan analis untuk menyimpan data dengan ukuran, bentuk, dan kecepatan apa pun, dan melakukan semua jenis pemrosesan dan analitik di seluruh platform dan bahasa. Ini menghapus kompleksitas penyerapan dan penyimpanan semua data Anda sambil membuatnya lebih cepat untuk bangun dan berjalan dengan analitik batch, streaming, dan interaktif.

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

Gunakan pustaka klien dalam paket ini untuk:

Membuat/Mencantumkan/Menghapus Sistem File
Buat/Baca/Daftar/Perbarui/Hapus Jalur, Direktori, dan File

Tautan utama:

Kode sumber
Paket (npm)
Dokumentasi Referensi API
dokumentasi produk
Samples
REST API Azure Storage Data Lake

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 Data Lake untuk JavaScript adalah dengan menggunakan manajer paket npm. Ketik berikut ini ke dalam jendela terminal:

npm install @azure/storage-file-datalake

Mengautentikasi klien

Azure Storage mendukung beberapa cara untuk mengautentikasi. Untuk berinteraksi dengan layanan Azure Data Lake Storage, Anda harus membuat instans klien Storage - DataLakeServiceClient, DataLakeFileSystemClient, atau DataLakePathClient misalnya. Lihat sampel untuk membuat DataLakeServiceClient untuk mempelajari selengkapnya tentang autentikasi.

Azure Active Directory
Kunci Bersama
Tanda tangan akses bersama

Azure Active Directory

Layanan Azure Data Lake 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 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 hanya tersedia di Node.js

Otorisasi Kunci Bersama berdasarkan nama akun dan kunci akun
- StorageSharedKeyCredential
Pembuatan Tanda Tangan Akses Bersama (SAS)
- generateAccountSASQueryParameters()
- generateDataLakeSASQueryParameters()
Pengunggahan dan pengunduhan paralel. Perhatikan bahwa DataLakeFileClient.upload() tersedia di Node.js dan browser.
- DataLakeFileClient.uploadFile()
- DataLakeFileClient.uploadStream()
- DataLakeFileClient.readToBuffer()
- DataLakeFileClient.readToFile()

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

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

Pemberitahuan: Data Lake saat ini berbagi pengaturan CORS untuk layanan blob.

Konsep utama

Azure Data Lake Storage Gen2 dirancang untuk:

Menyajikan beberapa petabyte informasi sambil mempertahankan ratusan gigabit throughput
Memungkinkan Anda mengelola data dalam jumlah besar dengan mudah

Fitur Utama DataLake Storage Gen2 meliputi:

Akses yang kompatibel dengan Hadoop
Set super izin POSIX
Hemat biaya dalam hal kapasitas dan transaksi penyimpanan berhemat rendah
Driver yang dioptimalkan untuk analitik big data

Bagian mendasar dari Data Lake Storage Gen2 adalah penambahan namespace hierarkis ke penyimpanan Blob. Namespace hierarkis mengatur objek/file ke dalam hierarki direktori untuk akses data yang efisien.

Di masa lalu, analitik berbasis cloud harus berkompromi di bidang performa, manajemen, dan keamanan. Data Lake Storage Gen2 membahas masing-masing aspek ini dengan cara berikut:

Performa dioptimalkan karena Anda tidak perlu menyalin atau mengubah data sebagai prasyarat untuk analisis. Namespace hierarkis sangat meningkatkan performa operasi manajemen direktori, yang meningkatkan performa pekerjaan secara keseluruhan.
Manajemen lebih mudah karena Anda dapat mengatur dan memanipulasi file melalui direktori dan subdirektori.
Keamanan dapat diberlakukan karena Anda dapat menentukan izin POSIX pada direktori atau file individual.
Efektivitas biaya dimungkinkan karena Data Lake Storage Gen2 dibangun di atas penyimpanan Azure Blob berbiaya rendah. Fitur tambahan semakin menurunkan total biaya kepemilikan untuk menjalankan analitik big data di Azure.

Penyimpanan Data Lake menawarkan tiga jenis sumber daya:

Akun penyimpanan yang digunakan melaluiDataLakeServiceClient
Sistem file di akun penyimpanan yang digunakan melalui DataLakeFileSystemClient
Jalur dalam sistem file yang digunakan melalui DataLakeDirectoryClient atauDataLakeFileClient

Azure DataLake Gen2	Blob
Filesystem	Container
Jalur (File atau Direktori)	Blob

Catatan: Pustaka klien ini hanya mendukung akun penyimpanan dengan namespace hierarkis (HNS) diaktifkan.

Examples

Impor paket
Membuat klien layanan data lake
Membuat sistem file baru
Mencantumkan sistem file
Membuat dan menghapus direktori
Membuat file
Mencantumkan jalur di dalam sistem file
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:

import * as AzureStorageDataLake from "@azure/storage-file-datalake";

Atau, secara selektif hanya mengimpor jenis yang Anda butuhkan:

import { DataLakeServiceClient, StorageSharedKeyCredential } from "@azure/storage-file-datalake";

Membuat klien layanan data lake

DataLakeServiceClient memerlukan URL ke layanan data lake 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 DataLakeServiceClient

Notice. Azure Data Lake saat ini menggunakan kembali peran terkait blob seperti "Pemilik Data Blob Penyimpanan" selama autentikasi AAD OAuth berikut.

Penyiapan : Referensi - Mengotorisasi akses ke blob (danau data) 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 Data Lake dengan RBAC di Portal Microsoft Azure
- Peran RBAC untuk blob (data lake) 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 { DataLakeServiceClient } from "@azure/storage-file-datalake";

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

const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.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 DataLakeServiceClient 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 { DataLakeServiceClient } from "@azure/storage-file-datalake";

const connectionString = "<connection string>";

const dataLakeServiceClient = DataLakeServiceClient.fromConnectionString(connectionString);

dengan `StorageSharedKeyCredential`

Atau, Anda membuat instans DataLakeServiceClient 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, DataLakeServiceClient } from "@azure/storage-file-datalake";

// 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 datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  sharedKeyCredential,
);

dengan Token SAS

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

import { DataLakeServiceClient } from "@azure/storage-file-datalake";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const serviceClientWithSAS = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`,
);

Membuat sistem file baru

Gunakan DataLakeServiceClient.getFileSystemClient() untuk mendapatkan instans klien sistem file lalu buat sumber daya sistem file baru.

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

// Create a file system
const fileSystemName = `newfilesystem${new Date().getTime()}`;
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const createResponse = await fileSystemClient.create();
console.log(`Create file system ${fileSystemName} successfully`, createResponse.requestId);

Mencantumkan sistem file

Gunakan fungsi DataLakeServiceClient.listFileSystems() untuk melakukan iterasi sistem file, dengan sintaks for-await-of baru:

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
for await (const fileSystem of fileSystems) {
  console.log(`File system ${i++}: ${fileSystem.name}`);
}

Atau tanpa menggunakan for-await-of:

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const fileSystems = datalakeServiceClient.listFileSystems();
let { value, done } = await fileSystems.next();
while (!done) {
  console.log(`File system ${i++}: ${value.name}`);
  ({ value, done } = await fileSystems.next());
}

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

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const response of datalakeServiceClient.listFileSystems().byPage({ maxPageSize: 20 })) {
  if (response.fileSystemItems) {
    for (const fileSystem of response.fileSystemItems) {
      console.log(`File System ${i++}: ${fileSystem.name}`);
    }
  }
}

Membuat dan menghapus direktori

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const directoryClient = fileSystemClient.getDirectoryClient("directory");
await directoryClient.create();
await directoryClient.delete();

Membuat file

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

const content = "Hello world!";
const fileName = `newfile${+new Date()}`;
const fileClient = fileSystemClient.getFileClient(fileName);
await fileClient.create();
await fileClient.append(content, 0, content.length);
await fileClient.flush(content.length);
console.log(`Create and upload file ${fileName} successfully`);

Mencantumkan jalur di dalam sistem file

Mirip dengan mencantumkan sistem file.

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);

let i = 1;
const paths = fileSystemClient.listPaths();
for await (const path of paths) {
  console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
}

Mengunduh file dan mengonversinya menjadi string (Node.js)

import { DataLakeServiceClient } from "@azure/storage-file-datalake";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net`,
  new DefaultAzureCredential(),
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const fileClient = fileSystemClient.getFileClient(fileName);

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

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

Mengunduh file dan mengonversinya menjadi string (Browser)

import { DataLakeServiceClient } from "@azure/storage-file-datalake";

const account = "<account>";
const sas = "<sas token>";
const datalakeServiceClient = new DataLakeServiceClient(
  `https://${account}.dfs.core.windows.net${sas}`,
);

const fileSystemName = "<file system name>";
const fileName = "<file name>";
const fileSystemClient = datalakeServiceClient.getFileSystemClient(fileSystemName);
const fileClient = fileSystemClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In browsers, get downloaded data by accessing downloadResponse.contentAsBlob
const downloadResponse = await fileClient.read();
if (downloadResponse.contentAsBlob) {
  const blob = await downloadResponse.contentAsBlob;
  const downloaded = await blob.text();
  console.log(`Downloaded file content ${downloaded}`);
}

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:

Sampel Penyimpanan DataLake (JavaScript)
Sampel DataLake Storage (TypeScript)
Kasus Pengujian DataLake Storage

Contributing

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

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-17