Kopiowanie obiektu blob z planowaniem asynchronicznym przy użyciu języka JavaScript lub TypeScript

• .NET
• Java
• JavaScript
• Python
• Przejdź

W tym artykule pokazano, jak skopiować obiekt blob z planowaniem asynchronicznym przy użyciu biblioteki klienta usługi Azure Storage dla języka JavaScript. Obiekt blob można skopiować ze źródła na tym samym koncie magazynu, ze źródła na innym koncie magazynu lub z dowolnego dostępnego obiektu pobranego za pośrednictwem żądania HTTP GET dla danego adresu URL. Możesz również przerwać oczekującą operację kopiowania.

Metody biblioteki klienta omówione w tym artykule korzystają z operacji kopiowania interfejsu API REST obiektów blob i mogą być używane, gdy chcesz wykonać kopię za pomocą planowania asynchronicznego. W przypadku większości scenariuszy kopiowania, w których chcesz przenieść dane na konto magazynu i mieć adres URL obiektu źródłowego, zobacz Kopiowanie obiektu blob z adresu URL obiektu źródłowego za pomocą języka JavaScript.

Wymagania wstępne

• W przykładach w tym artykule założono, że masz już skonfigurowany projekt do pracy z biblioteką klienta usługi Azure Blob Storage dla języka JavaScript. Aby dowiedzieć się więcej o konfigurowaniu projektu, w tym instalacji pakietu, importowaniu modułów i tworzeniu autoryzowanego obiektu klienta do pracy z zasobami danych, zobacz Rozpoczynanie pracy z usługami Azure Blob Storage i JavaScript.
• Mechanizm autoryzacji musi mieć uprawnienia do wykonania operacji kopiowania lub przerwania oczekującej kopii. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dla następującej operacji interfejsu API REST:
  • Kopiowanie obiektu blob
  • Przerwanie kopiowania obiektu blob

Informacje o kopiowaniu obiektów blob za pomocą planowania asynchronicznego

Operacja Copy Blob może zakończyć się asynchronicznie i jest wykonywana na podstawie najlepszego nakładu pracy, co oznacza, że operacja nie gwarantuje natychmiastowego uruchomienia ani ukończenia w określonym przedziale czasu. Operacja kopiowania jest zaplanowana w tle i wykonywana jako serwer ma dostępne zasoby. Operacja może zakończyć się synchronicznie, jeśli kopia występuje na tym samym koncie magazynu.

Operacja Copy Blob może wykonać dowolną z następujących akcji:

• Skopiuj źródłowy obiekt blob do docelowego obiektu blob o innej nazwie. Docelowy obiekt blob może być istniejącym obiektem blob tego samego typu obiektu blob (blok, dołączanie lub strona) albo może być nowym obiektem blob utworzonym przez operację kopiowania.
• Skopiuj źródłowy obiekt blob do docelowego obiektu blob o takiej samej nazwie, który zastępuje docelowy obiekt blob. Ten typ operacji kopiowania usuwa wszystkie niezatwierdzone bloki i zastępuje metadane docelowego obiektu blob.
• Skopiuj plik źródłowy w usłudze Azure File do docelowego obiektu blob. Docelowy obiekt blob może być istniejącym blokowym obiektem blob lub może być nowym blokowym obiektem blob utworzonym przez operację kopiowania. Kopiowanie z plików do stronicowych obiektów blob lub uzupełnialnych obiektów blob nie jest obsługiwane.
• Skopiuj migawkę na podstawowy obiekt blob. Promując migawkę do pozycji podstawowego obiektu blob, można przywrócić starszą wersję obiektu blob.
• Skopiuj migawkę do docelowego obiektu blob o innej nazwie. Wynikowy docelowy obiekt blob jest zapisywalnym obiektem blob, a nie migawką.

Aby dowiedzieć się więcej o Copy Blob operacji, w tym o właściwościach, tagach indeksu, metadanych i rozliczeniach, zobacz Kopiowanie uwag dotyczących obiektu blob.

Kopiowanie obiektu blob za pomocą planowania asynchronicznego

Ta sekcja zawiera omówienie metod udostępnianych przez bibliotekę klienta usługi Azure Storage dla języka JavaScript w celu wykonania operacji kopiowania przy użyciu planowania asynchronicznego.

Następujące metody opakowuje operację interfejsu API REST kopiowania obiektów blob i rozpoczynają asynchroniczną kopię danych ze źródłowego obiektu blob:

• BlobClient.beginCopyFromURL

Metoda beginCopyFromURL zwraca długotrwałą operację poller, która umożliwia oczekiwanie na czas nieokreślony do zakończenia kopiowania.

Kopiowanie obiektu blob ze źródła na platformie Azure

