Skip to content

Commit 9a89e10

Browse files
GitHubber17GitHubber17
authored
Merge pull request #205042 from diberry/diberry/0718-storage-upuload
Blob Storage - JS - blob upload methods
2 parents fcfbd83 + cdb4b45 commit 9a89e10

File tree

1 file changed

+78
-100
lines changed

1 file changed

+78
-100
lines changed

‎articles/storage/blobs/storage-blob-upload-javascript.md

Lines changed: 78 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ services: storage
55
author: normesta
66

77
ms.author: normesta
8-
ms.date: 03/28/2022
8+
ms.date: 07/18/2022
99
ms.service: storage
1010
ms.subservice: blobs
1111
ms.topic: how-to
@@ -22,126 +22,104 @@ The [sample code snippets](https://github.com/Azure-Samples/AzureStorageSnippets
2222
> [!NOTE]
2323
> The examples in this article assume that you've created a [BlobServiceClient](/javascript/api/@azure/storage-blob/blobserviceclient) object by using the guidance in the [Get started with Azure Blob Storage and JavaScript](storage-blob-javascript-get-started.md) article. Blobs in Azure Storage are organized into containers. Before you can upload a blob, you must first create a container. To learn how to create a container, see [Create a container in Azure Storage with JavaScript](storage-blob-container-create.md).
2424
25+
## Upload by blob client
2526

26-
## Upload by using a file path
27+
Use the following table to find the correct upload method based on the blob client.
28+
29+
|Client|Upload method|
30+
|--|--|
31+
|[BlobClient](/javascript/api/@azure/storage-blob/blobclient)|The SDK needs to know the blob type you want to upload to. Because BlobClient is the base class for the other Blob clients, it does not have upload methods. It is mostly useful for operations that are common to the child blob classes. For uploading, create specific blob clients directly or get specific blob clients from ContainerClient.|
32+
|[BlockBlobClient](/javascript/api/@azure/storage-blob/blockblobclient)|This is the **most common upload client**:<br>* upload()<br>* stageBlock() and commitBlockList()|
33+
|[AppendBlobClient](/javascript/api/@azure/storage-blob/appendblobclient)|* create()<br>* append()|
34+
|[PageBlobClient](/javascript/api/@azure/storage-blob/pageblobclient)|* create()<br>* appendPages()|
35+
36+
## <a name="upload-by-using-a-file-path"></a>Upload with BlockBlobClient by using a file path
2737

2838
The following example uploads a local file to blob storage with the [BlockBlobClient](/javascript/api/@azure/storage-blob/blockblobclient) object. The [options](/javascript/api/@azure/storage-blob/blockblobparalleluploadoptions) object allows you to pass in your own metadata and [tags](storage-manage-find-blobs.md#blob-index-tags-and-data-management), used for indexing, at upload time:
2939

30-
```javascript
31-
// uploadOptions: {
32-
// metadata: { reviewer: 'john', reviewDate: '2022-04-01' },
33-
// tags: {project: 'xyz', owner: 'accounts-payable'}
34-
// }
35-
async function createBlobFromLocalPath(containerClient, blobName, localFileWithPath, uploadOptions){
36-
37-
// create blob client from container client
38-
const blockBlobClient = await containerClient.getBlockBlobClient(blobName);
39-
40-
// upload file to blob storage
41-
await blockBlobClient.uploadFile(localFileWithPath, uploadOptions);
42-
console.log(`${blobName} succeeded`);
43-
}
44-
```
40+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-local-file-path.js" id="Snippet_UploadBlob" highlight="14":::
4541

46-
## Upload by using a Stream
42+
## <a name="upload-by-using-a-stream"></a>Upload with BlockBlobClient by using a Stream
4743

4844
The following example uploads a readable stream to blob storage with the [BlockBlobClient](/javascript/api/@azure/storage-blob/blockblobclient) object. Pass in the BlockBlobUploadStream [options](/javascript/api/@azure/storage-blob/blockblobuploadstreamoptions) to affect the upload:
4945

46+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-stream.js" id="Snippet_UploadBlob" highlight="27":::
47+
48+
Transform the stream during the upload for data clean up.
49+
50+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-stream.js" id="Snippet_Transform" :::
51+
52+
The following code demonstrates how to use the function.
53+
5054
```javascript
51-
// uploadOptions: {
52-
// metadata: { reviewer: 'john', reviewDate: '2022-04-01' },
53-
// tags: {project: 'xyz', owner: 'accounts-payable'},
54-
// }
55-
async function createBlobFromReadStream(containerClient, blobName, readableStream, uploadOptions) {
56-
57-
// Create blob client from container client
58-
const blockBlobClient = await containerClient.getBlockBlobClient(blobName);
59-
60-
// Size of every buffer allocated, also
61-
// the block size in the uploaded block blob.
62-
// Default value is 8MB
63-
const bufferSize = 4 * 1024 * 1024;
64-
65-
// Max concurrency indicates the max number of
66-
// buffers that can be allocated, positive correlation
67-
// with max uploading concurrency. Default value is 5
68-
const maxConcurrency = 20;
69-
70-
// use transform per chunk - only to see chunck
71-
const transformedReadableStream = readableStream.pipe(myTransform);
72-
73-
// Upload stream
74-
await blockBlobClient.uploadStream(transformedReadableStream, bufferSize, maxConcurrency, uploadOptions);
75-
76-
// do something with blob
77-
const getTagsResponse = await blockBlobClient.getTags();
78-
console.log(`tags for ${blobName} = ${JSON.stringify(getTagsResponse.tags)}`);
79-
}
80-
81-
// Transform stream
82-
// Reasons to transform:
83-
// 1. Sanitize the data - remove PII
84-
// 2. Compress or uncompress
85-
const myTransform = new Transform({
86-
transform(chunk, encoding, callback) {
87-
// see what is in the artificially
88-
// small chunk
89-
console.log(chunk);
90-
callback(null, chunk);
91-
},
92-
decodeStrings: false
93-
});
55+
// fully qualified path to file
56+
const localFileWithPath = path.join(__dirname, `my-text-file.txt`);
57+
58+
// encoding: just to see the chunk as it goes by in the transform
59+
const streamOptions = { highWaterMark: 20, encoding: 'utf-8' }
9460

61+
const readableStream = fs.createReadStream(localFileWithPath, streamOptions);
62+
63+
// upload options
64+
const uploadOptions = {
65+
66+
// not indexed for searching
67+
metadata: {
68+
owner: 'PhillyProject'
69+
},
70+
71+
// indexed for searching
72+
tags: {
73+
createdBy: 'YOUR-NAME',
74+
createdWith: `StorageSnippetsForDocs-${i}`,
75+
createdOn: (new Date()).toDateString()
76+
}
77+
}
78+
79+
// upload stream
80+
await createBlobFromReadStream(containerClient, `my-text-file.txt`, readableStream, uploadOptions);
9581
```
9682

97-
## Upload by using a BinaryData object
83+
## <a name="upload-by-using-a-binarydata-object"></a>Upload with BlockBlobClient by using a BinaryData object
9884

9985
The following example uploads a Node.js buffer to blob storage with the [BlockBlobClient](/javascript/api/@azure/storage-blob/blockblobclient) object. Pass in the BlockBlobParallelUpload [options](/javascript/api/@azure/storage-blob/blockblobparalleluploadoptions) to affect the upload:
10086

87+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-buffer.js" id="Snippet_UploadBlob" highlight="17":::
88+
89+
The following code demonstrates how to use the function.
90+
10191
```javascript
102-
// uploadOptions: {
103-
// blockSize: destination block blob size in bytes,
104-
// concurrency: concurrency of parallel uploading - must be greater than or equal to 0,
105-
// maxSingleShotSize: blob size threshold in bytes to start concurrency uploading
106-
// metadata: { reviewer: 'john', reviewDate: '2022-04-01' },
107-
// tags: {project: 'xyz', owner: 'accounts-payable'}
108-
// }
109-
async function createBlobFromBuffer(containerClient, blobName, buffer, uploadOptions) {
110-
111-
// Create blob client from container client
112-
const blockBlobClient = await containerClient.getBlockBlobClient(blobName);
113-
114-
// Upload buffer
115-
await blockBlobClient.uploadData(buffer, uploadOptions);
116-
117-
// do something with blob
118-
const getTagsResponse = await blockBlobClient.getTags();
119-
console.log(`tags for ${blobName} = ${JSON.stringify(getTagsResponse.tags)}`);
120-
}
92+
// fully qualified path to file
93+
const localFileWithPath = path.join(__dirname, `daisies.jpg`);
94+
95+
// read file into buffer
96+
const buffer = await fs.readFile(localFileWithPath);
97+
98+
// upload options
99+
const uploadOptions = {
100+
101+
// not indexed for searching
102+
metadata: {
103+
owner: 'PhillyProject'
104+
},
105+
106+
// indexed for searching
107+
tags: {
108+
createdBy: 'YOUR-NAME',
109+
createdWith: `StorageSnippetsForDocs-${i}`,
110+
createdOn: (new Date()).toDateString()
111+
}
112+
}
113+
114+
// upload buffer
115+
createBlobFromBuffer(containerClient, `daisies.jpg`, buffer, uploadOptions)
121116
```
122117

123-
## Upload a string
118+
## <a name="upload-a-string"></a>Upload a string with BlockBlobClient
124119

125120
The following example uploads a string to blob storage with the [BlockBlobClient](/javascript/api/@azure/storage-blob/blockblobclient) object. Pass in the BlockBlobUploadOptions [options](/javascript/api/@azure/storage-blob/blockblobuploadoptions) to affect the upload:
126121

127-
```javascript
128-
// uploadOptions: {
129-
// metadata: { reviewer: 'john', reviewDate: '2022-04-01' },
130-
// tags: {project: 'xyz', owner: 'accounts-payable'}
131-
// }
132-
async function createBlobFromString(containerClient, blobName, fileContentsAsString, uploadOptions){
133-
134-
// Create blob client from container client
135-
const blockBlobClient = await containerClient.getBlockBlobClient(blobName);
136-
137-
// Upload string
138-
await blockBlobClient.upload(fileContentsAsString, fileContentsAsString.length, uploadOptions);
139-
140-
// do something with blob
141-
const getTagsResponse = await blockBlobClient.getTags();
142-
console.log(`tags for ${blobName} = ${JSON.stringify(getTagsResponse.tags)}`);
143-
}
144-
```
122+
:::code language="javascript" source="~/azure_storage-snippets/blobs/howto/JavaScript/NodeJS-v12/dev-guide/upload-blob-from-string.js" id="Snippet_UploadBlob" highlight="14":::
145123

146124
## See also
147125

0 commit comments

Comments
 (0)