Sdílet prostřednictvím

Kopírování objektu blob s asynchronním plánováním pomocí TypeScriptu

  • Článek

Tento článek ukazuje, jak zkopírovat objekt blob s asynchronním plánováním pomocí klientské knihovny Azure Storage pro JavaScript. Objekt blob můžete zkopírovat ze zdroje ve stejném účtu úložiště, ze zdroje v jiném účtu úložiště nebo z libovolného přístupného objektu načteného prostřednictvím požadavku HTTP GET na dané adrese URL. Můžete také přerušit čekající operaci kopírování.

Metody klientské knihovny popsané v tomto článku používají operaci copy blob REST API a lze ji použít, když chcete provést kopírování s asynchronním plánováním. Ve většině scénářů kopírování, ve kterých chcete přesunout data do účtu úložiště a mít adresu URL zdrojového objektu, najdete v tématu Kopírování objektu blob ze zdrojové adresy URL objektu pomocí TypeScriptu.

Předpoklady

  • Příklady v tomto článku předpokládají, že už máte projekt nastavený tak, aby fungoval s klientskou knihovnou Azure Blob Storage pro JavaScript. Další informace o nastavení projektu, včetně instalace balíčku, importu modulů a vytvoření autorizovaného klientského objektu pro práci s datovými prostředky, najdete v tématu Začínáme se službou Azure Blob Storage a TypeScriptem.
  • Autorizační mechanismus musí mít oprávnění k provedení operace kopírování nebo k přerušení čekající kopie. Další informace najdete v pokynech k autorizaci pro následující operaci rozhraní REST API:

Kopírování objektů blob pomocí asynchronního plánování

Operace Copy Blob se může dokončit asynchronně a provádí se na základě maximálního úsilí, což znamená, že není zaručeno, že se operace spustí okamžitě nebo dokončí v zadaném časovém rámci. Operace kopírování se naplánuje na pozadí a provede se tak, jak má server dostupné prostředky. Operace může být dokončena synchronně, pokud se kopie vyskytuje ve stejném účtu úložiště.

Copy Blob Operace může provádět některou z následujících akcí:

  • Zkopírujte zdrojový objekt blob do cílového objektu blob s jiným názvem. Cílovým objektem blob může být existující objekt blob stejného typu objektu blob (blok, připojení nebo stránka), nebo může být novým objektem blob vytvořeným operací kopírování.
  • Zkopírujte zdrojový objekt blob do cílového objektu blob se stejným názvem, který nahradí cílový objekt blob. Tento typ operace kopírování odebere všechny nepotvrzené bloky a přepíše metadata cílového objektu blob.
  • Zkopírujte zdrojový soubor ve službě Azure File Service do cílového objektu blob. Cílovým objektem blob může být existující objekt blob bloku nebo může být nový objekt blob bloku vytvořený operací kopírování. Kopírování ze souborů do objektů blob stránky nebo doplňovacích objektů blob se nepodporuje.
  • Zkopírujte snímek nad jeho základní objekt blob. Zvýšením úrovně snímku na pozici základního objektu blob můžete obnovit starší verzi objektu blob.
  • Zkopírujte snímek do cílového objektu blob s jiným názvem. Výsledný cílový objekt blob je zapisovatelný objekt blob, nikoli snímek.

Další informace o Copy Blob operaci, včetně informací o vlastnostech, značkách indexu, metadatech a fakturaci, najdete v tématu Kopírování poznámek k objektům blob.

Kopírování objektu blob s asynchronním plánováním

Tato část poskytuje přehled metod poskytovaných klientskou knihovnou Azure Storage pro JavaScript a TypeScript k provedení operace kopírování s asynchronním plánováním.

Následující metody zabalí operaci copy blob REST API a spustí asynchronní kopii dat ze zdrojového objektu blob:

Metoda beginCopyFromURL vrátí dlouho běžící operaci poller, která umožňuje čekat na neomezenou dobu, dokud se kopie nedokončí.

