مشاركة عبر

التشغيل السريع: مكتبة عميل Azure Blob Storage Node.js باستخدام TypeScript

ابدأ مع مكتبة عميل Azure Blob Storage Node.js باستخدام TypeScript لإدارة الكائنات الثنائية كبيرة الحجم والحاويات.

في هذه المقالة، يمكنك اتباع الخطوات لتثبيت الحزمة وتجربة مثال التعليمات البرمجية للمهام الأساسية.

مرجع واجهة برمجة التطبيقات | مكتبة مصدر التعليمات البرمجية | الحزمة (npm) | عينات

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

الإعداد

يرشدك هذا القسم خلال إعداد مشروع للعمل مع مكتبة عميل Azure Blob Storage Node.js.

إنشاء مشروع Node.js

إنشاء تطبيق TypeScript باسم blob-quickstart.

  1. في نافذة وحدة تحكم (مثل cmd أو PowerShell أو Bash)، قم بإنشاء دليل جديد للمشروع:

    mkdir blob-quickstart

  2. قم بالتبديل إلى دليل blob-quickstart الذي تم إنشاؤه حديثا:

    cd blob-quickstart

  3. إنشاء ملف package.json:

    npm init -y

  4. فتح المشروع في التعليمة البرمجية Visual Studio:

    code .

  5. تحرير ملف package.json لإضافة الخصائص التالية لدعم ESM مع TypeScript:

    "type": "module",

قم بتثبيت الحِزَم

من دليل المشروع، قم بتثبيت الحزم التالية باستخدام npm install الأمر .

  1. قم بتثبيت حزمة Azure Storage npm:

    npm install @azure/storage-blob

  2. ثم بتثبيت التبعيات الأخرى المستخدمة في هذا التشغيل السريع:

    npm install uuid dotenv @types/node @types/uuid

  3. tsconfig.json إنشاء ملف في دليل المشروع بالمحتويات التالية.

    {
    "compilerOptions": {
      "target": "es2022",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
      "module": "ESNext",                                /* Specify what module code is generated. */
      "moduleResolution": "node",                     /* Specify how TypeScript looks up a file from a given module specifier. */
      "outDir": "dist",                                   /* Specify an output folder for all emitted files. */
      "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
      "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
      "strict": true,                                      /* Enable all strict type-checking options. */
      "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
    }
  }

نموذج الكائن

يتم تحسين Azure Blob Storage لتخزين كميات هائلة من البيانات غير المنظمة. البيانات غير منظمة البنية هي بيانات لا تلتزم بنموذج بيانات أو تعريف معين، مثل البيانات النصية أو الثنائية. يوفر موقع تخزين Blob ثلاثة أنواع من الموارد:

  • حساب التخزين
  • حاوية في حساب التخزين
  • كائن تخزين بيانات ثنائية كبيرة في الحاوية

يعرض الرسم التخطيطي التالي العلاقة بين هذه الموارد.

رسم تخطيطي لبنية Blob storage.

استخدم فئات JavaScript التالية للتفاعل مع هذه الموارد:

  • BlobServiceClient: BlobServiceClient تسمح لك الفئة بمعالجة موارد Azure Storage وحاويات كائن تخزين البيانات الثنائية الكبيرة.
  • ContainerClient: تسمح لك الفئة ContainerClient بمعالجة حاويات Azure Storage والكائنات الثنائية كبيرة الحجم الخاصة بها.
  • BlobClient: BlobClient تسمح الفئة لك بمعالجة نقط تخزين Azure.

أمثلة على التعليمات البرمجية

توضح لك أمثلة أجزاء التعليمات البرمجية هذه كيفية القيام بالمهام التالية باستخدام مكتبة عميل Azure Blob Storage ل JavaScript:

يتوفر نموذج التعليمات البرمجية أيضا على GitHub.

المصادقة على Azure وتخويل الوصول إلى بيانات الكائن الثنائي كبير الحجم

يجب تخويل طلبات التطبيق إلى Azure Blob Storage. DefaultAzureCredential استخدام الفئة التي توفرها مكتبة عميل Azure Identity هو الأسلوب الموصى به لتنفيذ اتصالات بدون كلمة مرور بخدمات Azure في التعليمات البرمجية الخاصة بك، بما في ذلك Blob Storage.

