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

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

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

  • تفترض الأمثلة في هذه المقالة أن لديك بالفعل مشروعا تم إعداده للعمل مع مكتبة عميل Azure Blob Storage ل JavaScript. للتعرف على إعداد مشروعك، بما في ذلك تثبيت الحزمة، واستيراد الوحدات النمطية، وإنشاء كائن عميل معتمد للعمل مع موارد البيانات، راجع بدء استخدام Azure Blob Storage وJavaScript.
  • يجب أن يكون لآلية التخويل أذونات لتنفيذ عملية تحميل. لمعرفة المزيد، راجع إرشادات التخويل لعمليات واجهة برمجة تطبيقات REST التالية:

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

يمكنك استخدام أي من الطرق التالية لتحميل البيانات إلى كائن ثنائي كبير الحجم للكتلة:

يمكن استدعاء كل من هذه الطرق باستخدام كائن BlockBlobClient .

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

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

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadBlobFromLocalPath(containerClient, blobName, localFilePath){
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath);
}

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

يقوم المثال التالي بتحميل كائن ثنائي كبير الحجم للكتلة عن طريق إنشاء دفق قابل للقراءة وتحميل الدفق:

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// readableStream: Readable stream, for example, a stream returned from fs.createReadStream()
async function uploadBlobFromReadStream(containerClient, blobName, readableStream) {
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload data to block blob using a readable stream
  await blockBlobClient.uploadStream(readableStream);
}

تحميل كائن ثنائي كبير الحجم للكتلة من مخزن مؤقت

يقوم المثال التالي بتحميل كائن ثنائي كبير الحجم للكتلة من مخزن مؤقت Node.js:

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// buffer: blob contents as a buffer, for example, from fs.readFile()
async function uploadBlobFromBuffer(containerClient, blobName, buffer) {

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload buffer
  await blockBlobClient.uploadData(buffer);
}

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

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

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// fileContentsAsString: blob content
async function uploadBlobFromString(containerClient, blobName, fileContentsAsString){
  
  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.upload(fileContentsAsString, fileContentsAsString.length);
}

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

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

تحديد خيارات نقل البيانات عند التحميل

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

الخاصية ‏‏الوصف
blockSize الحد الأقصى لحجم الكتلة المطلوب نقله لكل طلب كجزء من عملية التحميل.
concurrency الحد الأقصى لعدد الطلبات المتوازية التي يتم إصدارها في أي وقت كجزء من نقل مواز واحد.
maxSingleShotSize إذا كان حجم البيانات أقل من هذه القيمة أو مساويا لها، يتم تحميلها في وضع واحد بدلا من تقسيمها إلى مجموعات. إذا تم تحميل البيانات في لقطة واحدة، يتم تجاهل حجم الكتلة. القيمة الافتراضية هي 256 ميبي بايت.

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

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithTransferOptions(containerClient, blobName, localFilePath) {
  
  // Specify data transfer options
  const uploadOptions = {
    blockSize: 4 * 1024 * 1024, // 4 MiB max block size
    concurrency: 2, // maximum number of parallel transfer workers
    maxSingleShotSize: 8 * 1024 * 1024, // 8 MiB initial transfer size
  } 

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob with transfer options
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

لمعرفة المزيد حول خيارات ضبط نقل البيانات، راجع ضبط الأداء للتحميلات والتنزيلات باستخدام JavaScript.

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

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

يقوم المثال التالي بتحميل كائن ثنائي كبير الحجم للكتلة مع تعيين علامات الفهرس باستخدام BlockBlobParallelUploadOptions:

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithIndexTags(containerClient, blobName, localFilePath) {
  
  // Specify index tags for blob
  const uploadOptions = {
    tags: {
      'Sealed': 'false',
      'Content': 'image',
      'Date': '2022-07-18',
    }
  }

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob with index tags
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

تعيين طبقة وصول كائن ثنائي كبير الحجم عند التحميل

يمكنك تعيين طبقة وصول كائن ثنائي كبير الحجم عند التحميل باستخدام واجهة BlockBlobParallelUploadOptions . يوضح مثال التعليمات البرمجية التالي كيفية تعيين طبقة الوصول عند تحميل كائن ثنائي كبير الحجم:

// containerClient: ContainerClient object
// blobName: string, includes file extension if provided
// localFilePath: fully qualified path and file name
async function uploadWithAccessTier(containerClient, blobName, localFilePath) {
  
  // Specify access tier
  const uploadOptions = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    tier: 'Cool',
  }

  // Create blob client from container client
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);

  // Upload blob to cool tier
  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

يسمح بتعيين طبقة الوصول فقط لكتل الكائنات الثنائية كبيرة الحجم. يمكنك تعيين طبقة الوصول لكتلة كائن ثنائي كبير الحجم إلى Hotأو CoolColdأو أو Archive. لتعيين مستوى الوصول إلى Cold، يجب استخدام الحد الأدنى لإصدار مكتبة العميل من 12.13.0.

لمعرفة المزيد حول مستويات الوصول، راجع نظرة عامة على مستويات الوصول.

الموارد

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

عمليات واجهة برمجة تطبيقات REST

يحتوي Azure SDK ل JavaScript على مكتبات تستند إلى واجهة برمجة تطبيقات AZURE REST، ما يسمح لك بالتفاعل مع عمليات REST API من خلال نماذج JavaScript المألوفة. تستخدم أساليب مكتبة العميل لتحميل الكائنات الثنائية كبيرة الحجم عمليات واجهة برمجة تطبيقات REST التالية:

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

عرض نماذج التعليمات البرمجية من هذه المقالة (GitHub):

موارد مكتبة العميل

(راجع أيضًا )

  • هذه المقالة هي جزء من دليل مطور Blob Storage ل JavaScript/Typescript. لمعرفة المزيد، راجع القائمة الكاملة لمقالات دليل المطور في إنشاء تطبيق JavaScript/Typescript.