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

• NET.
• Java
• JavaScript
• Python
• ذهب

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

تستخدم أساليب مكتبة العميل المغطاة في هذه المقالة عملية Copy Blob REST API، ويمكن استخدامها عندما تريد إجراء نسخة بجدولة غير متزامنة. بالنسبة لمعظم سيناريوهات النسخ حيث تريد نقل البيانات إلى حساب تخزين ولديك عنوان URL للكائن المصدر، راجع نسخ كائن ثنائي كبير الحجم من عنوان URL للكائن المصدر باستخدام JavaScript.

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

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

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

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

Copy Blob يمكن لعملية تنفيذ أي من الإجراءات التالية:

• انسخ الكائن الثنائي كبير الحجم الخاص بالمصدر إلى كائن ثنائي كبير الحجم في الوجهة باسم مختلف. يمكن أن يكون الكائن الثنائي كبير الحجم الوجهة كائن ثنائي كبير الحجم موجود من نفس نوع الكائن الثنائي كبير الحجم (كتلة أو إلحاق أو صفحة)، أو يمكن أن يكون كائنا ثنائيا جديدا تم إنشاؤه بواسطة عملية النسخ.
• انسخ كائن ثنائي كبير الحجم المصدر إلى كائن ثنائي كبير الحجم الوجهة بنفس الاسم، والذي يحل محل الكائن الثنائي كبير الحجم الوجهة. يزيل هذا النوع من عمليات النسخ أي كتل غير ملتزمة ويستبدل بيانات تعريف الكائن الثنائي كبير الحجم الوجهة.
• انسخ ملف مصدر في خدمة Azure File إلى كائن ثنائي كبير الحجم في الوجهة. يمكن أن يكون الكائن الثنائي كبير الحجم في الوجهة كائنًا ثنائيًّا كبير الحجم لكتلة موجودة، أو يمكن أن يكون كائناً ثنائياً كبير الحجم لكتلة جديدة تم إنشاؤه من خلال عملية النسخ. النسخ من الملفات إلى الكائنات الثنائية كبيرة الحجم للصفحة أو الكائنات الثنائية كبيرة الحجم للإلحاق غير مدعوم.
• انسخ لقطة فوق الكائن الثنائي كبير الحجم الأساسي الخاص بها. من خلال ترقية لقطة إلى موضع الكائن الثنائي كبير الحجم الأساسي، يمكنك استعادة إصدار سابق من كائن ثنائي كبير الحجم.
• انسخ لقطة إلى كائن ثنائي كبير الحجم في الوجهة باسم مختلف. يكون الكائن الثنائي كبير الحجم في الوجهة الناتج عبارة عن كائن ثنائي كبير الحجم قابل للكتابة وليس لقطة.

لمعرفة المزيد حول العملية، بما في Copy Blob ذلك معلومات حول الخصائص وعلامات الفهرس وبيانات التعريف والفوترة، راجع نسخ ملاحظات Blob.

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

يقدم هذا القسم نظرة عامة على الأساليب التي توفرها مكتبة عميل Azure Storage ل JavaScript لتنفيذ عملية نسخ بجدولة غير متزامنة.

تلتف الأساليب التالية عملية Copy Blob REST API، وتبدأ نسخة غير متزامنة من البيانات من الكائن الثنائي كبير الحجم المصدر:

• BlobClient.beginCopyFromURL

يقوم beginCopyFromURL الأسلوب بإرجاع استقصاء عملية طويلة الأمد يسمح لك بالانتظار إلى أجل غير مسمى حتى تكتمل النسخة.

نسخ كائن ثنائي كبير الحجم من مصدر داخل Azure

إذا كنت تقوم بنسخ كائن ثنائي كبير الحجم داخل نفس حساب التخزين، يمكن أن تكتمل العملية بشكل متزامن. يمكن التصريح بالوصول إلى الكائن الثنائي كبير الحجم المصدر عبر معرف Microsoft Entra أو توقيع وصول مشترك (SAS) أو مفتاح حساب. لعملية نسخ متزامنة تبديلية، راجع نسخ كائن ثنائي كبير الحجم من عنوان URL لكائن مصدر باستخدام JavaScript.

