استخدم JavaScript SDK في Node.js لإدارة الدلائل والملفات في Azure Data Lake Storage Gen2

توضح لك هذه المقالة كيفية استخدام Node.js لإنشاء الدلائل والملفات وإدارتها في حسابات التخزين التي تحتوي على مساحة الأسماء الهرمية.

للتعرف على كيفية الحصول على قائمة التحكم بالوصول (ACL) الخاصة بالدلائل والملفات وتعيينها وتحديثها، راجع استخدام JavaScript SDK في Node.js لإدارة قوائم التحكم بالوصول في Azure Data Lake Storage Gen2.

حزمة (Node Package Manager) | عينات | إعطاء التعليقات

المتطلبات الأساسية

• اشتراك Azure. لمزيد من المعلومات، راجع الحصول على التجربة المجانية من Azure.

• حساب تخزين يحتوي على مساحة أسماء هرمية ممكنة. اتبع هذه الإرشادات لإنشاء واحدة.

• إذا كنت تستخدم هذه الحزمة في تطبيق Node.js، فستحتاج إلى Node.js 8.0.0 أو أعلى.

إعداد مشروعك

ثبت مكتبة عميل Data Lake لـ JavaScript عن طريق فتح نافذة terminal، ثم اكتب الأمر التالي.

npm install @azure/storage-file-datalake

استورد الحزمة storage-file-datalake عن طريق وضع هذه العبارة في الجزء العلوي من ملف التعليمة البرمجية.

const {
AzureStorageDataLake,
DataLakeServiceClient,
StorageSharedKeyCredential
} = require("@azure/storage-file-datalake");

إشعار

يتيح الوصول متعدد البروتوكولات على Data Lake Storage للتطبيقات استخدام كل من واجهات برمجة تطبيقات Blob وواجهات برمجة تطبيقات Data Lake Storage Gen2 للعمل مع البيانات في حسابات التخزين مع تمكين مساحة الاسم الهرمية (HNS). عند العمل مع قدرات فريدة من نوعها ل Data Lake Storage Gen2، مثل عمليات الدليل و ACLs، استخدم واجهات برمجة تطبيقات Data Lake Storage Gen2، كما هو موضح في هذه المقالة.

عند اختيار واجهات برمجة التطبيقات التي يجب استخدامها في سيناريو معين، ضع في اعتبارك حمل العمل واحتياجات التطبيق الخاص بك، بالإضافة إلى المشكلات المعروفة وتأثير HNS على أحمال العمل والتطبيقات.

الاتصال بالحساب

لاستخدام القصاصات البرمجية الموجودة في هذه المقالة، ستحتاج إلى إنشاء مثيل DataLakeServiceClient يُمثل حساب التخزين.

الاتصال باستخدام معرف Microsoft Entra

يمكنك استخدام مكتبة عميل هوية Azure ل JS لمصادقة التطبيق الخاص بك باستخدام معرف Microsoft Entra.

إنشاء مثيل DataLakeServiceClient وتمرير مثيل جديد من فئة DefaultAzureCredential .

function GetDataLakeServiceClientAD(accountName) {

  const dataLakeServiceClient = new DataLakeServiceClient(
      `https://${accountName}.dfs.core.windows.net`,
      new DefaultAzureCredential());

  return dataLakeServiceClient;
}

لمعرفة المزيد حول استخدام DefaultAzureCredential لتخويل الوصول إلى البيانات، راجع نظرة عامة: مصادقة تطبيقات JavaScript إلى Azure باستخدام Azure SDK.

الاتصال باستخدام مفتاح حساب

يمكنك تخويل الوصول إلى البيانات باستخدام مفاتيح الوصول إلى حسابك (المفتاح المشترك). ينشئ هذا المثال مثيل DataLakeServiceClient المخول بمفتاح الحساب.

function GetDataLakeServiceClient(accountName, accountKey) {

  const sharedKeyCredential =
     new StorageSharedKeyCredential(accountName, accountKey);

  const dataLakeServiceClient = new DataLakeServiceClient(
      `https://${accountName}.dfs.core.windows.net`, sharedKeyCredential);

  return dataLakeServiceClient;
}

يعمل أسلوب التخويل هذا فقط مع تطبيقات Node.js. إذا كنت تخطط لتشغيل التعليمات البرمجية الخاصة بك في مستعرض، يمكنك التخويل باستخدام معرف Microsoft Entra.

تنبيه

لا يوصى بالتخويل باستخدام المفتاح المشترك لأنه قد يكون أقل أمانا. للحصول على الأمان الأمثل، قم بتعطيل التخويل عبر المفتاح المشترك لحساب التخزين الخاص بك، كما هو موضح في منع تخويل المفتاح المشترك لحساب Azure Storage.

يجب أن يقتصر استخدام مفاتيح الوصول سلسلة الاتصال على الإثبات الأولي لتطبيقات المفاهيم أو النماذج الأولية للتطوير التي لا تصل إلى الإنتاج أو البيانات الحساسة. وإلا، يجب دائما تفضيل فئات المصادقة المستندة إلى الرمز المميز المتوفرة في Azure SDK عند المصادقة على موارد Azure.

