Upload a blob with JavaScript or TypeScript

2025-04-12

W tym artykule pokazano, jak przekazać obiekt blob przy użyciu biblioteki klienta usługi Azure Storage dla języka JavaScript. You can upload data to a block blob from a file path, a stream, a buffer, or a text string. You can also upload blobs with index tags.

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:
- Put Blob
- Put Block

Upload data to a block blob

You can use any of the following methods to upload data to a block blob:

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

The Azure Storage client libraries don't support concurrent writes to the same blob. If your app requires multiple processes writing to the same blob, you should implement a strategy for concurrency control to provide a predictable experience. Aby dowiedzieć się więcej na temat strategii współbieżności, zobacz Zarządzanie współbieżnością w usłudze Blob Storage.

Upload a block blob from a file path

The following example uploads a block blob from a local file path:

JavaScript
TypeScript

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

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

Upload a block blob from a stream

The following example uploads a block blob by creating a readable stream and uploading the stream:

JavaScript
TypeScript

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

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

Upload a block blob from a buffer

The following example uploads a block blob from a Node.js buffer:

JavaScript
TypeScript

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

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

Upload a block blob from a string

The following example uploads a block blob from a string:

JavaScript
TypeScript

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

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

Upload a block blob with configuration options

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. If the data is uploaded in a single shot, the block size is ignored. 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
TypeScript

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

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.

Upload a block blob with index tags

Blob index tags categorize data in your storage account using key-value tag attributes. Te tagi są automatycznie indeksowane i uwidaczniane jako indeks wielowymiarowy z możliwością wyszukiwania w celu łatwego znajdowania danych.

The following example uploads a block blob with index tags set using BlockBlobParallelUploadOptions:

JavaScript
TypeScript

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

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

Set a blob's access tier on upload

You can set a blob's access tier on upload by using the BlockBlobParallelUploadOptions interface. The following code example shows how to set the access tier when uploading a blob:

JavaScript
TypeScript

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

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. You can set the access tier for a block blob to Hot, Cool, Cold, or 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 (REST API)
Put Block (REST API)

Przykłady kodu

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

Upload from local file path for JavaScript or TypeScript
Przekazywanie z buforu dla języka JavaScript lub TypeScript
Upload from stream for JavaScript or TypeScript
Upload from string for JavaScript or TypeScript
Przesyłanie z opcjami transferu dla JavaScript lub TypeScript
Prześlij z tagami indeksu dla JavaScript lub TypeScript
Upload with access tier for JavaScript or TypeScript

Zasoby biblioteki klienta

Zobacz też

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.

Udostępnij za pośrednictwem