Jeśli kopiujesz obiekt blob na tym samym koncie magazynu, operacja może zakończyć się synchronicznie. Dostęp do źródłowego obiektu blob można autoryzować za pośrednictwem identyfikatora Firmy Microsoft, sygnatury dostępu współdzielonego (SAS) lub klucza konta. Aby uzyskać informacje na temat operacji kopiowania synchronicznego, zobacz Kopiowanie obiektu blob z adresu URL obiektu źródłowego przy użyciu języka JavaScript.

Jeśli źródło kopiowania jest obiektem blob na innym koncie magazynu, operacja może zakończyć się asynchronicznie. Źródłowy obiekt blob musi być publiczny lub autoryzowany za pośrednictwem tokenu SAS. Token SAS musi zawierać uprawnienie Odczyt ('r'). Aby dowiedzieć się więcej na temat tokenów SAS, zobacz Delegowanie dostępu za pomocą sygnatur dostępu współdzielonego.

Poniższy przykład przedstawia scenariusz kopiowania źródłowego obiektu blob z innego konta magazynu z asynchronicznym planowaniem. W tym przykładzie utworzymy źródłowy adres URL obiektu blob z dołączonym tokenem SAS delegowania użytkownika. W przykładzie pokazano, jak wygenerować token SAS przy użyciu biblioteki klienta, ale możesz również podać własne. W przykładzie pokazano również, jak dzierżawić źródłowy obiekt blob podczas operacji kopiowania, aby zapobiec zmianom obiektu blob z innego klienta. Operacja Copy Blob zapisuje ETag wartość źródłowego obiektu blob po uruchomieniu operacji kopiowania. Jeśli wartość zostanie zmieniona ETag przed zakończeniem operacji kopiowania, operacja zakończy się niepowodzeniem.

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

Uwaga

Tokeny SAS delegowania użytkownika zapewniają większe bezpieczeństwo, ponieważ są podpisane przy użyciu poświadczeń firmy Microsoft Entra zamiast klucza konta. Aby utworzyć token SAS delegowania użytkownika, podmiot zabezpieczeń firmy Microsoft entra potrzebuje odpowiednich uprawnień. Aby uzyskać wymagania dotyczące autoryzacji, zobacz Pobieranie klucza delegowania użytkownika.

Kopiowanie obiektu blob ze źródła spoza platformy Azure

Operację kopiowania można wykonać na dowolnym obiekcie źródłowym, który można pobrać za pośrednictwem żądania HTTP GET dla danego adresu URL, w tym obiektów dostępnych poza platformą Azure. Poniższy przykład przedstawia scenariusz kopiowania obiektu blob z dostępnego adresu URL obiektu źródłowego.

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

Sprawdzanie stanu operacji kopiowania

Aby sprawdzić stan operacji asynchronicznej Copy Blob , możesz sondować metodę getProperties i sprawdzić stan kopiowania.

W poniższym przykładzie kodu pokazano, jak sprawdzić stan oczekującej operacji kopiowania:

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

Przerywanie operacji kopiowania

Przerwanie oczekującej Copy Blob operacji powoduje utworzenie docelowego obiektu blob o zerowej długości. Jednak metadane docelowego obiektu blob mają nowe wartości skopiowane ze źródłowego obiektu blob lub ustawione jawnie podczas operacji kopiowania. Aby zachować oryginalne metadane przed kopią, przed wywołaniem jednej z metod kopiowania utwórz migawkę docelowego obiektu blob.

Aby przerwać oczekującą operację kopiowania, wywołaj następującą operację:

• BlobClient.abortCopyFromURL

Ta metoda opakowuje operację interfejsu API REST kopiowania obiektu blob abort, która anuluje oczekującą Copy Blob operację. Poniższy przykład kodu pokazuje, jak przerwać oczekującą Copy Blob operację:

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

Zasoby

Aby dowiedzieć się więcej na temat kopiowania obiektów blob za pomocą planowania asynchronicznego przy użyciu biblioteki klienta usługi Azure Blob Storage dla języka JavaScript, zobacz następujące zasoby.

Przykłady kodu

• Wyświetl przykłady kodu JavaScript i TypeScript z tego artykułu (GitHub)

Operacje interfejsu API REST

Zestaw Azure SDK dla języka JavaScript zawiera biblioteki, które bazują na interfejsie API REST platformy Azure, co umożliwia interakcję z operacjami interfejsu API REST za pomocą znanych paradygmatów języka JavaScript. Metody biblioteki klienta opisane w tym artykule korzystają z następujących operacji interfejsu API REST:

• Kopiowanie obiektu blob (interfejs API REST)
• Przerwanie kopiowania obiektu blob (interfejs API REST)

Zasoby biblioteki klienta

• Dokumentacja referencyjna biblioteki klienta
• Kod źródłowy biblioteki klienta
• Pakiet (npm)

Powiązana zawartość

• Ten artykuł jest częścią przewodnika dla deweloperów usługi Blob Storage dla języka JavaScript/Typescript. Aby dowiedzieć się więcej, zobacz pełną listę artykułów z przewodnika dla deweloperów na stronie Tworzenie aplikacji JavaScript/Typescript.