مكتبة عميل Azure Storage Blob ل JavaScript - الإصدار 12.24.0

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

يوفر هذا المشروع مكتبة عميل في JavaScript تسهل استخدام خدمة Microsoft Azure Storage Blob.

استخدم مكتبات العميل في هذه الحزمة من أجل:

• الحصول على/تعيين خصائص خدمة Blob
• إنشاء/قائمة/حذف حاويات
• إنشاء/قراءة/قائمة/تحديث/حذف الكائنات الثنائية كبيرة الحجم للكتلة
• إنشاء/قراءة/قائمة/تحديث/حذف الكائنات الثنائية كبيرة الحجم للصفحة
• إنشاء/قراءة/قائمة/تحديث/حذف الكائنات الثنائية كبيرة الحجم للإلحاق

الارتباطات الرئيسية

• التعليمات البرمجية المصدر
• حزمة (npm)
• الوثائق المرجعية لواجهة برمجة التطبيقات
• وثائق Product
• عينات
• واجهات برمجة تطبيقات Azure Storage Blob REST

الشروع

البيئات المدعومة حاليا

• إصدارات LTS من Node.js
• أحدث إصدارات Safari وChrome وEdge وFirefox.

راجع نهج دعم للحصول على مزيد من التفاصيل.

المتطلبات المسبقه

• اشتراك Azure
• حساب تخزين

تثبيت الحزمة

الطريقة المفضلة لتثبيت مكتبة عميل Azure Storage Blob ل JavaScript هي استخدام مدير حزمة npm. اكتب ما يلي في نافذة طرفية:

npm install @azure/storage-blob

مصادقة العميل

يدعم Azure Storage عدة طرق للمصادقة. للتفاعل مع خدمة Azure Blob Storage، ستحتاج إلى إنشاء مثيل لعميل التخزين - BlobServiceClientأو ContainerClientأو BlobClient على سبيل المثال. راجع نماذج لإنشاء BlobServiceClient لمعرفة المزيد حول المصادقة.

• Azure Active Directory
• المفتاح المشترك
• توقيعات الوصول المشترك

Azure Active Directory

تدعم خدمة Azure Blob Storage استخدام Azure Active Directory لمصادقة الطلبات على واجهات برمجة التطبيقات الخاصة بها. توفر حزمة @azure/identity مجموعة متنوعة من أنواع بيانات الاعتماد التي يمكن للتطبيق الخاص بك استخدامها للقيام بذلك. يرجى الاطلاع على README للحصول على @azure/identity للحصول على مزيد من التفاصيل والعينات لبدء الاستخدام.

التوافق

تتوافق هذه المكتبة مع Node.js والمستعرضات، وتم التحقق من صحتها مقابل إصدارات LTS Node.js (>=8.16.0) وأحدث إصدارات Chrome وFirefox وEdge.

عمال الويب

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

لمزيد من المعلومات، يرجى الرجوع إلى وثائق لاستخدام Azure SDK ل JS في Web Workers

تعتمد هذه المكتبة على واجهات برمجة التطبيقات DOM التالية التي تحتاج إلى ملفات تعريف خارجية محملة عند استخدامها في عمال الويب:

• document
• DOMParser
• Node
• XMLSerializer

الاختلافات بين Node.js والمستعرضات

هناك اختلافات بين وقت تشغيل Node.js والمستعرضات. عند بدء استخدام هذه المكتبة، انتبه إلى واجهات برمجة التطبيقات أو الفئات المميزة "متوفر فقط في وقت تشغيل NODE.JS" أو "متوفر فقط في المستعرضات".

• إذا كان الكائن الثنائي كبير الحجم يحتوي على بيانات مضغوطة بتنسيق gzip أو deflate وتم تعيين ترميز محتواه وفقا لذلك، فإن سلوك التنزيل يختلف بين Node.js والمستعرضات. في Node.js سيقوم عملاء التخزين بتنزيل الكائن الثنائي كبير الحجم بتنسيقه المضغوط، بينما في المستعرضات سيتم تنزيل البيانات بتنسيق غير مضغوط.

الميزات أو الواجهات أو الفئات أو الوظائف المتوفرة فقط في Node.js