يمكنك أيضًا تخويل الطلبات إلى Azure Blob Storage باستخدام مفتاح الوصول إلى الحساب. ومع ذلك، ينبغي استخدام هذا النهج بحذر. يجب أن يكون المطورون مجتهدين لعدم عرض مفتاح الوصول في موقع غير آمن. يمكن لأي شخص لديه مفتاح الوصول تخويل الطلبات مقابل حساب التخزين، ولديه حق الوصول إلى جميع البيانات بشكل فعال. DefaultAzureCredential يوفر مزايا إدارة وأمان محسنة عبر مفتاح الحساب للسماح بالمصادقة التي لا تتطلب كلمة مرور. يتم عرض كلا الخيارين في المثال التالي.

DefaultAzureCredential يدعم أساليب مصادقة متعددة ويحدد الأسلوب الذي يجب استخدامه في وقت التشغيل. يمكن هذا النهج تطبيقك من استخدام أساليب مصادقة مختلفة في بيئات مختلفة (البيئة المحلية مقابل بيئة التشغيل) دون تنفيذ التعليمات البرمجية الخاصة بالبيئة.

يمكن العثور على الترتيب والمواقع التي تبحث فيها DefaultAzureCredential عن بيانات الاعتماد في نظرة عامة على مكتبة هوية Azure.

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

تعيين أدوار لحساب مستخدم Microsoft Entra

عند التطوير محليًا، تأكد من أن حساب المستخدم الذي يصل إلى بيانات الكائن الثنائي كبير الحجم لديه الأذونات الصحيحة. ستحتاج إلى Storage Blob Data Contributor لقراءة بيانات الكائن الثنائي كبير الحجم وكتابتها. لتعيين هذا الدور لنفسك، ستحتاج إلى تعيين دور مسؤول وصول المستخدم، أو دور آخر يتضمن إجراء Microsoft.Authorization/roleAssignments/write . يمكنك تعيين أدوار Azure RBAC لمستخدم باستخدام مدخل Microsoft Azure أو Azure CLI أو Azure PowerShell. لمزيد من المعلومات حول دور مساهم بيانات Storage Blob ، راجع مساهم بيانات Blob للتخزين. لمزيد من المعلومات حول النطاقات المتوفرة لتعيينات الأدوار، راجع فهم نطاق Azure RBAC.

في هذا السيناريو، ستقوم بتعيين أذونات لحساب المستخدم الخاص بك، محددة النطاق إلى حساب التخزين، لاتباع مبدأ أقل الامتيازات. تمنح هذه الممارسة المستخدمين الحد الأدنى من الأذونات المطلوبة فقط وتنشئ بيئات تشغيل أكثر أمانًا.

سيقوم المثال التالي بتعيين دور Storage Blob Data Contributor إلى حساب المستخدم الخاص بك، والذي يوفر حق الوصول للقراءة والكتابة إلى بيانات blob في حساب التخزين الخاص بك.

هام

في معظم الحالات، سيستغرق نشر تعيين الدور في Azure دقيقة أو دقيقتين، ولكن في حالات نادرة قد يستغرق الأمر ما يصل إلى ثماني دقائق. إذا تلقيت أخطاء المصادقة عند تشغيل التعليمات البرمجية لأول مرة، فانتظر بضع لحظات وحاول مرة أخرى.

  1. في مدخل Microsoft Azure، حدد موقع حساب التخزين الخاص بك باستخدام شريط البحث الرئيسي أو شريط التنقل الأيسر.

  2. في صفحة نظرة عامة على حساب التخزين، حدد التحكم بالوصول (IAM) من القائمة اليسرى.

  3. حدد صفحة التحكم بالوصول (IAM)، وحدد علامة تبويب تعيينات الدور.

  4. حدد + إضافة من القائمة العلوية ثم إضافة تعيين الدور من القائمة المنسدلة الناتجة.

    لقطة شاشة توضح كيفية تعيين دور.

  5. استخدم مربع البحث لتصفية النتائج إلى الدور المطلوب. في هذا المثال، ابحث عن مساهم بيانات Storage Blob وحدد النتيجة المطابقة ثم اختر التالي.

  6. ضمن تعيين الوصول إلى، حدد المستخدم أو المجموعة أو كيان الخدمة، ثم اختر + تحديد الأعضاء.

  7. في مربع الحوار، ابحث عن اسم مستخدم Microsoft Entra (عنوان بريدك الإلكتروني user@domain عادة) ثم اختر تحديد في أسفل مربع الحوار.

  8. حدد مراجعة + تعيين للانتقال إلى الصفحة النهائية، ثم مراجعة + تعيين مرة أخرى لإكمال العملية.

