Przekazywanie bloba za pomocą języka JavaScript lub TypeScript

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

W tym artykule pokazano, jak przekazać obiekt blob przy użyciu biblioteki klienta usługi Azure Storage dla języka JavaScript. Dane można przesłać do obiektu blob blokowego przy użyciu ścieżki pliku, strumienia, buforu lub ciągu tekstowego. Można również przesyłać obiekty blob z użyciem tagów indeksu.

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 wykonywania operacji przesyłania. Aby dowiedzieć się więcej, zobacz wskazówki dotyczące autoryzacji dla następujących operacji interfejsu API REST:
  • Umieść obiekt blob
  • Dodaj blok

Przekazywanie danych do blobu blokowego

Możesz użyć dowolnej z poniższych metod, aby przesłać dane do obiektu blob blokowego:

• upload (nieparalelna metoda przesyłania)
• uploadData
• uploadFile (dostępny tylko w środowisku uruchomieniowym Node.js)
• uploadStream (dostępny tylko w środowisku uruchomieniowym Node.js)

Każda z tych metod może być wywoływana przy użyciu obiektu BlockBlobClient .

Uwaga

Biblioteki klienckie Azure Storage nie obsługują równoczesnego zapisu do tego samego obiektu blob. Jeśli Twoja aplikacja wymaga wielu procesów zapisujących do tego samego obiektu blob, należy zaimplementować strategię kontroli współbieżności, aby zapewnić przewidywalne doświadczenie. Aby dowiedzieć się więcej na temat strategii współbieżności, zobacz Zarządzanie współbieżnością w usłudze Blob Storage.

Przekazywanie blokowego obiektu blob ze ścieżki pliku

Poniższy przykład pokazuje, jak załadować blokowy blob ze ścieżki pliku lokalnego.

JavaScript

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

TypeScript

async function uploadBlobFromLocalPath(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath);
}

Prześlij blok typu blob ze strumienia

Poniższy przykład przesyła obiekt blob typu blokowego przez utworzenie strumienia do odczytu i przesłanie tego strumienia:

JavaScript

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

TypeScript

async function uploadBlobFromReadStream(
  containerClient: ContainerClient,
  blobName: string,
  readStream: fs.ReadStream
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadStream(readStream);
}

Przekazywanie blokowego obiektu blob z buforu

Poniższy przykład przesyła blokowy obiekt blob z buforu Node.js:

JavaScript

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

TypeScript