• تخويل المفتاح المشترك استنادا إلى اسم الحساب ومفتاح الحساب
  • StorageSharedKeyCredential
• إنشاء توقيع الوصول المشترك (SAS)
  • generateAccountSASQueryParameters()
  • generateBlobSASQueryParameters()
• التحميل والتنزيل المتوازي. لاحظ أن BlockBlobClient.uploadData() متوفر في كل من Node.js والمستعرضات.
  • BlockBlobClient.uploadFile()
  • BlockBlobClient.uploadStream()
  • BlobClient.downloadToBuffer()
  • BlobClient.downloadToFile()

الميزات أو الواجهات أو الفئات أو الوظائف المتوفرة فقط في المستعرضات

• التحميل والتنزيل المتوازي
  • BlockBlobClient.uploadBrowserData()

حزمة JavaScript

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

CORS

تحتاج إلى إعداد قواعد مشاركة الموارد عبر المنشأ (CORS) لحساب التخزين الخاص بك إذا كنت بحاجة إلى التطوير للمتصفحات. انتقل إلى مدخل Microsoft Azure ومستكشف تخزين Azure، وابحث عن حساب التخزين الخاص بك، وأنشئ قواعد CORS جديدة ل blob/queue/file/table service(s).

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

• الأصول المسموح بها: *
• الأفعال المسموح بها: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
• الرؤوس المسموح بها: *
• الرؤوس المكشوفة: *
• الحد الأقصى للعمر (بالثوان): 86400

المفاهيم الرئيسية

تم تصميم تخزين Blob من أجل:

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

يوفر تخزين Blob ثلاثة أنواع من الموارد:

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

امثله

• استيراد الحزمة
• إنشاء عميل خدمة الكائن الثنائي كبير الحجم
• إنشاء حاوية جديدة
• سرد الحاويات
• إنشاء كائن ثنائي كبير الحجم عن طريق تحميل البيانات
• قائمة الكائنات الثنائية كبيرة الحجم داخل حاوية
• تنزيل كائن ثنائي كبير الحجم وتحويله إلى سلسلة (Node.js)
• تنزيل كائن ثنائي كبير الحجم وتحويله إلى سلسلة (مستعرضات)

استيراد الحزمة

لاستخدام العملاء، قم باستيراد الحزمة إلى ملفك:

const AzureStorageBlob = require("@azure/storage-blob");

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

const { BlobServiceClient, StorageSharedKeyCredential } = require("@azure/storage-blob");

إنشاء عميل خدمة كائن ثنائي كبير الحجم

يتطلب BlobServiceClient عنوان URL لخدمة الكائن الثنائي كبير الحجم وبيانات اعتماد الوصول. كما يقبل اختياريا بعض الإعدادات في المعلمة options.

مع DefaultAzureCredential من حزمة @azure/identity

الطريقة الموصى بها لإنشاء مثيل BlobServiceClient

الإعداد: مرجع - تخويل الوصول إلى الكائنات الثنائية كبيرة الحجم وقوائم الانتظار باستخدام Azure Active Directory من تطبيق عميل - /azure/storage/common/storage-auth-aad-app

• تسجيل تطبيق AAD جديد ومنح أذونات للوصول إلى Azure Storage نيابة عن المستخدم الذي سجل الدخول

  • تسجيل تطبيق جديد في Azure Active Directory (في مدخل Azure) - /azure/active-directory/develop/quickstart-register-app
  • في قسم API permissions، حدد Add a permission واختر Microsoft APIs.
  • اختر Azure Storage وحدد خانة الاختيار بجوار user_impersonation ثم انقر فوق Add permissions. سيسمح هذا للتطبيق بالوصول إلى Azure Storage نيابة عن المستخدم الذي سجل الدخول.

• منح حق الوصول إلى بيانات Azure Blob باستخدام RBAC في مدخل Microsoft Azure

  • أدوار التحكم في الوصول استنادا إلى الدور للكائنات الثنائية كبيرة الحجم وقوائم الانتظار - /azure/storage/common/storage-auth-aad-rbac-portal.
  • في مدخل Microsoft Azure، انتقل إلى حساب التخزين الخاص بك وقم بتعيين دور Storage Blob Data Contributor لتطبيق AAD المسجل من علامة التبويب Access control (IAM) (في شريط التنقل الأيسر لحساب التخزين الخاص بك في مدخل Microsoft Azure).