تسجيل الدخول وتوصيل التعليمات البرمجية للتطبيق الخاص بك ب Azure باستخدام DefaultAzureCredential

يمكنك تخويل الوصول إلى البيانات في حساب التخزين الخاص بك باستخدام الخطوات التالية:

  1. تأكد من مصادقتك باستخدام نفس حساب Microsoft Entra الذي قمت بتعيين الدور له على حساب التخزين الخاص بك. يمكنك المصادقة عبر Azure CLI أو Visual Studio Code أو Azure PowerShell.

    سجل الدخول إلى Azure من خلال Azure CLI باستخدام الأمر التالي:

    az login

  2. لاستخدام DefaultAzureCredential، تأكد من تثبيت حزمة @azure\identity، واستيراد الفئة:

    import { DefaultAzureCredential } from '@azure/identity';

  3. أضف هذه التعليمة البرمجية try داخل الكتلة. عند تشغيل التعليمات البرمجية على محطة العمل المحلية، DefaultAzureCredential يستخدم بيانات اعتماد المطور للأداة ذات الأولوية التي قمت بتسجيل الدخول إليها للمصادقة على Azure. تتضمن أمثلة هذه الأدوات Azure CLI أو Visual Studio Code.

    const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME as string;
if (!accountName) throw Error('Azure Storage accountName not found');

// Add `Storage Blob Data Contributor` role assignment to the identity
const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);

  4. تأكد من تحديث اسم حساب التخزين، AZURE_STORAGE_ACCOUNT_NAME، في .env الملف أو متغيرات البيئة الخاصة بك. يمكن العثور على اسم حساب التخزين في صفحة النظرة العامة لمدخل Microsoft Azure.

    لقطة شاشة تعرض كيفية العثور على اسم حساب التخزين.

    إشعار

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

إنشاء حاوية

إنشاء حاوية جديدة في حساب التخزين. يأخذ مثال التعليمات البرمجية التالي كائن BlobServiceClient ويستدعي أسلوب getContainerClient للحصول على مرجع إلى حاوية. بعد ذلك، تستدعي التعليمات البرمجية أسلوب الإنشاء لإنشاء الحاوية فعليا في حساب التخزين الخاص بك.

أضف هذه التعليمات البرمجية إلى الكتلة try:

  const containerName = 'quickstart' + uuidv4();

  console.log('\nCreating container...');
  console.log('\t', containerName);

  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse: ContainerCreateResponse = await containerClient.create();
  console.log(
    `Container was created successfully.\n\trequestId:${createContainerResponse.requestId}\n\tURL: ${containerClient.url}`
  );

لمعرفة المزيد حول إنشاء حاوية، واستكشاف المزيد من نماذج التعليمات البرمجية، راجع إنشاء حاوية كائن ثنائي كبير الحجم باستخدام JavaScript.

هام

ويجب أن تكون أسماء الحاويات بأحرف صغيرة. لمزيد من المعلومات حول عملية تسمية الحاويات والكائنات الثنائية كبيرة الحجم، راجع تسمية الحاويات والكائنات الثنائية كبيرة الحجم وبيانات التعريف والإشارة إليها.

تحميل الكائنات الثنائية كبيرة الحجم إلى حاوية

تحميل كائن ثنائي كبير الحجم إلى الحاوية. تحصل التعليمات البرمجية التالية على مرجع إلى كائن BlockBlobClient عن طريق استدعاء الأسلوب getBlockBlobClient على ContainerClient من قسم إنشاء حاوية .

تقوم التعليمة البرمجية بتحميل بيانات السلسلة النصية إلى كائن ثنائي كبير الحجم عن طريق استدعاء أسلوب upload.

أضف هذه التعليمات البرمجية إلى الكتلة try:

  const blobName = 'quickstart' + uuidv4(); + '.txt';
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  console.log(
    `\nUploading to Azure storage as blob\n\tname: ${blobName}:\n\tURL: ${blockBlobClient.url}`
  );

  const data = 'Hello, World!';
  const uploadBlobResponse: BlockBlobUploadResponse = await blockBlobClient.upload(data, data.length);
  console.log(
    `Blob was uploaded successfully. requestId: ${uploadBlobResponse.requestId}`
  );

لمعرفة المزيد حول تحميل الكائنات الثنائية كبيرة الحجم، واستكشاف المزيد من نماذج التعليمات البرمجية، راجع تحميل كائن ثنائي كبير الحجم باستخدام JavaScript.

سرد الكائنات الثنائية كبيرة الحجم في حاوية

