Копирование большого двоичного объекта с асинхронным планированием с помощью JavaScript или TypeScript

• .NET
• Java
• JavaScript
• Python
• Go

В этой статье показано, как скопировать большой двоичный объект с асинхронным планированием с помощью клиентской библиотеки служба хранилища Azure для JavaScript. Большой двоичный объект можно скопировать из источника в той же учетной записи хранения, из источника в другой учетной записи хранения или из любого доступного объекта, полученного через HTTP-запрос GET по указанному URL-адресу. Кроме того, можно прервать ожидающие операции копирования.

Методы клиентской библиотеки, описанные в этой статье, используют операцию REST API копирования BLOB-объектов и могут использоваться при выполнении копирования с асинхронным планированием. В большинстве сценариев копирования, в которых требуется переместить данные в учетную запись хранения и получить URL-адрес исходного объекта, см. статью "Копирование большого двоичного объекта из URL-адреса исходного объекта с помощью JavaScript".

Необходимые компоненты

• В примерах этой статьи предполагается, что у вас уже есть проект, настроенный для работы с клиентской библиотекой Хранилище BLOB-объектов Azure для JavaScript. Сведения о настройке проекта, включая установку пакетов, импорт модулей и создание авторизованного клиентского объекта для работы с ресурсами данных, см. в статье "Начало работы с Хранилище BLOB-объектов Azure и JavaScript".
• Механизм авторизации должен иметь разрешения на выполнение операции копирования или прерывание ожидающей копии. Дополнительные сведения см. в руководстве по авторизации для следующей операции REST API:
  • Copy Blob
  • Прерывание копирования большого двоичного объекта

О копировании больших двоичных объектов с помощью асинхронного планирования

Операция Copy Blob может завершиться асинхронно и выполняется на основе наилучших усилий, что означает, что операция не гарантируется немедленно или завершена в течение указанного интервала времени. Операция копирования запланирована в фоновом режиме и выполняется, так как сервер имеет доступные ресурсы. Операция может выполняться синхронно, если копия происходит в той же учетной записи хранения.

Операция Copy Blob может выполнять любое из следующих действий:

• Копирование исходного большого двоичного объекта в целевой большой двоичный объект с другим именем. Целевой большой двоичный объект может быть существующим BLOB-объектом одного типа (блокировать, добавить или страницу) или быть новым BLOB-объектом, созданным операцией копирования.
• Скопируйте исходный большой двоичный объект в целевой большой двоичный объект с тем же именем, который заменяет целевой большой двоичный объект. Этот тип операции копирования удаляет все незафиксированные блоки и перезаписывает метаданные целевого BLOB-объекта.
• Копирование исходного файла из службы файлов Azure в целевой большой двоичный объект. Целевым большим двоичным объектом может быть существующий блочный BLOB-объект или новый блочный BLOB-объект, созданный операцией копирования. Копирование из файлов в страничные большие двоичные объекты или добавление больших двоичных объектов не поддерживается.
• Копирование моментального снимка поверх его базового большого двоичного объекта. Повысив уровень моментального снимка до базового большого двоичного объекта, можно восстановить более раннюю версию большого двоичного объекта.
• Копирование моментального снимка в целевой большой двоичный объект с другим именем. Результирующий целевой большой двоичный объект не станет моментальным снимком, а будет большим двоичным объектом, доступным для записи.

Дополнительные сведения об операции, включая сведения о свойствах, тегах индекса, метаданных и выставлении счетов, см. в примечаниях Copy Blobкопирования BLOB-объектов.

Копирование большого двоичного объекта с асинхронным планированием

В этом разделе представлен обзор методов, предоставляемых клиентской библиотекой служба хранилища Azure для JavaScript для выполнения операции копирования с асинхронным планированием.

Следующие методы упаковывают операцию REST API копирования BLOB-объектов и начинают асинхронную копию данных из исходного BLOB-объекта:

• BlobClient.beginCopyFromURL

Метод beginCopyFromURL возвращает длительный опрашиватель операций, позволяющий ждать неограниченное время, пока копия не будет завершена.

Копирование большого двоичного объекта из источника в Azure

Если вы копируете большой двоичный объект в той же учетной записи хранения, операция может выполняться синхронно. Доступ к исходному BLOB-объекту можно авторизовать с помощью идентификатора Microsoft Entra, подписанного URL-адресом (SAS) или ключа учетной записи. Сведения об изменении синхронной операции копирования см. в разделе "Копирование большого двоичного объекта" из URL-адреса исходного объекта с помощью JavaScript.

Если источник копирования является большим двоичным объектом в другой учетной записи хранения, операция может выполняться асинхронно. Исходный большой двоичный объект должен быть общедоступным или авторизованным с помощью маркера SAS. Маркер SAS должен включать разрешение read ('r'). Дополнительные сведения о маркерах SAS см. в статье "Делегирование доступа с подписанными URL-адресами".

В следующем примере показан сценарий копирования исходного большого двоичного объекта из другой учетной записи хранения с асинхронным планированием. В этом примере мы создадим URL-адрес исходного BLOB-объекта с добавленным маркером 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()!);
  }
}

Ресурсы

Дополнительные сведения о копировании больших двоичных объектов с асинхронным планированием с помощью клиентской библиотеки Хранилище BLOB-объектов Azure для JavaScript см. в следующих ресурсах.

Примеры кода

• Просмотр примеров кода JavaScript и TypeScript из этой статьи (GitHub)

Операции REST API

Пакет SDK Azure для JavaScript содержит библиотеки, которые создаются на основе REST API Azure, что позволяет взаимодействовать с операциями REST API через знакомые парадигмы JavaScript. Методы клиентской библиотеки, описанные в этой статье, используют следующие операции REST API:

• Копирование BLOB-объектов (REST API)
• Прерывание копирования BLOB-объекта (REST API)

Ресурсы клиентской библиотеки

• Справочная документация по клиентской библиотеке
• Исходный код клиентской библиотеки
• Пакет (npm)

Связанный контент

• Эта статья является частью руководства разработчика хранилища BLOB-объектов для JavaScript/TypeScript. Дополнительные сведения см. в полном списке статей руководства разработчика по созданию приложения JavaScript и TypeScript.