إذا كان مصدر النسخ كائن ثنائي كبير الحجم في حساب تخزين مختلف، يمكن أن تكتمل العملية بشكل غير متزامن. يجب أن يكون الكائن الثنائي كبير الحجم المصدر عاما أو مخولا عبر رمز SAS المميز. يحتاج رمز SAS المميز إلى تضمين إذن القراءة ('r'). لمعرفة المزيد حول رموز SAS المميزة، راجع تفويض الوصول باستخدام توقيعات الوصول المشتركة.

يوضح المثال التالي سيناريو لنسخ كائن ثنائي كبير الحجم المصدر من حساب تخزين مختلف بجدولة غير متزامنة. في هذا المثال، نقوم بإنشاء عنوان URL للكائن الثنائي كبير الحجم المصدر مع رمز SAS لتفويض المستخدم الملحق. يوضح المثال كيفية إنشاء رمز SAS المميز باستخدام مكتبة العميل، ولكن يمكنك أيضا توفير رمز SAS الخاص بك. يوضح المثال أيضا كيفية تأجير الكائن الثنائي كبير الحجم المصدر أثناء عملية النسخ لمنع التغييرات على الكائن الثنائي كبير الحجم من عميل مختلف. تحفظ Copy Blob ETag العملية قيمة الكائن الثنائي كبير الحجم المصدر عند بدء عملية النسخ. ETag إذا تم تغيير القيمة قبل انتهاء عملية النسخ، تفشل العملية.

JavaScript

async function copyAcrossStorageAccountsAsync(sourceBlob, destinationBlob, blobServiceClient) {
  
  // Lease the source blob to prevent changes during the copy operation
  const sourceBlobLease = new BlobLeaseClient(sourceBlob);

  // Create a SAS token that's valid for 1 hour
  const sasToken = await generateUserDelegationSAS(sourceBlob, blobServiceClient);
  const sourceBlobSASURL = sourceBlob.url + "?" + sasToken;

  try {
    await sourceBlobLease.acquireLease(-1);

    // Start the copy operation and wait for it to complete
    const copyPoller = await destinationBlob.beginCopyFromURL(sourceBlobSASURL);
    await copyPoller.pollUntilDone();
  } catch (error) {
    // Handle the exception
  } finally {
    // Release the lease once the copy operation completes
    await sourceBlobLease.releaseLease();
  }
}

async function generateUserDelegationSAS(sourceBlob, blobServiceClient) {
  
  // Get a user delegation key for the Blob service that's valid for 1 hour, as an example
  const delegationKeyStart = new Date();
  const delegationKeyExpiry = new Date(Date.now() + 3600000);
  const userDelegationKey = await blobServiceClient.getUserDelegationKey(
    delegationKeyStart,
    delegationKeyExpiry
  );

  // Create a SAS token that's valid for 1 hour, as an example
  const sasTokenStart = new Date();
  const sasTokenExpiry = new Date(Date.now() + 3600000);
  const blobName = sourceBlob.name;
  const containerName = sourceBlob.containerName;
  const sasOptions = {
    blobName,
    containerName,
    permissions: BlobSASPermissions.parse("r"),
    startsOn: sasTokenStart,
    expiresOn: sasTokenExpiry,
    protocol: SASProtocol.HttpsAndHttp
  };

  const sasToken = generateBlobSASQueryParameters(
    sasOptions,
    userDelegationKey,
    blobServiceClient.accountName
  ).toString();

  return sasToken.toString();
}

TypeScript

async function copyAcrossStorageAccountsAsync(
  sourceBlob: BlockBlobClient,
  destinationBlob: BlockBlobClient,
  blobServiceClient: BlobServiceClient
): Promise<void> {
  const sourceBlobLease = new BlobLeaseClient(sourceBlob);

  // Create a SAS token that's valid for 1 hour
  const sasToken = await generateUserDelegationSAS(sourceBlob, blobServiceClient);
  const sourceBlobSASURL: string = sourceBlob.url + '?' + sasToken;

  try {
    await sourceBlobLease.acquireLease(-1);

    const copyPoller = await destinationBlob.beginCopyFromURL(sourceBlobSASURL);
    await copyPoller.pollUntilDone();
  } catch (error) {
    console.log(error);
  } finally {
    await sourceBlobLease.releaseLease();
  }
}