async function uploadBlobFromBuffer(
  containerClient: ContainerClient, blobName: string, buffer: Buffer
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

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

Prześlij blokowy blob z ciągu znaków

Poniższy przykład przesyła blokowy blob z ciągu:

JavaScript

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

TypeScript

async function uploadBlobFromString(
  containerClient: ContainerClient,
  blobName: string,
  fileContents: string
): Promise<void> {
  
  // Create blob client from container client
  const blockBlobClient: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

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

Przesyłanie blokowego obiektu blob z użyciem opcji konfiguracji

Opcje konfiguracji biblioteki klienta można zdefiniować, kiedy przesyłasz obiekt blob. Te opcje można dostosować, aby zwiększyć wydajność, zwiększyć niezawodność i zoptymalizować koszty. Przykłady kodu w tej sekcji pokazują, jak ustawić opcje konfiguracji przy użyciu interfejsu BlockBlobParallelUploadOptions oraz jak przekazać te opcje jako parametr do wywołania metody przekazywania.

Określanie opcji transferu danych podczas przekazywania

Właściwości można skonfigurować w BlockBlobParallelUploadOptions, aby zwiększyć wydajność operacji transferu danych. W poniższej tabeli wymieniono właściwości, które można skonfigurować, wraz z opisem:

Property	Description
blockSize	Maksymalny rozmiar bloku do przesyłania dla każdego żądania w ramach operacji przesyłania.
concurrency	Maksymalna liczba żądań równoległych, które są wydawane w danym momencie w ramach pojedynczego transferu równoległego.
maxSingleShotSize	Jeśli rozmiar danych jest mniejszy lub równy tej wartości, zostanie przekazany w jednym miejscu, a nie podzielony na fragmenty. Jeśli dane są przekazywane za jednym razem, rozmiar bloku jest ignorowany. Wartość domyślna to 256 MiB.

Poniższy przykład kodu przedstawia sposób ustawiania wartości dla BlockBlobParallelUploadOptions i dołączania opcji jako części wywołania metody przesyłania. Wartości podane w przykładach nie są przeznaczone do zalecenia. Aby prawidłowo dostosować te wartości, należy wziąć pod uwagę konkretne potrzeby aplikacji.

JavaScript

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

TypeScript

async function uploadWithTransferOptions(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Specify data transfer options
  const uploadOptions: BlockBlobParallelUploadOptions = {
    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: BlockBlobClient = containerClient.getBlockBlobClient(blobName);

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

Aby dowiedzieć się więcej na temat dostrajania opcji transferu danych, zobacz Dostosowywanie wydajności przekazywania i pobierania za pomocą języka JavaScript.

Określanie weryfikacji transferu danych podczas przekazywania

Weryfikacja transferu za pomocą CRC64 zapewnia integralność danych na poziomie klienta dla Azure Blob Storage, co pozwala sprawdzić, czy dane wysyłane przez aplikację są tymi samymi danymi przechowywanymi i odczytywanymi z Azure. Po włączeniu zestaw Blob SDK oblicza i weryfikuje sumy kontrolne CRC64 podczas operacji przekazywania i pobierania, podczas gdy usługa niezależnie oblicza i weryfikuje sumy kontrolne CRC64 dla odbieranych i zwracanych danych. Walidacja jest wykonywana dla każdego żądania i w całym strumieniu danych, co zapewnia, że cały blob jest weryfikowany nawet wtedy, gdy dane są przesyłane w częściach, na przykład podczas przesyłania bloków lub odczytów zakresowych. Aby uzyskać więcej informacji, zobacz Format treści ustrukturyzowanych .

Opcje weryfikacji transferu można zdefiniować na poziomie klienta przy użyciu klasy BlobClientConfig, która stosuje opcje walidacji do wszystkich metod wywoływanych z wystąpienia obiektu BlobClient . Alternatywnie można zastąpić opcje weryfikacji transferu na poziomie operacji za pomocą opcji, takich jak BlobUploadOptions.

JavaScript

const blobServiceClient = new BlobServiceClient(
   `https://${account}.blob.core.windows.net`,
   new DefaultAzureCredential(),
   {
     uploadContentChecksumAlgorithm: "StorageCrc64",
     downloadContentChecksumAlgorithm: "StorageCrc64",
   }
);

TypeScript

 const blobServiceClient: BlobServiceClient = new BlobServiceClient(
   `https://${account}.blob.core.windows.net`,
   new DefaultAzureCredential(),
   {
     uploadContentChecksumAlgorithm: "StorageCrc64",
     downloadContentChecksumAlgorithm: "StorageCrc64",
   },
);

Przesyłanie obiektu typu block blob z tagami indeksu

Tagi indeksu obiektów blob kategoryzują dane na koncie przechowywania przy użyciu znaczników typu klucz-wartość. Te tagi są automatycznie indeksowane i uwidaczniane jako indeks wielowymiarowy z możliwością wyszukiwania w celu łatwego znajdowania danych.

Poniższy przykład przesyła blokowy blob z ustawionymi tagami indeksowymi przy użyciu BlockBlobParallelUploadOptions:

JavaScript

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

TypeScript

async function uploadBlobWithIndexTags(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {
  
  // Specify index tags for blob
  const uploadOptions: BlockBlobParallelUploadOptions = {
    tags: {
      'Sealed': 'false',
      'Content': 'image',
      'Date': '2022-07-18',
    }
  };

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

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

Ustaw warstwę dostępu obiektu blob podczas przesyłania

Warstwę dostępu obiektu blob można ustawić podczas przesyłania przy użyciu interfejsu BlockBlobParallelUploadOptions. W poniższym przykładzie kodu pokazano, jak ustawić warstwę dostępu podczas ładowania obiektu blob.

JavaScript

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

TypeScript

async function uploadBlobWithAccessTier(
  containerClient: ContainerClient,
  blobName: string,
  localFilePath: string
): Promise<void> {

  // Upload blob to 'Cool' access tier
  const uploadOptions: BlockBlobParallelUploadOptions = {
    // 'Hot', 'Cool', 'Cold', or 'Archive'
    tier: 'Cool'
  };

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

  await blockBlobClient.uploadFile(localFilePath, uploadOptions);
}

Ustawienie warstwy dostępu jest dozwolone tylko dla blobów blokowych. Warstwę dostępu dla bloba blokowego można ustawić na Hot, Cool, Cold lub Archive. Aby ustawić warstwę dostępu na Cold, należy użyć minimalnej wersji biblioteki klienta 12.13.0.

Aby dowiedzieć się więcej na temat warstw dostępu, zobacz Omówienie warstw dostępu.

Zasoby

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

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 do przekazywania obiektów blob używają następujących operacji interfejsu API REST:

• Put Blob (interfejs API REST)
• Operacja Umieszczania Bloku (API REST)

Przykłady kodu

Wyświetl przykłady kodu z tego artykułu (GitHub):

• Przekazywanie z lokalnej ścieżki pliku dla języka JavaScript lub TypeScript
• Przekazywanie z buforu dla języka JavaScript lub TypeScript
• Przesyłanie ze strumienia w JavaScript lub TypeScript
• Przekazywanie z ciągu dla języka JavaScript lub TypeScript
• Przesyłanie z opcjami transferu dla JavaScript lub TypeScript
• Prześlij z tagami indeksu dla JavaScript lub TypeScript
• Przesyłanie z warstwą dostępu dla języka JavaScript lub języka TypeScript

Zasoby biblioteki klienta

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

Zobacz też

• Zarządzanie danymi obiektów blob platformy Azure i znajdowanie ich za pomocą tagów indeksu obiektów blob
• Zarządzaj danymi i wyszukuj je w usłudze Azure Blob Storage za pomocą tagów indeksu obiektów blob

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.