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

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

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

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

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

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

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

الشروع

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

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

راجع سياسة الدعم الخاصة بنا لمزيد من التفاصيل.

Prerequisites

تثبيت الحزمة

الطريقة المفضلة لتثبيت مكتبة عميل 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 للحصول على مزيد من التفاصيل والعينات لبدء الاستخدام.

Compatibility

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

عمال الويب

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

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

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

الاختلافات بين 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 ثلاثة أنواع من الموارد:

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

Examples

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

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

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

import * as AzureStorageBlob from "@azure/storage-blob";

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

import { BlobServiceClient, StorageSharedKeyCredential } from "@azure/storage-blob";

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

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

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

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

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

تسجيل تطبيق AAD جديد ومنح أذونات للوصول إلى Azure Storage نيابة عن المستخدم الذي سجل الدخول
- تسجيل تطبيق جديد في Azure Active Directory (في مدخل microsoft azure) - https://learn.microsoft.com/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
- أدوار RBAC للكائنات الثنائية كبيرة الحجم وقوائم الانتظار - https://learn.microsoft.com/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).

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@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]

import { BlobServiceClient } from "@azure/storage-blob";

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

مع `StorageSharedKeyCredential`

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

import { StorageSharedKeyCredential, BlobServiceClient } from "@azure/storage-blob";

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

import { BlobServiceClient } from "@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() للحصول على مثيل عميل حاوية ثم إنشاء مورد حاوية جديد.

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

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

سرد الحاويات

استخدم الدالة BlobServiceClient.listContainers() لتكرار الحاويات، باستخدام بناء جملة for-await-of الجديد:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const containers = blobServiceClient.listContainers();
for await (const container of containers) {
  console.log(`Container ${i++}: ${container.name}`);
}

بدلا من ذلك دون استخدام for-await-of:

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
const iter = blobServiceClient.listContainers();
let { value, done } = await iter.next();
while (!done) {
  console.log(`Container ${i++}: ${value.name}`);
  ({ value, done } = await iter.next());
}

بالإضافة إلى ذلك، يتم دعم ترقيم الصفحات لإدراجه أيضا عبر byPage():

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

let i = 1;
for await (const page of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
  for (const container of page.containerItems) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

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

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

const content = "Hello world!";
const blobName = `newblob ${+new Date()}`;
const blockBlobClient = containerClient.getBlockBlobClient(blobName);
const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
console.log(
  `Upload block blob ${blobName} successfully with request ID: ${uploadBlobResponse.requestId}`,
);

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

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const containerClient = blobServiceClient.getContainerClient(containerName);

let i = 1;
const blobs = containerClient.listBlobsFlat();
for await (const blob of blobs) {
  console.log(`Blob ${i++}: ${blob.name}`);
}

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

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
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();
if (downloadBlockBlobResponse.readableStreamBody) {
  const downloaded = await streamToString(downloadBlockBlobResponse.readableStreamBody);
  console.log(`Downloaded blob content: ${downloaded}`);
}

async function streamToString(stream: NodeJS.ReadableStream): Promise<string> {
  const result = await new Promise<Buffer<ArrayBuffer>>((resolve, reject) => {
    const chunks: Buffer[] = [];
    stream.on("data", (data) => {
      chunks.push(Buffer.isBuffer(data) ? data : Buffer.from(data));
    });
    stream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    stream.on("error", reject);
  });
  return result.toString();
}

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

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

import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

const account = "<account>";
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  new DefaultAzureCredential(),
);

const containerName = "<container name>";
const blobName = "<blob name>";
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 blobBody = await downloadBlockBlobResponse.blobBody;
if (blobBody) {
  const downloaded = await blobBody.text();
  console.log(`Downloaded blob content: ${downloaded}`);
}

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

Troubleshooting

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

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

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

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

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

Contributing

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

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

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-10-17