FileURL class

Package:

@azure/storage-file

A FileURL represents a URL to an Azure Storage file.

Extends

StorageURL

Constructors

FileURL(string, Pipeline)

Creates an instance of FileURL.

Properties

pipeline	Request policy pipeline.
url	URL string value.

Methods

abortCopyFromURL(Aborter, string)	Aborts a pending Copy File operation, and leaves a destination file with zero length and full metadata.
clearRange(Aborter, number, number)	Clears the specified range and releases the space used in storage for that range.
create(Aborter, number, IFileCreateOptions)	Creates a new file or replaces a file. Note it only initializes the file with no content.
delete(Aborter)	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)
download(Aborter, number, undefined | number, IFileDownloadOptions)	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 blobBody
forceCloseHandle(Aborter, string)	Force close a specific handle for a file.
forceCloseHandlesSegment(Aborter, undefined | string)	Force close all handles for a file.
fromDirectoryURL(DirectoryURL, string)	Creates a FileURL object from a DirectoryURL object.
getProperties(Aborter)	Returns all user-defined metadata, standard HTTP properties, and system properties for the file. It does not return the content of the file.
getRangeList(Aborter, IFileGetRangeListOptions)	Returns the list of valid ranges for a file.
listHandlesSegment(Aborter, undefined | string, IFileListHandlesSegmentOptions)	Lists handles for a file.
newPipeline(Credential, INewPipelineOptions)	A static method used to create a new Pipeline object with Credential provided.
resize(Aborter, number)	Resize file.
setHTTPHeaders(Aborter, IFileHTTPHeaders)	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.
setMetadata(Aborter, IMetadata)	Updates user-defined metadata for the specified file. If no metadata defined in the option parameter, the file metadata will be removed.
setProperties(Aborter, IFileProperties)	Sets properties on the file.
startCopyFromURL(Aborter, string, IFileStartCopyOptions)	Copies a blob or file to a destination file within the storage account.
uploadRange(Aborter, HttpRequestBody, number, number, IFileUploadRangeOptions)	Upload a range of bytes to a file. Both the start and count of the range must be specified. The range can be up to 4 MB in size.
uploadRangeFromURL(Aborter, string, number, number, number)	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.
withPipeline(Pipeline)	Creates a new FileURL object identical to the source but with the specified request policy pipeline.

Constructor Details

FileURL(string, Pipeline)

Creates an instance of FileURL.

new FileURL(url: string, pipeline: Pipeline)

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 StorageURL.newPipeline() to create a default pipeline, or provide a customized pipeline.

Property Details

pipeline

Request policy pipeline.

pipeline: Pipeline

Property Value

Pipeline

url

URL string value.

url: string

Property Value

string

Method Details

abortCopyFromURL(Aborter, string)

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

function abortCopyFromURL(aborter: Aborter, copyId: string)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

copyId

string

Returns

Promise<Models.FileAbortCopyResponse>

clearRange(Aborter, number, number)

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

function clearRange(aborter: Aborter, offset: number, contentLength: number)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

offset

number

contentLength

number

Returns

Promise<Models.FileUploadRangeResponse>

create(Aborter, number, IFileCreateOptions)

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

function create(aborter: Aborter, size: number, options?: IFileCreateOptions)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

size

number

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

options

IFileCreateOptions

Returns

Promise<Models.FileCreateResponse>

delete(Aborter)

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)

function delete(aborter: Aborter)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

Returns

Promise<Models.FileDeleteResponse>

download(Aborter, number, undefined | number, IFileDownloadOptions)

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 blobBody

function download(aborter: Aborter, offset: number, count?: undefined | number, options?: IFileDownloadOptions)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

offset

number

From which position of the file to download, >= 0

count

undefined | number

options

IFileDownloadOptions

Returns

Promise<Models.FileDownloadResponse>

forceCloseHandle(Aborter, string)

Force close a specific handle for a file.

function forceCloseHandle(aborter: Aborter, handleId: string)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

handleId

string

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

Returns

Promise<Models.FileForceCloseHandlesResponse>

forceCloseHandlesSegment(Aborter, undefined | string)