توصي Microsoft بأن يستخدم العملاء إما معرف Microsoft Entra أو توقيع وصول مشترك (SAS) لتخويل الوصول إلى البيانات في Azure Storage. لمزيد من المعلومات، راجع تخويل العمليات للوصول إلى البيانات.

إنشاء حاوية

تعمل الحاوية كنظام ملفات لملفاتك. يمكنك إنشاء واحد عن طريق الحصول على مثيل FileSystemClient ثم استدعاء الأسلوب FileSystemClient.Create.

هذا المثال ينشئ حاوية باسم my-file-system.

async function CreateFileSystem(dataLakeServiceClient) {

  const fileSystemName = "my-file-system";

  const fileSystemClient = dataLakeServiceClient.getFileSystemClient(fileSystemName);

  const createResponse = await fileSystemClient.create();

}

إنشاء دليل

إنشاء مرجع دليل عن طريق الحصول على مثيل DirectoryClient ثم استدعاء الأسلوب DirectoryClient.create.

يضيف هذا المثال دليلاً باسم my-directory إلى حاوية.

async function CreateDirectory(fileSystemClient) {

  const directoryClient = fileSystemClient.getDirectoryClient("my-directory");

  await directoryClient.create();

}

إعادة تسمية دليل أو نقله

إعادة تسمية أو نقل دليل عن طريق استدعاء الأسلوب DirectoryClient.rename. تمرير مسار الدليل المطلوب معلمة.

يعيد هذا المثال تسمية دليل فرعي بالاسم my-directory-renamed.

async function RenameDirectory(fileSystemClient) {

  const directoryClient = fileSystemClient.getDirectoryClient("my-directory");
  await directoryClient.move("my-directory-renamed");

}

ينقل هذا المثال دليلا باسم my-directory-renamed إلى دليل فرعي لدليل يسمى my-directory-2.

async function MoveDirectory(fileSystemClient) {

  const directoryClient = fileSystemClient.getDirectoryClient("my-directory-renamed");
  await directoryClient.move("my-directory-2/my-directory-renamed");

}

حذف دليل

حذف دليل عن طريق استدعاء الأسلوب DirectoryClient.delete.

يحذف هذا المثال دليلاً باسم my-directory.

async function DeleteDirectory(fileSystemClient) {

  const directoryClient = fileSystemClient.getDirectoryClient("my-directory");
  await directoryClient.delete();

}

تحميل ملف إلى دليل

أولاً، اقرأ ملفاً. يستخدم هذا المثال الوحدة النمطية Node.js fs. ثم قم بإنشاء مرجع ملف في الدليل الهدف عن طريق إنشاء مثيل FileClient ثم استدعاء الأسلوب FileClient.create. تحميل ملف عن طريق استدعاء الأسلوب FileClient.append. تأكد من إكمال التحميل عن طريق استدعاء الأسلوب FileClient.flush.

يقوم هذا المثال بتحميل ملف نصي إلى دليل باسم my-directory.`

async function UploadFile(fileSystemClient) {

  const fs = require('fs')

  var content = "";

  fs.readFile('mytestfile.txt', (err, data) => {
      if (err) throw err;

      content = data.toString();

  })

  const fileClient = fileSystemClient.getFileClient("my-directory/uploaded-file.txt");
  await fileClient.create();
  await fileClient.append(content, 0, content.length);
  await fileClient.flush(content.length);

}

تنزيل من دليل

أولاً، قم بإنشاء مثيل FileSystemClient الذي يُمثل الملف الذي تريد تنزيله. استخدم الأسلوب FileSystemClient.read لقراءة الملف. ثم اكتب الملف. يستخدم هذا المثال الوحدة النمطية Node.js fs للقيام بذلك.

إشعار

يعمل أسلوب تنزيل ملف هذا فقط مع تطبيقات Node.js. إذا كنت تخطط لتشغيل التعليمة البرمجية في مستعرض، فراجع مكتبة عميل Azure Storage File Data Lake لـ JavaScript للملف التمهيدي من أجل الحصول على مثال حول كيفية القيام بذلك في مستعرض.

async function DownloadFile(fileSystemClient) {

  const fileClient = fileSystemClient.getFileClient("my-directory/uploaded-file.txt");

  const downloadResponse = await fileClient.read();

  const downloaded = await streamToString(downloadResponse.readableStreamBody);

  async function streamToString(readableStream) {
    return new Promise((resolve, reject) => {
      const chunks = [];
      readableStream.on("data", (data) => {
        chunks.push(data.toString());
      });
      readableStream.on("end", () => {
        resolve(chunks.join(""));
      });
      readableStream.on("error", reject);
    });
  }

  const fs = require('fs');

  fs.writeFile('mytestfiledownloaded.txt', downloaded, (err) => {
    if (err) throw err;
  });
}

إعداد قائمة محتويات الدليل

يقوم هذا المثال بطباعة أسماء كل دليل وملف موجود في دليل باسم my-directory.

async function ListFilesInDirectory(fileSystemClient) {

  let i = 1;

  let iter = await fileSystemClient.listPaths({path: "my-directory", recursive: true});

  for await (const path of iter) {

    console.log(`Path ${i++}: ${path.name}, is directory: ${path.isDirectory}`);
  }

}

(راجع أيضًا )

• الحزمة (Node Package Manager)
• عينات
• تقديم ملاحظات