ShareFileClient class

A ShareFileClient represents a URL to an Azure Storage file.

Extends

StorageClient

Constructors

ShareFileClient(string, Credential_2 | TokenCredential, ShareClientOptions)

Creates an instance of ShareFileClient.

ShareFileClient(string, Pipeline, ShareClientConfig)

Creates an instance of ShareFileClient.

Properties

name

The name of the file

path

The full path of the file

shareName

The share name corresponding to this file client

Inherited Properties

accountName
url

URL string value.

Methods

abortCopyFromURL(string, FileAbortCopyFromURLOptions)

Aborts a pending Copy File operation, and leaves a destination file with zero length and full metadata.

See https://docs.microsoft.com/en-us/rest/api/storageservices/abort-copy-file

clearRange(number, number, FileClearRangeOptions)

Clears the specified range and releases the space used in storage for that range.

create(number, FileCreateOptions)

Creates a new file or replaces a file. Note it only initializes the file with no content.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-file

delete(FileDeleteOptions)

Removes the file from the storage account. When a file is successfully deleted, it is immediately removed from the storage account's index and is no longer accessible to clients. The file's data is later removed from the service during garbage collection.

Delete File will fail with status code 409 (Conflict) and error code SharingViolation if the file is open on an SMB client.

Delete File is not supported on a share snapshot, which is a read-only copy of a share. An attempt to perform this operation on a share snapshot will fail with 400 (InvalidQueryParameterValue)

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-file2

deleteIfExists(FileDeleteOptions)

Removes the file from the storage account if it exists. When a file is successfully deleted, it is immediately removed from the storage account's index and is no longer accessible to clients. The file's data is later removed from the service during garbage collection.

Delete File will fail with status code 409 (Conflict) and error code SharingViolation if the file is open on an SMB client.

Delete File is not supported on a share snapshot, which is a read-only copy of a share. An attempt to perform this operation on a share snapshot will fail with 400 (InvalidQueryParameterValue)

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-file2

download(number, number, FileDownloadOptions)

Reads or downloads a file from the system, including its metadata and properties.

  • In Node.js, data returns in a Readable stream readableStreamBody
  • In browsers, data returns in a promise contentAsBlob

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-file