Force close all handles for a file.

function forceCloseHandlesSegment(aborter: Aborter, marker?: undefined | string)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

marker

undefined | string

Returns

Promise<Models.FileForceCloseHandlesResponse>

fromDirectoryURL(DirectoryURL, string)

Creates a FileURL object from a DirectoryURL object.

static function fromDirectoryURL(directoryURL: DirectoryURL, fileName: string)

Parameters

directoryURL

DirectoryURL

A DirectoryURL object

fileName

string

A file name

Returns

FileURL

getProperties(Aborter)

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

function getProperties(aborter: Aborter)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

Returns

Promise<Models.FileGetPropertiesResponse>

getRangeList(Aborter, IFileGetRangeListOptions)

Returns the list of valid ranges for a file.

function getRangeList(aborter: Aborter, options?: IFileGetRangeListOptions)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

options

IFileGetRangeListOptions

Returns

Promise<FileGetRangeListResponse>

listHandlesSegment(Aborter, undefined | string, IFileListHandlesSegmentOptions)

Lists handles for a file.

function listHandlesSegment(aborter: Aborter, marker?: undefined | string, options?: IFileListHandlesSegmentOptions)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

marker

undefined | string

options

IFileListHandlesSegmentOptions

Returns

Promise<Models.FileListHandlesResponse>

newPipeline(Credential, INewPipelineOptions)

A static method used to create a new Pipeline object with Credential provided.

static function newPipeline(credential: Credential, pipelineOptions?: INewPipelineOptions)

Parameters

credential

Credential

Such as AnonymousCredential, SharedKeyCredential.

pipelineOptions

INewPipelineOptions

Returns

Pipeline

A new Pipeline object.

resize(Aborter, number)

Resize file.

function resize(aborter: Aborter, length: number)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

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.

Returns

Promise<Models.FileSetHTTPHeadersResponse>

setHTTPHeaders(Aborter, IFileHTTPHeaders)

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.

function setHTTPHeaders(aborter: Aborter, fileHTTPHeaders?: IFileHTTPHeaders)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

fileHTTPHeaders

IFileHTTPHeaders

Returns

Promise<Models.FileSetHTTPHeadersResponse>

setMetadata(Aborter, IMetadata)

Updates user-defined metadata for the specified file. If no metadata defined in the option parameter, the file metadata will be removed.

function setMetadata(aborter: Aborter, metadata?: IMetadata)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

metadata

IMetadata

Returns

Promise<Models.FileSetMetadataResponse>

setProperties(Aborter, IFileProperties)

Sets properties on the file.

function setProperties(aborter: Aborter, properties?: IFileProperties)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

properties

IFileProperties

Returns

Promise<ISetPropertiesResponse>

startCopyFromURL(Aborter, string, IFileStartCopyOptions)

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

function startCopyFromURL(aborter: Aborter, copySource: string, options?: IFileStartCopyOptions)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation

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

IFileStartCopyOptions

Returns

Promise<Models.FileStartCopyResponse>

uploadRange(Aborter, HttpRequestBody, number, number, IFileUploadRangeOptions)

Upload a range of bytes to a file. Both the start and count of the range must be specified. The range can be up to 4 MB in size.

function uploadRange(aborter: Aborter, body: HttpRequestBody, offset: number, contentLength: number, options?: IFileUploadRangeOptions)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation.

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

IFileUploadRangeOptions

Returns

Promise<Models.FileUploadRangeResponse>

uploadRangeFromURL(Aborter, string, number, number, number)

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(aborter: Aborter, sourceURL: string, sourceOffset: number, destOffset: number, count: number)

Parameters

aborter

Aborter

Create a new Aborter instance with Aborter.none or Aborter.timeout(), goto documents of Aborter for more examples about request cancellation.

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.

Returns

Promise<Models.FileUploadRangeFromURLResponse>

withPipeline(Pipeline)

Creates a new FileURL object identical to the source but with the specified request policy pipeline.

function withPipeline(pipeline: Pipeline)

Parameters

pipeline

Pipeline

Returns

FileURL