• إعداد البيئة للعينة

  • من صفحة النظرة العامة لتطبيق AAD الخاص بك، دون CLIENT IDTENANT ID. في علامة التبويب "Certificates & Secrets"، قم بإنشاء سر ولاحظ ذلك لأسفل.
  • تأكد من أن لديك AZURE_TENANT_ID، AZURE_CLIENT_ID، AZURE_CLIENT_SECRET كمتغيرات بيئة لتنفيذ النموذج بنجاح (يمكن الاستفادة من 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
);

راجع عينة مصادقة Microsoft Azure Active Directory للحصول على مثال كامل باستخدام هذا الأسلوب.

[ملاحظة - الخطوات أعلاه مخصصة فقط Node.js]

استخدام سلسلة الاتصال

بدلا من ذلك، يمكنك إنشاء مثيل BlobServiceClient باستخدام الأسلوب الثابت fromConnectionString() مع سلسلة الاتصال الكاملة كوسيطة. (يمكن الحصول على سلسلة الاتصال من مدخل Azure.) [متوفر فقط في وقت تشغيل NODE.JS]

const { BlobServiceClient } = require("@azure/storage-blob");

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

مع StorageSharedKeyCredential

بدلا من ذلك، يمكنك إنشاء مثيل BlobServiceClient باستخدام StorageSharedKeyCredential عن طريق تمرير اسم الحساب ومفتاح الحساب كوسيطات. (يمكن الحصول على اسم الحساب ومفتاح الحساب من مدخل Microsoft Azure.) [متوفر فقط في وقت تشغيل 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
);

مع رمز SAS المميز

يمكنك أيضا إنشاء مثيل BlobServiceClient بتوقيعات وصول مشتركة (SAS). يمكنك الحصول على رمز SAS المميز من مدخل Microsoft Azure أو إنشاء رمز باستخدام 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}`);

إنشاء حاوية جديدة

استخدم BlobServiceClient.getContainerClient() للحصول على مثيل عميل حاوية ثم إنشاء مورد حاوية جديد.

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();

سرد الحاويات

استخدم الدالة BlobServiceClient.listContainers() لتكرار الحاويات، باستخدام بناء جملة 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();

بدلا من ذلك دون استخدام 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();

بالإضافة إلى ذلك، يتم دعم ترقيم الصفحات لإدراجه أيضا عبر 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();

للحصول على عينة كاملة حول الحاويات التكرارية، يرجى مراجعة samples/v12/typescript/src/listContainers.ts.

إنشاء كائن ثنائي كبير الحجم عن طريق تحميل البيانات

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();

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

على غرار سرد الحاويات.

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();

للحصول على عينة كاملة حول تكرار الكائنات الثنائية كبيرة الحجم، يرجى الاطلاع على عينات /v12/typescript/src/listBlobsFlat.ts.

تنزيل كائن ثنائي كبير الحجم وتحويله إلى سلسلة (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();

قم بتنزيل كائن ثنائي كبير الحجم وتحويله إلى سلسلة (المستعرضات).

يرجى الرجوع إلى قسم حزمة JavaScript للحصول على مزيد من المعلومات حول استخدام هذه المكتبة في المستعرض.

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();

مثال كامل على السيناريوهات البسيطة في samples/v12/typescript/src/sharedKeyAuth.ts.

استكشاف الاخطاء

قد يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. لمشاهدة سجل طلبات واستجابات HTTP، قم بتعيين متغير البيئة AZURE_LOG_LEVEL إلى info. بدلا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق استدعاء setLogLevel في @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

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

المزيد من نماذج التعليمات البرمجية:

• Blob Storage Samples (JavaScript)
• Blob Storage Samples (TypeScript)
• حالات اختبار تخزين الكائن الثنائي كبير الحجم

المساهمه

إذا كنت ترغب في المساهمة في هذه المكتبة، فيرجى قراءة دليل المساهمة لمعرفة المزيد حول كيفية إنشاء التعليمات البرمجية واختبارها.

راجع أيضا دليل التخزين المحدد للحصول على معلومات إضافية حول إعداد بيئة الاختبار لمكتبات التخزين.

مرات الظهور