سرد الكائنات الثنائية كبيرة الحجم في الحاوية. تستدعي التعليمات البرمجية التالية أسلوب listBlobsFlat . في هذه الحالة، يوجد كائن ثنائي كبير الحجم واحد فقط في الحاوية، لذلك تقوم عملية الإدراج بإرجاع هذا الكائن الثنائي كبير الحجم فقط.

أضف هذه التعليمات البرمجية إلى الكتلة try:

  console.log('\nListing blobs...');

  for await (const blob of containerClient.listBlobsFlat()) {
    const tempBlockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blob.name);

    console.log(
      `\n\tname: ${blob.name}\n\tURL: ${tempBlockBlobClient.url}\n`
    );
  }

لمعرفة المزيد حول سرد الكائنات الثنائية كبيرة الحجم واستكشاف المزيد من نماذج التعليمات البرمجية، راجع سرد الكائنات الثنائية كبيرة الحجم باستخدام JavaScript.

تنزيل كائنات تخزين البيانات الثنائية الكبيرة

قم بتنزيل الكائن الثنائي كبير الحجم وعرض المحتويات. تستدعي التعليمات البرمجية التالية أسلوب التنزيل لتنزيل الكائن الثنائي كبير الحجم.

أضف هذه التعليمات البرمجية إلى الكتلة try:

  const offset = 0;         // start at beginning
  const length = undefined; // read all

  const downloadBlockBlobResponse: BlobDownloadResponseParsed = await blockBlobClient.download(offset, length);
  console.log('\nDownloaded blob content...');
  console.log(
    '\t',
    await streamToText(downloadBlockBlobResponse.readableStreamBody as NodeJS.ReadableStream)
  );

تقوم التعليمات البرمجية التالية بتحويل دفق مرة أخرى إلى سلسلة لعرض المحتويات.

أضف هذه التعليمة البرمجية بعد الدالة main :

// Convert stream to text
async function streamToText(readable: NodeJS.ReadableStream): Promise<string> {
  readable.setEncoding('utf8');
  let data = '';
  for await (const chunk of readable) {
    data += chunk;
  }
  return data;
}

لمعرفة المزيد حول تنزيل الكائنات الثنائية كبيرة الحجم واستكشاف المزيد من نماذج التعليمات البرمجية، راجع تنزيل كائن ثنائي كبير الحجم باستخدام JavaScript.

احذف حاوية

احذف الحاوية وجميع الكائنات الثنائية كبيرة الحجم داخل الحاوية. تنظف التعليمات البرمجية التالية الموارد التي أنشأها التطبيق عن طريق إزالة الحاوية بأكملها باستخدام أسلوب الحذف.

أضف هذه التعليمات البرمجية إلى الكتلة try:

  console.log('\nDeleting container...');

  const deleteContainerResponse: ContainerDeleteResponse = await containerClient.delete();
  console.log(
    'Container was deleted successfully. requestId: ',
    deleteContainerResponse.requestId
  );

لمعرفة المزيد حول حذف حاوية، واستكشاف المزيد من نماذج التعليمات البرمجية، راجع حذف حاوية كائن ثنائي كبير الحجم واستعادتها باستخدام JavaScript.

تشغيل التعليمات البرمجية

  1. من محطة Visual Studio Code الطرفية، أنشئ التطبيق.

    tsc

  2. تشغيل التطبيق.

    node dist/index.js

  3. يتشابه إخراج التطبيق مع المثال التالي:

    Azure Blob storage - JavaScript quickstart sample

Creating container...
    quickstart4a0780c0-fb72-11e9-b7b9-b387d3c488da

Uploading to Azure Storage as blob:
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Listing blobs...
    quickstart4a3128d0-fb72-11e9-b7b9-b387d3c488da.txt

Downloaded blob content...
    Hello, World!

Deleting container...
Done

انتقل إلى التعليمات البرمجية الموجودة في مصحح الأخطاء وتحقق من "مدخل Microsoft Azure" خلال العملية. تحقق لمعرفة أن الحاوية قيد الإنشاء. يمكنك فتح النقطة داخل الحاوية وعرض المحتويات.

تنظيف الموارد

  1. عند الانتهاء من هذا التشغيل السريع، احذف الدليل blob-quickstart.
  2. إذا انتهيت من استخدام مورد Azure Storage، فاستخدم Azure CLI لإزالة مورد Storage.

الخطوة التالية

نماذج Azure Storage وأدلة المطور ل JavaScript وTypeScript

  • Last updated on