Kopírování objektu blob ze zdroje v Azure

Pokud kopírujete objekt blob ve stejném účtu úložiště, operace se může dokončit synchronně. Přístup ke zdrojovému objektu blob je možné autorizovat prostřednictvím ID Microsoft Entra, sdíleného přístupového podpisu (SAS) nebo klíče účtu. Informace o operaci alterativní synchronní kopírování najdete v tématu Kopírování objektu blob ze zdrojové adresy URL objektu pomocí TypeScriptu.

Pokud je zdrojem kopírování objekt blob v jiném účtu úložiště, může operace asynchronně dokončit. Zdrojový objekt blob musí být veřejný nebo autorizovaný prostřednictvím tokenu SAS. Token SAS musí obsahovat oprávnění ke čtení ('r' ). Další informace o tokenech SAS najdete v tématu Delegování přístupu pomocí sdílených přístupových podpisů.

Následující příklad ukazuje scénář kopírování zdrojového objektu blob z jiného účtu úložiště s asynchronním plánováním. V tomto příkladu vytvoříme adresu URL zdrojového objektu blob s připojeným tokenem SAS delegování uživatele. Příklad ukazuje, jak vygenerovat token SAS pomocí klientské knihovny, ale můžete také zadat vlastní. Příklad také ukazuje, jak zapůjčení zdrojového objektu blob během operace kopírování, aby se zabránilo změnám objektu blob z jiného klienta. Operace Copy Blob uloží ETag hodnotu zdrojového objektu blob při spuštění operace kopírování. ETag Pokud se hodnota změní před dokončením operace kopírování, operace selže.

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

Poznámka:

Tokeny SAS delegování uživatelů nabízejí větší zabezpečení, protože jsou podepsané pomocí přihlašovacích údajů Microsoft Entra místo klíče účtu. K vytvoření tokenu SAS delegování uživatele potřebuje objekt zabezpečení Microsoft Entra příslušná oprávnění. Požadavky na autorizaci najdete v tématu Získání klíče delegování uživatele.

Kopírování objektu blob ze zdroje mimo Azure

Operaci kopírování můžete provést u libovolného zdrojového objektu, který lze načíst prostřednictvím požadavku HTTP GET na danou adresu URL, včetně přístupných objektů mimo Azure. Následující příklad ukazuje scénář kopírování objektu blob z adresy URL přístupného zdrojového objektu.

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

Kontrola stavu operace kopírování

Pokud chcete zkontrolovat stav asynchronní Copy Blob operace, můžete se dotazovat na metodu getProperties a zkontrolovat stav kopírování.

Následující příklad kódu ukazuje, jak zkontrolovat stav čekající operace kopírování:

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

Přerušení operace kopírování

Přerušení čekající Copy Blob operace způsobí, že cílový objekt blob má nulovou délku. Metadata cílového objektu blob ale mají nové hodnoty zkopírované ze zdrojového objektu blob nebo explicitně nastavené během operace kopírování. Chcete-li zachovat původní metadata před kopií, vytvořte snímek cílového objektu blob před voláním jedné z metod kopírování.

Chcete-li přerušit čekající operaci kopírování, zavolejte následující operaci:

Tato metoda zabalí operaci Abort Copy Blob REST API, která zruší čekající Copy Blob operaci. Následující příklad kódu ukazuje, jak přerušit čekající Copy Blob operaci:

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

Zdroje informací

Další informace o kopírování objektů blob s asynchronním plánováním pomocí klientské knihovny služby Azure Blob Storage pro JavaScript a TypeScript najdete v následujících zdrojích informací.

Operace rozhraní REST API

Sada Azure SDK pro JavaScript a TypeScript obsahuje knihovny, které jsou založené na rozhraní Azure REST API a umožňují interakci s operacemi rozhraní REST API prostřednictvím známých jazykových paradigmat. Metody klientské knihovny popsané v tomto článku používají následující operace rozhraní REST API:

Ukázky kódu

Prostředky klientské knihovny