async function generateUserDelegationSAS(
  sourceBlob: BlockBlobClient,
  blobServiceClient: BlobServiceClient
): Promise<string> {
  // Get a user delegation key for the Blob service that's valid for 1 hour, as an example
  const delegationKeyStart = new Date();
  const delegationKeyExpiry = new Date(Date.now() + 3600000);
  const userDelegationKey = await blobServiceClient.getUserDelegationKey(
    delegationKeyStart,
    delegationKeyExpiry
  );

  // Create a SAS token that's valid for 1 hour, as an example
  const sasTokenStart = new Date();
  const sasTokenExpiry = new Date(Date.now() + 3600000);
  const blobName = sourceBlob.name;
  const containerName = sourceBlob.containerName;
  const sasOptions = {
    blobName,
    containerName,
    permissions: BlobSASPermissions.parse("r"),
    startsOn: sasTokenStart,
    expiresOn: sasTokenExpiry,
    protocol: SASProtocol.HttpsAndHttp
  };

  const sasToken = generateBlobSASQueryParameters(
    sasOptions,
    userDelegationKey,
    blobServiceClient.accountName
  ).toString();

  return sasToken.toString();
}

إشعار

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

نسخ كائن ثنائي كبير الحجم من مصدر خارج Azure

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

JavaScript

async function copyFromExternalSource(sourceURL, destinationBlob) {
  
  const copyPoller = await destinationBlob.beginCopyFromURL(sourceURL);
  await copyPoller.pollUntilDone();
}

TypeScript

async function copyFromExternalSource(sourceURL: string,
  destinationBlob: BlockBlobClient
): Promise<void> {
  try {
    const copyPoller = await destinationBlob.beginCopyFromURL(sourceURL);
    await copyPoller.pollUntilDone();
  } catch (error) {
    console.log(error);
  }
}

التحقق من حالة عملية النسخ

للتحقق من حالة عملية غير متزامنة Copy Blob ، يمكنك التحقق من أسلوب getProperties والتحقق من حالة النسخ.

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

JavaScript

async function checkCopyStatus(destinationBlob) {
  
  const properties = await destinationBlob.getProperties();
  console.log(properties.copyStatus);
}

TypeScript

async function checkCopyStatus(destinationBlob: BlockBlobClient): Promise<void> {
  const properties = await destinationBlob.getProperties();
  console.log(properties.copyStatus);
}

إجهاض عملية نسخ

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

لإجهاض عملية نسخ معلقة، قم باستدعاء العملية التالية:

• BlobClient.abortCopyFromURL

يلتف هذا الأسلوب عملية Abort Copy Blob REST API، والتي تلغي عملية معلقة Copy Blob . يوضح مثال التعليمات البرمجية التالي كيفية إجهاض عملية معلقة Copy Blob :

JavaScript

async function abortCopy(destinationBlob) {
  
  const properties = await destinationBlob.getProperties();

  // Check the copy status and abort if pending
  if (properties.copyStatus === "pending") {
    await destinationBlob.abortCopyFromURL(properties.copyId);
  }
}

TypeScript

async function abortCopy(destinationBlob: BlockBlobClient): Promise<void> {
  const properties = await destinationBlob.getProperties();

  // Check the copy status and abort if pending
  if (properties.copyStatus === "pending") {
    await destinationBlob.abortCopyFromURL(properties.copyId?.toString()!);
  }
}

الموارد

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

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

• عرض نماذج التعليمات البرمجية JavaScript وTypeScript من هذه المقالة (GitHub)

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

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

• نسخ Blob (REST API)
• إجهاض نسخ Blob (REST API)

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

• الوثائق المرجعية لمكتبة العميل
• التعليمات البرمجية لمصدر مكتبة عميل
• الحزمة (npm)

المحتوى ذو الصلة

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