downloadToBuffer(Buffer, number, number, FileDownloadToBufferOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Downloads an Azure file in parallel to a buffer. Offset and count are optional, pass 0 for both to download the entire file.

Warning: Buffers can only support files up to about one gigabyte on 32-bit systems or about two gigabytes on 64-bit systems due to limitations of Node.js/V8. For files larger than this size, consider downloadToFile.

downloadToBuffer(number, number, FileDownloadToBufferOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME

Downloads an Azure file in parallel to a buffer. Offset and count are optional, pass 0 for both to download the entire file

Warning: Buffers can only support files up to about one gigabyte on 32-bit systems or about two gigabytes on 64-bit systems due to limitations of Node.js/V8. For files larger than this size, consider downloadToFile.

downloadToFile(string, number, number, FileDownloadOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Downloads an Azure Blob to a local file. Fails if the the given file path already exits. Offset and count are optional, pass 0 and undefined respectively to download the entire blob.

exists(FileExistsOptions)

Returns true if the specified file exists; false otherwise.

NOTE: use this function with care since an existing file might be deleted by other clients or applications. Vice versa new files might be added by other clients or applications after this function completes.

forceCloseAllHandles(FileForceCloseHandlesOptions)

Force close all handles for a file.

See https://docs.microsoft.com/en-us/rest/api/storageservices/force-close-handles

forceCloseHandle(string, FileForceCloseHandlesOptions)

Force close a specific handle for a file.

See https://docs.microsoft.com/en-us/rest/api/storageservices/force-close-handles

generateSasUrl(FileGenerateSasUrlOptions)

Only available for clients constructed with a shared key credential.

Generates a Service Shared Access Signature (SAS) URI based on the client properties and parameters passed in. The SAS is signed by the shared key credential of the client.

See https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas

getProperties(FileGetPropertiesOptions)

Returns all user-defined metadata, standard HTTP properties, and system properties for the file. It does not return the content of the file.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-file-properties

getRangeList(FileGetRangeListOptions)

Returns the list of valid ranges for a file.

getRangeListDiff(string, FileGetRangeListOptions)

Returns the list of ranges that differ between a previous share snapshot and this file.

getShareLeaseClient(string)

Get a ShareLeaseClient that manages leases on the file.

listHandles(FileListHandlesOptions)

Returns an async iterable iterator to list all the handles. under the specified account.

.byPage() returns an async iterable iterator to list the handles in pages.

rename(string, FileRenameOptions)

Renames a file. This API only supports renaming a file in the same share.

resize(number, FileResizeOptions)

Resize file.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-properties

setHttpHeaders(FileHttpHeaders, FileSetHttpHeadersOptions)

Sets HTTP headers on the file.

If no option provided, or no value provided for the file HTTP headers in the options, these file HTTP headers without a value will be cleared.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-properties

setMetadata(Metadata, FileSetMetadataOptions)

Updates user-defined metadata for the specified file.

If no metadata defined in the option parameter, the file metadata will be removed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-metadata

setProperties(FileProperties)

Sets properties on the file.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-properties

startCopyFromURL(string, FileStartCopyOptions)

Copies a blob or file to a destination file within the storage account.

uploadData(Blob | ArrayBuffer | ArrayBufferView | Buffer, FileParallelUploadOptions)

Creates a new Azure File or replaces an existing Azure File, and then uploads a Buffer(Node)/Blob/ArrayBuffer/ArrayBufferView to it.

uploadFile(string, FileParallelUploadOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Creates a new Azure File or replaces an existing Azure File, and then uploads a local file to it.

uploadRange(HttpRequestBody, number, number, FileUploadRangeOptions)

Upload a range of bytes to a file. This operation can only be called on an existing file. It won't change the size, properties or metadata of the file. Both the start and count of the range must be specified. The range can be up to 4 MB in size.

uploadRangeFromURL(string, number, number, number, FileUploadRangeFromURLOptions)

Upload a range of bytes to a file where the contents are read from a another file's URL. The range can be up to 4 MB in size.

uploadResetableStream((offset: number, count?: number) => ReadableStream, number, FileParallelUploadOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Accepts a Node.js Readable stream factory, and uploads in blocks to an Azure File. The Readable stream factory must returns a Node.js Readable stream starting from the offset defined. The offset is the offset in the Azure file to be uploaded.

uploadSeekableBlob((offset: number, size: number) => Blob, number, FileParallelUploadOptions)

ONLY AVAILABLE IN BROWSERS.

Uploads a browser Blob object to an Azure file. Requires a blobFactory as the data source, which need to return a Blob object with the offset and size provided.

uploadStream(Readable, number, number, number, FileUploadStreamOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Creates a new Azure File or replaces an existing Azure File, and then uploads a Node.js Readable stream into it. This method will try to create an Azure File, then starts uploading chunk by chunk. Size of chunk is defined by bufferSize parameter. Please make sure potential size of stream doesn't exceed file size.

PERFORMANCE IMPROVEMENT TIPS:

  • Input stream highWaterMark is better to set a same value with bufferSize parameter, which will avoid Buffer.concat() operations.
withShareSnapshot(string)

Creates a new ShareFileClient object identical to the source but with the specified share snapshot timestamp. Provide "" will remove the snapshot and return a URL to the base ShareFileClient.

Constructor Details

ShareFileClient(string, Credential_2 | TokenCredential, ShareClientOptions)

Creates an instance of ShareFileClient.

new ShareFileClient(url: string, credential?: Credential_2 | TokenCredential, options?: ShareClientOptions)

Parameters

url

string

A URL string pointing to Azure Storage file, such as "https://myaccount.file.core.windows.net/myshare/mydirectory/file". You can append a SAS if using AnonymousCredential, such as "https://myaccount.file.core.windows.net/myshare/mydirectory/file?sasString". This method accepts an encoded URL or non-encoded URL pointing to a file. Encoded URL string will NOT be escaped twice, only special characters in URL path will be escaped. However, if a file or directory name includes %, file or directory name must be encoded in the URL. Such as a file named "myfile%", the URL should be "https://myaccount.file.core.windows.net/myshare/mydirectory/myfile%25".

credential

Credential | TokenCredential

Such as AnonymousCredential, StorageSharedKeyCredential or TokenCredential, If not specified, AnonymousCredential is used.

options
ShareClientOptions

Optional. Options to configure the HTTP pipeline.

ShareFileClient(string, Pipeline, ShareClientConfig)

Creates an instance of ShareFileClient.

new ShareFileClient(url: string, pipeline: Pipeline, options?: ShareClientConfig)

Parameters

url

string

A URL string pointing to Azure Storage file, such as "https://myaccount.file.core.windows.net/myshare/mydirectory/file". You can append a SAS if using AnonymousCredential, such as "https://myaccount.file.core.windows.net/myshare/mydirectory/file?sasString". This method accepts an encoded URL or non-encoded URL pointing to a file. Encoded URL string will NOT be escaped twice, only special characters in URL path will be escaped. However, if a file or directory name includes %, file or directory name must be encoded in the URL. Such as a file named "myfile%", the URL should be "https://myaccount.file.core.windows.net/myshare/mydirectory/myfile%25".

pipeline
Pipeline

Call newPipeline() to create a default pipeline, or provide a customized pipeline.

Property Details

name

The name of the file

string name

Property Value

string

path

The full path of the file

string path

Property Value

string

shareName

The share name corresponding to this file client

string shareName

Property Value

string

Inherited Property Details

accountName

accountName: string

Property Value

string

Inherited From StorageClient.accountName

url

URL string value.

url: string

Property Value

string

Inherited From StorageClient.url

Method Details

abortCopyFromURL(string, FileAbortCopyFromURLOptions)

Aborts a pending Copy File operation, and leaves a destination file with zero length and full metadata.

See https://docs.microsoft.com/en-us/rest/api/storageservices/abort-copy-file

function abortCopyFromURL(copyId: string, options?: FileAbortCopyFromURLOptions): Promise<FileAbortCopyResponse>

Parameters

copyId

string

Id of the Copy File operation to abort.

options
FileAbortCopyFromURLOptions

Options to File Abort Copy From URL operation.

Returns

clearRange(number, number, FileClearRangeOptions)

Clears the specified range and releases the space used in storage for that range.

function clearRange(offset: number, contentLength: number, options?: FileClearRangeOptions): Promise<FileUploadRangeResponse>

Parameters

offset

number

contentLength

number

options
FileClearRangeOptions

Options to File Clear Range operation.

Returns

create(number, FileCreateOptions)

Creates a new file or replaces a file. Note it only initializes the file with no content.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-file

function create(size: number, options?: FileCreateOptions): Promise<FileCreateResponse>

Parameters

size

number

Specifies the maximum size in bytes for the file, up to 4 TB.

options
FileCreateOptions

Options to File Create operation.

Returns

Response data for the File Create operation.

Example usage:

const content = "Hello world!";

// Create the file
await fileClient.create(content.length);
console.log("Created file successfully!");

// Then upload data to the file
await fileClient.uploadRange(content, 0, content.length);
console.log("Updated file successfully!")

delete(FileDeleteOptions)

Removes the file from the storage account. When a file is successfully deleted, it is immediately removed from the storage account's index and is no longer accessible to clients. The file's data is later removed from the service during garbage collection.

Delete File will fail with status code 409 (Conflict) and error code SharingViolation if the file is open on an SMB client.

Delete File is not supported on a share snapshot, which is a read-only copy of a share. An attempt to perform this operation on a share snapshot will fail with 400 (InvalidQueryParameterValue)

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-file2

function delete(options?: FileDeleteOptions): Promise<FileDeleteResponse>

Parameters

options
FileDeleteOptions

Options to File Delete operation.

Returns

Response data for the File Delete operation.

deleteIfExists(FileDeleteOptions)

Removes the file from the storage account if it exists. When a file is successfully deleted, it is immediately removed from the storage account's index and is no longer accessible to clients. The file's data is later removed from the service during garbage collection.

Delete File will fail with status code 409 (Conflict) and error code SharingViolation if the file is open on an SMB client.

Delete File is not supported on a share snapshot, which is a read-only copy of a share. An attempt to perform this operation on a share snapshot will fail with 400 (InvalidQueryParameterValue)

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-file2

function deleteIfExists(options?: FileDeleteOptions): Promise<FileDeleteIfExistsResponse>

Parameters

Returns

download(number, number, FileDownloadOptions)

Reads or downloads a file from the system, including its metadata and properties.

  • In Node.js, data returns in a Readable stream readableStreamBody
  • In browsers, data returns in a promise contentAsBlob

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-file

function download(offset?: number, count?: number, options?: FileDownloadOptions): Promise<FileDownloadResponseModel>

Parameters

offset

number

From which position of the file to download, greater than or equal to 0

count

number

How much data to be downloaded, greater than 0. Will download to the end when undefined

options
FileDownloadOptions

Options to File Download operation.

Returns

Response data for the File Download operation.

Example usage (Node.js):

// Download a file to a string
const downloadFileResponse = await fileClient.download();
console.log(
  "Downloaded file content:",
  (await streamToBuffer(downloadFileResponse.readableStreamBody)).toString()}
);

// A helper method used to read a Node.js readable stream into string
async function streamToBuffer(readableStream) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

Example usage (browsers):

// Download a file to a string
const downloadFileResponse = await fileClient.download(0);
console.log(
  "Downloaded file content:",
  await blobToString(await downloadFileResponse.blobBody)}
);

// A helper method used to convert a browser Blob into string.
export async function blobToString(blob: Blob): Promise<string> {
  const fileReader = new FileReader();
  return new Promise<string>((resolve, reject) => {
    fileReader.onloadend = (ev: any) => {
      resolve(ev.target!.result);
    };
    fileReader.onerror = reject;
    fileReader.readAsText(blob);
  });
}

downloadToBuffer(Buffer, number, number, FileDownloadToBufferOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Downloads an Azure file in parallel to a buffer. Offset and count are optional, pass 0 for both to download the entire file.

Warning: Buffers can only support files up to about one gigabyte on 32-bit systems or about two gigabytes on 64-bit systems due to limitations of Node.js/V8. For files larger than this size, consider downloadToFile.

function downloadToBuffer(buffer: Buffer, offset?: number, count?: number, options?: FileDownloadToBufferOptions): Promise<Buffer>

Parameters

buffer

Buffer

Buffer to be fill, must have length larger than count

offset

number

From which position of the Azure File to download

count

number

How much data to be downloaded. Will download to the end when passing undefined

Returns

Promise<Buffer>

downloadToBuffer(number, number, FileDownloadToBufferOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME

Downloads an Azure file in parallel to a buffer. Offset and count are optional, pass 0 for both to download the entire file

Warning: Buffers can only support files up to about one gigabyte on 32-bit systems or about two gigabytes on 64-bit systems due to limitations of Node.js/V8. For files larger than this size, consider downloadToFile.

function downloadToBuffer(offset?: number, count?: number, options?: FileDownloadToBufferOptions): Promise<Buffer>

Parameters

offset

number

From which position of the Azure file to download

count

number

How much data to be downloaded. Will download to the end when passing undefined

Returns

Promise<Buffer>

downloadToFile(string, number, number, FileDownloadOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Downloads an Azure Blob to a local file. Fails if the the given file path already exits. Offset and count are optional, pass 0 and undefined respectively to download the entire blob.

function downloadToFile(filePath: string, offset?: number, count?: number, options?: FileDownloadOptions): Promise<FileDownloadResponseModel>

Parameters

filePath

string

offset

number

From which position of the block blob to download.

count

number

How much data to be downloaded. Will download to the end when passing undefined.

options
FileDownloadOptions

Options to Blob download options.

Returns

The response data for blob download operation, but with readableStreamBody set to undefined since its content is already read and written into a local file at the specified path.

exists(FileExistsOptions)

Returns true if the specified file exists; false otherwise.

NOTE: use this function with care since an existing file might be deleted by other clients or applications. Vice versa new files might be added by other clients or applications after this function completes.

function exists(options?: FileExistsOptions): Promise<boolean>

Parameters

options
FileExistsOptions

options to Exists operation.

Returns

Promise<boolean>

forceCloseAllHandles(FileForceCloseHandlesOptions)

Force close all handles for a file.

See https://docs.microsoft.com/en-us/rest/api/storageservices/force-close-handles

function forceCloseAllHandles(options?: FileForceCloseHandlesOptions): Promise<CloseHandlesInfo>

Parameters

options
FileForceCloseHandlesOptions

Options to force close handles operation.

Returns

Promise<CloseHandlesInfo>

forceCloseHandle(string, FileForceCloseHandlesOptions)

Force close a specific handle for a file.

See https://docs.microsoft.com/en-us/rest/api/storageservices/force-close-handles

function forceCloseHandle(handleId: string, options?: FileForceCloseHandlesOptions): Promise<FileForceCloseHandlesResponse>

Parameters

handleId

string

Specific handle ID, cannot be asterisk "*". Use forceCloseAllHandles() to close all handles.

Returns

generateSasUrl(FileGenerateSasUrlOptions)

Only available for clients constructed with a shared key credential.

Generates a Service Shared Access Signature (SAS) URI based on the client properties and parameters passed in. The SAS is signed by the shared key credential of the client.

See https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas

function generateSasUrl(options: FileGenerateSasUrlOptions): string

Parameters

options
FileGenerateSasUrlOptions

Optional parameters.

Returns

string

The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token.

getProperties(FileGetPropertiesOptions)

Returns all user-defined metadata, standard HTTP properties, and system properties for the file. It does not return the content of the file.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-file-properties

function getProperties(options?: FileGetPropertiesOptions): Promise<FileGetPropertiesResponse>

Parameters

options
FileGetPropertiesOptions

Options to File Get Properties operation.

Returns

Response data for the File Get Properties operation.

getRangeList(FileGetRangeListOptions)

Returns the list of valid ranges for a file.

function getRangeList(options?: FileGetRangeListOptions): Promise<FileGetRangeListResponse>

Parameters

options
FileGetRangeListOptions

Options to File Get range List operation.

Returns

getRangeListDiff(string, FileGetRangeListOptions)

Returns the list of ranges that differ between a previous share snapshot and this file.

function getRangeListDiff(prevShareSnapshot: string, options?: FileGetRangeListOptions): Promise<FileGetRangeListDiffResponse>

Parameters

prevShareSnapshot

string

The previous snapshot parameter is an opaque DateTime value that specifies the previous share snapshot to compare with.

Returns

getShareLeaseClient(string)

Get a ShareLeaseClient that manages leases on the file.

function getShareLeaseClient(proposeLeaseId?: string): ShareLeaseClient

Parameters

proposeLeaseId

string

Initial proposed lease Id.

Returns

A new ShareLeaseClient object for managing leases on the file.

listHandles(FileListHandlesOptions)

Returns an async iterable iterator to list all the handles. under the specified account.

.byPage() returns an async iterable iterator to list the handles in pages.

function listHandles(options?: FileListHandlesOptions): PagedAsyncIterableIterator<HandleItem, FileListHandlesResponse, PageSettings>

Parameters

options
FileListHandlesOptions

Options to list handles operation.

An asyncIterableIterator that supports paging.

Returns

PagedAsyncIterableIterator<HandleItem, FileListHandlesResponse, PageSettings>

rename(string, FileRenameOptions)

Renames a file. This API only supports renaming a file in the same share.

function rename(destinationPath: string, options?: FileRenameOptions): Promise<{ destinationFileClient: ShareFileClient, fileRenameResponse: FileRenameResponse }>

Parameters

destinationPath

string

Specifies the destination path to rename to. The path will be encoded to put into a URL to specify the destination.

options
FileRenameOptions

Options for the renaming operation.

Returns

Promise<{ destinationFileClient: ShareFileClient, fileRenameResponse: FileRenameResponse }>

Response data for the file renaming operation.

Example usage:


// Rename the file
await fileClient.rename(destinationPath);
console.log("Renamed file successfully!");

resize(number, FileResizeOptions)

Resize file.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-properties

function resize(length: number, options?: FileResizeOptions): Promise<FileSetHTTPHeadersResponse>

Parameters

length

number

Resizes a file to the specified size in bytes. If the specified byte value is less than the current size of the file, then all ranges above the specified byte value are cleared.

options
FileResizeOptions

Options to File Resize operation.

Returns

Response data for the File Set HTTP Headers operation.

setHttpHeaders(FileHttpHeaders, FileSetHttpHeadersOptions)

Sets HTTP headers on the file.

If no option provided, or no value provided for the file HTTP headers in the options, these file HTTP headers without a value will be cleared.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-properties

function setHttpHeaders(fileHttpHeaders?: FileHttpHeaders, options?: FileSetHttpHeadersOptions): Promise<FileSetHTTPHeadersResponse>

Parameters

fileHttpHeaders
FileHttpHeaders
options
FileSetHttpHeadersOptions

Options to File Set HTTP Headers operation.

Returns

Response data for the File Set HTTP Headers operation.

setMetadata(Metadata, FileSetMetadataOptions)

Updates user-defined metadata for the specified file.

If no metadata defined in the option parameter, the file metadata will be removed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-metadata

function setMetadata(metadata?: Metadata, options?: FileSetMetadataOptions): Promise<FileSetMetadataResponse>

Parameters

metadata
Metadata

If no metadata provided, all existing directory metadata will be removed

options
FileSetMetadataOptions

Options to File Set Metadata operation.

Returns

Response data for the File Set Metadata operation.

setProperties(FileProperties)

Sets properties on the file.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-properties

function setProperties(properties?: FileProperties): Promise<SetPropertiesResponse>

Parameters

properties
FileProperties

File properties. For file HTTP headers(e.g. Content-Type), if no values are provided, existing HTTP headers will be removed. For other file properties(e.g. fileAttributes), if no values are provided, existing values will be preserved.

Returns

startCopyFromURL(string, FileStartCopyOptions)

Copies a blob or file to a destination file within the storage account.

function startCopyFromURL(copySource: string, options?: FileStartCopyOptions): Promise<FileStartCopyResponse>

Parameters

copySource

string

Specifies the URL of the source file or blob, up to 2 KB in length. To copy a file to another file within the same storage account, you may use Shared Key to authenticate the source file. If you are copying a file from another storage account, or if you are copying a blob from the same storage account or another storage account, then you must authenticate the source file or blob using a shared access signature. If the source is a public blob, no authentication is required to perform the copy operation. A file in a share snapshot can also be specified as a copy source.

options
FileStartCopyOptions

Options to File Start Copy operation.

Returns

uploadData(Blob | ArrayBuffer | ArrayBufferView | Buffer, FileParallelUploadOptions)

Creates a new Azure File or replaces an existing Azure File, and then uploads a Buffer(Node)/Blob/ArrayBuffer/ArrayBufferView to it.

function uploadData(data: Blob | ArrayBuffer | ArrayBufferView | Buffer, options?: FileParallelUploadOptions): Promise<void>

Parameters

data

Blob | ArrayBuffer | ArrayBufferView | Buffer

Buffer(Node), Blob, ArrayBuffer or ArrayBufferView

Returns

Promise<void>

uploadFile(string, FileParallelUploadOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Creates a new Azure File or replaces an existing Azure File, and then uploads a local file to it.

function uploadFile(filePath: string, options?: FileParallelUploadOptions): Promise<void>

Parameters

filePath

string

Full path of local file

Returns

Promise<void>

uploadRange(HttpRequestBody, number, number, FileUploadRangeOptions)

Upload a range of bytes to a file. This operation can only be called on an existing file. It won't change the size, properties or metadata of the file. Both the start and count of the range must be specified. The range can be up to 4 MB in size.

function uploadRange(body: HttpRequestBody, offset: number, contentLength: number, options?: FileUploadRangeOptions): Promise<FileUploadRangeResponse>

Parameters

body
HttpRequestBody

Blob, string, ArrayBuffer, ArrayBufferView or a function which returns a new Readable stream whose offset is from data source beginning.

offset

number

Offset position of the destination Azure File to upload.

contentLength

number

Length of body in bytes. Use Buffer.byteLength() to calculate body length for a string including non non-Base64/Hex-encoded characters.

options
FileUploadRangeOptions

Options to File Upload Range operation.

Returns

Response data for the File Upload Range operation.

Example usage:

const content = "Hello world!";

// Create the file
await fileClient.create(content.length);
console.log("Created file successfully!");

// Then upload data to the file
await fileClient.uploadRange(content, 0, content.length);
console.log("Updated file successfully!")

uploadRangeFromURL(string, number, number, number, FileUploadRangeFromURLOptions)

Upload a range of bytes to a file where the contents are read from a another file's URL. The range can be up to 4 MB in size.

function uploadRangeFromURL(sourceURL: string, sourceOffset: number, destOffset: number, count: number, options?: FileUploadRangeFromURLOptions): Promise<FileUploadRangeFromURLResponse>

Parameters

sourceURL

string

Specify a URL to the copy source, Shared Access Signature(SAS) maybe needed for authentication.

sourceOffset

number

The source offset to copy from. Pass 0 to copy from the beginning of source file.

destOffset

number

Offset of destination file.

count

number

Number of bytes to be uploaded from source file.

options
FileUploadRangeFromURLOptions

Options to configure File - Upload Range from URL operation.

Returns

uploadResetableStream((offset: number, count?: number) => ReadableStream, number, FileParallelUploadOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Accepts a Node.js Readable stream factory, and uploads in blocks to an Azure File. The Readable stream factory must returns a Node.js Readable stream starting from the offset defined. The offset is the offset in the Azure file to be uploaded.

function uploadResetableStream(streamFactory: (offset: number, count?: number) => ReadableStream, size: number, options?: FileParallelUploadOptions): Promise<void>

Parameters

streamFactory

(offset: number, count?: number) => ReadableStream

Returns a Node.js Readable stream starting from the offset defined

size

number

Size of the Azure file

Returns

Promise<void>

uploadSeekableBlob((offset: number, size: number) => Blob, number, FileParallelUploadOptions)

ONLY AVAILABLE IN BROWSERS.

Uploads a browser Blob object to an Azure file. Requires a blobFactory as the data source, which need to return a Blob object with the offset and size provided.

function uploadSeekableBlob(blobFactory: (offset: number, size: number) => Blob, size: number, options?: FileParallelUploadOptions): Promise<void>

Parameters

blobFactory

(offset: number, size: number) => Blob

size

number

Returns

Promise<void>

uploadStream(Readable, number, number, number, FileUploadStreamOptions)

ONLY AVAILABLE IN NODE.JS RUNTIME.

Creates a new Azure File or replaces an existing Azure File, and then uploads a Node.js Readable stream into it. This method will try to create an Azure File, then starts uploading chunk by chunk. Size of chunk is defined by bufferSize parameter. Please make sure potential size of stream doesn't exceed file size.

PERFORMANCE IMPROVEMENT TIPS:

  • Input stream highWaterMark is better to set a same value with bufferSize parameter, which will avoid Buffer.concat() operations.
function uploadStream(stream: Readable, size: number, bufferSize: number, maxBuffers: number, options?: FileUploadStreamOptions): Promise<void>

Parameters

stream

Readable

Node.js Readable stream. Must be less or equal than file size.

size

number

Size of file to be created. Maximum size allowed is 4 TB. If this value is larger than stream size, there will be empty bytes in file tail.

bufferSize

number

Size of every buffer allocated in bytes, also the chunk/range size during the uploaded file. Size must be greater than 0 and lesser than or equal to 4 * 1024 * 1024 (4MB)

maxBuffers

number

Max buffers will allocate during uploading, positive correlation with max uploading concurrency

Returns

Promise<void>

withShareSnapshot(string)

Creates a new ShareFileClient object identical to the source but with the specified share snapshot timestamp. Provide "" will remove the snapshot and return a URL to the base ShareFileClient.

function withShareSnapshot(shareSnapshot: string): ShareFileClient

Parameters

shareSnapshot

string

The share snapshot timestamp.

Returns

A new ShareFileClient object identical to the source but with the specified share snapshot timestamp.