ShareClient class

Reference

Package:: @azure/storage-file-share

A ShareClient represents a URL to the Azure Storage share allowing you to manipulate its directories and files.

Extends: StorageClient

Constructors

ShareClient(string, Credential_2 \| TokenCredential, ShareClientOptions)	Creates an instance of ShareClient.
ShareClient(string, Pipeline, ShareClientConfig)	Creates an instance of ShareClient.
ShareClient(string, string, ShareClientOptions)

Properties

name

The name of the share

rootDirectoryClient

Gets the directory client for the root directory of this share. Note that the root directory always exists and cannot be deleted.

A new ShareDirectoryClient object for the root directory.

Inherited Properties

accountName
url	URL string value.

Methods

create(ShareCreateOptions)	Creates a new share under the specified account. If the share with the same name already exists, the operation fails. See https://docs.microsoft.com/en-us/rest/api/storageservices/create-share
createDirectory(string, DirectoryCreateOptions)	Creates a new subdirectory under this share. See https://docs.microsoft.com/en-us/rest/api/storageservices/create-directory
createFile(string, number, FileCreateOptions)	Creates a new file or replaces a file under the root directory of this share. Note it only initializes the file with no content. See https://docs.microsoft.com/en-us/rest/api/storageservices/create-file
createIfNotExists(ShareCreateOptions)	Creates a new share under the specified account. If the share with the same name already exists, it is not changed. See https://docs.microsoft.com/en-us/rest/api/storageservices/create-share
createPermission(string, ShareCreatePermissionOptions)	Creates a file permission (a security descriptor) at the share level. The created security descriptor can be used for the files/directories in the share. See https://docs.microsoft.com/en-us/rest/api/storageservices/create-permission
createSnapshot(ShareCreateSnapshotOptions)	Creates a read-only snapshot of a share.
delete(ShareDeleteMethodOptions)	Marks the specified share for deletion. The share and any directories or files contained within it are later deleted during garbage collection. See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-share
deleteDirectory(string, DirectoryDeleteOptions)	Removes the specified empty sub directory under this share. Note that the directory must be empty before it can be deleted. See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-directory
deleteFile(string, FileDeleteOptions)	Removes a file under the root directory of this share 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(ShareDeleteMethodOptions)	Marks the specified share for deletion if it exists. The share and any directories or files contained within it are later deleted during garbage collection. See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-share
exists(ShareExistsOptions)	Returns true if the Azrue share resource represented by this client exists; false otherwise. NOTE: use this function with care since an existing share might be deleted by other clients or applications. Vice versa new shares might be added by other clients or applications after this function completes.
generateSasUrl(ShareGenerateSasUrlOptions)	Only available for ShareClient 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
getAccessPolicy(ShareGetAccessPolicyOptions)	Gets the permissions for the specified share. The permissions indicate whether share data may be accessed publicly. WARNING: JavaScript Date will potential lost precision when parsing start and expiry string. For example, new Date("2018-12-31T03:44:23.8827891Z").toISOString() will get "2018-12-31T03:44:23.882Z". See https://docs.microsoft.com/en-us/rest/api/storageservices/get-share-acl
getDirectoryClient(string)	Creates a ShareDirectoryClient object.
getPermission(string, ShareGetPermissionOptions)	Gets the Security Descriptor Definition Language (SDDL) for a given file permission key which indicates a security descriptor. See https://docs.microsoft.com/en-us/rest/api/storageservices/get-permission
getProperties(ShareGetPropertiesOptions)	Returns all user-defined metadata and system properties for the specified share. See https://docs.microsoft.com/en-us/rest/api/storageservices/get-share-properties WARNING: The `metadata` object returned in the response will have its keys in lowercase, even if they originally contained uppercase characters. This differs from the metadata keys returned by the `listShares` method of ShareServiceClient using the `includeMetadata` option, which will retain their original casing.
getStatistics(ShareGetStatisticsOptions)	Retrieves statistics related to the share.
setAccessPolicy(SignedIdentifier[], ShareSetAccessPolicyOptions)	Sets the permissions for the specified share. The permissions indicate whether directories or files in a share may be accessed publicly. When you set permissions for a share, the existing permissions are replaced. If no shareAcl provided, the existing share ACL will be removed. When you establish a stored access policy on a share, it may take up to 30 seconds to take effect. During this interval, a shared access signature that is associated with the stored access policy will fail with status code 403 (Forbidden), until the access policy becomes active. See https://docs.microsoft.com/en-us/rest/api/storageservices/set-share-acl
setMetadata(Metadata, ShareSetMetadataOptions)	Sets one or more user-defined name-value pairs for the specified share. If no option provided, or no metadata defined in the option parameter, the share metadata will be removed. See https://docs.microsoft.com/en-us/rest/api/storageservices/set-share-metadata
setProperties(ShareSetPropertiesOptions)	Sets properties of the share.
setQuota(number, ShareSetQuotaOptions)	Sets quota for the specified share.
withSnapshot(string)	Creates a new ShareClient object identical to the source but with the specified snapshot timestamp. Provide "" will remove the snapshot and return a URL to the base share.

Constructor Details

Creates an instance of ShareClient.

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

Parameters

url: string

A URL string pointing to Azure Storage file share, such as "https://myaccount.file.core.windows.net/share". You can append a SAS if using AnonymousCredential, such as "https://myaccount.file.core.windows.net/share?sasString".

credential: Credential | TokenCredential

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

options: ShareClientOptions

Optional. Options to configure the HTTP pipeline.

Creates an instance of ShareClient.

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

Parameters

url: string

pipeline: Pipeline

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

options: ShareClientConfig

new ShareClient(connectionString: string, name: string, options?: ShareClientOptions)

Parameters

connectionString: string

Account connection string or a SAS connection string of an Azure storage account. [ Note - Account connection string can only be used in NODE.JS runtime. ] Account connection string example - DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=accountKey;EndpointSuffix=core.windows.net SAS connection string example - BlobEndpoint=https://myaccount.blob.core.windows.net/;QueueEndpoint=https://myaccount.queue.core.windows.net/;FileEndpoint=https://myaccount.file.core.windows.net/;TableEndpoint=https://myaccount.table.core.windows.net/;SharedAccessSignature=sasString

name: string

Share name.

options: ShareClientOptions

Optional. Options to configure the HTTP pipeline.

Property Details

The name of the share

string name

Property Value

string

Gets the directory client for the root directory of this share. Note that the root directory always exists and cannot be deleted.

A new ShareDirectoryClient object for the root directory.

ShareDirectoryClient rootDirectoryClient

Property Value

ShareDirectoryClient

Inherited Property Details

accountName: string

Property Value

string

Inherited From StorageClient.accountName

URL string value.

url: string

Property Value

string

Inherited From StorageClient.url

Method Details

Creates a new share under the specified account. If the share with the same name already exists, the operation fails.

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

function create(options?: ShareCreateOptions): Promise<ShareCreateResponse>

Parameters

options: ShareCreateOptions

Options to Share Create operation.

Returns

Promise<ShareCreateResponse>

Response data for the Share Create operation.

Creates a new subdirectory under this share.

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

function createDirectory(directoryName: string, options?: DirectoryCreateOptions): Promise<{ directoryClient: ShareDirectoryClient, directoryCreateResponse: DirectoryCreateResponse }>

Parameters

directoryName: string

options: DirectoryCreateOptions

Options to Directory Create operation.

Returns

Promise<{ directoryClient: ShareDirectoryClient, directoryCreateResponse: DirectoryCreateResponse }>

Directory creation response data and the corresponding directory client.

Creates a new file or replaces a file under the root directory of this share. Note it only initializes the file with no content.

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

function createFile(fileName: string, size: number, options?: FileCreateOptions): Promise<{ fileClient: ShareFileClient, fileCreateResponse: FileCreateResponse }>

Parameters

fileName: string

size: number

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

options: FileCreateOptions

Options to File Create operation.

Returns

Promise<{ fileClient: ShareFileClient, fileCreateResponse: FileCreateResponse }>

File creation response data and the corresponding file client.

Creates a new share under the specified account. If the share with the same name already exists, it is not changed.

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

function createIfNotExists(options?: ShareCreateOptions): Promise<ShareCreateIfNotExistsResponse>

Parameters

options: ShareCreateOptions

Returns

Promise<ShareCreateIfNotExistsResponse>

Creates a file permission (a security descriptor) at the share level. The created security descriptor can be used for the files/directories in the share.

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

function createPermission(filePermission: string, options?: ShareCreatePermissionOptions): Promise<ShareCreatePermissionResponse>

Parameters

filePermission: string

File permission described in the SDDL

options: ShareCreatePermissionOptions

Options to Share Create Permission operation.

Returns

Promise<ShareCreatePermissionResponse>

Creates a read-only snapshot of a share.

function createSnapshot(options?: ShareCreateSnapshotOptions): Promise<ShareCreateSnapshotResponse>

Parameters

options: ShareCreateSnapshotOptions

Options to Share Create Snapshot operation.

Returns

Promise<ShareCreateSnapshotResponse>

Response data for the Share Create Snapshot operation.

Marks the specified share for deletion. The share and any directories or files contained within it are later deleted during garbage collection.

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

function delete(options?: ShareDeleteMethodOptions): Promise<ShareDeleteResponse>

Parameters

options: ShareDeleteMethodOptions

Options to Share Delete operation.

Returns

Promise<ShareDeleteResponse>

Response data for the Share Delete operation.

Removes the specified empty sub directory under this share. Note that the directory must be empty before it can be deleted.

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

function deleteDirectory(directoryName: string, options?: DirectoryDeleteOptions): Promise<DirectoryDeleteResponse>

Parameters

directoryName: string

options: DirectoryDeleteOptions

Options to Directory Delete operation.

Returns

Promise<DirectoryDeleteResponse>

Directory deletion response data.

Removes a file under the root directory of this share 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 deleteFile(fileName: string, options?: FileDeleteOptions): Promise<FileDeleteResponse>

Parameters

fileName: string

options: FileDeleteOptions

Options to File Delete operation.

Returns

Promise<FileDeleteResponse>

Promise File Delete response data.

Marks the specified share for deletion if it exists. The share and any directories or files contained within it are later deleted during garbage collection.

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

function deleteIfExists(options?: ShareDeleteMethodOptions): Promise<ShareDeleteIfExistsResponse>

Parameters

options: ShareDeleteMethodOptions

Returns

Promise<ShareDeleteIfExistsResponse>

Returns true if the Azrue share resource represented by this client exists; false otherwise.

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

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

Parameters

options: ShareExistsOptions

options to Exists operation.

Returns

Promise<boolean>

Only available for ShareClient 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: ShareGenerateSasUrlOptions): string

Parameters

options: ShareGenerateSasUrlOptions

Optional parameters.

Returns

string

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

Gets the permissions for the specified share. The permissions indicate whether share data may be accessed publicly.

WARNING: JavaScript Date will potential lost precision when parsing start and expiry string. For example, new Date("2018-12-31T03:44:23.8827891Z").toISOString() will get "2018-12-31T03:44:23.882Z".

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

function getAccessPolicy(options?: ShareGetAccessPolicyOptions): Promise<ShareGetAccessPolicyResponse>

Parameters

options: ShareGetAccessPolicyOptions

Returns

Promise<ShareGetAccessPolicyResponse>

Response data for the Share Get Access Policy operation.

Creates a ShareDirectoryClient object.

function getDirectoryClient(directoryName: string): ShareDirectoryClient

Parameters

directoryName: string

A directory name

Returns

ShareDirectoryClient

The ShareDirectoryClient object for the given directory name.

Gets the Security Descriptor Definition Language (SDDL) for a given file permission key which indicates a security descriptor.

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

function getPermission(filePermissionKey: string, options?: ShareGetPermissionOptions): Promise<ShareGetPermissionResponse>

Parameters

filePermissionKey: string

File permission key which indicates the security descriptor of the permission.

options: ShareGetPermissionOptions

Options to Share Create Permission operation.

Returns

Promise<ShareGetPermissionResponse>

Returns all user-defined metadata and system properties for the specified share.

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

WARNING: The metadata object returned in the response will have its keys in lowercase, even if they originally contained uppercase characters. This differs from the metadata keys returned by the listShares method of ShareServiceClient using the includeMetadata option, which will retain their original casing.

function getProperties(options?: ShareGetPropertiesOptions): Promise<ShareGetPropertiesResponse>

Parameters

options: ShareGetPropertiesOptions

Returns

Promise<ShareGetPropertiesResponse>

Response data for the Share Get Properties operation.

Retrieves statistics related to the share.

function getStatistics(options?: ShareGetStatisticsOptions): Promise<ShareGetStatisticsResponse>

Parameters

options: ShareGetStatisticsOptions

Returns

Promise<ShareGetStatisticsResponse>

Response data for the Share Get Statistics operation.

Sets the permissions for the specified share. The permissions indicate whether directories or files in a share may be accessed publicly.

When you set permissions for a share, the existing permissions are replaced. If no shareAcl provided, the existing share ACL will be removed.

When you establish a stored access policy on a share, it may take up to 30 seconds to take effect. During this interval, a shared access signature that is associated with the stored access policy will fail with status code 403 (Forbidden), until the access policy becomes active.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-share-acl

function setAccessPolicy(shareAcl?: SignedIdentifier[], options?: ShareSetAccessPolicyOptions): Promise<ShareSetAccessPolicyResponse>

Parameters

shareAcl: SignedIdentifier[]

Array of signed identifiers, each having a unique Id and details of access policy.

options: ShareSetAccessPolicyOptions

Returns

Promise<ShareSetAccessPolicyResponse>

Response data for the Share Set Access Policy operation.

Sets one or more user-defined name-value pairs for the specified share.

If no option provided, or no metadata defined in the option parameter, the share metadata will be removed.

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

function setMetadata(metadata?: Metadata, options?: ShareSetMetadataOptions): Promise<ShareSetMetadataResponse>

Parameters

metadata: Metadata

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

options: ShareSetMetadataOptions

Returns

Promise<ShareSetMetadataResponse>

Response data for the Share Set Metadata operation.

Sets properties of the share.

function setProperties(options?: ShareSetPropertiesOptions): Promise<ShareSetPropertiesResponse>

Parameters

options: ShareSetPropertiesOptions

Returns

Promise<ShareSetPropertiesResponse>

Response data for the Share Set Properties operation.

Warning

This API is now deprecated.

Use setProperties instead.

Sets quota for the specified share.

function setQuota(quotaInGB: number, options?: ShareSetQuotaOptions): Promise<ShareSetPropertiesResponse>

Parameters

quotaInGB: number

Specifies the maximum size of the share in gigabytes

options: ShareSetQuotaOptions

Returns

Promise<ShareSetPropertiesResponse>

Response data for the Share Get Quota operation.

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

function withSnapshot(snapshot: string): ShareClient

Parameters

snapshot: string

The snapshot timestamp.

Returns

ShareClient

A new ShareClient object identical to the source but with the specified snapshot timestamp

ShareClient class

Constructors

Properties

Inherited Properties

Methods

Constructor Details

ShareClient(string, Credential_2 | TokenCredential, ShareClientOptions)

Parameters

ShareClient(string, Pipeline, ShareClientConfig)

Parameters

ShareClient(string, string, ShareClientOptions)

Parameters

Property Details

name

Property Value

rootDirectoryClient

Property Value

Inherited Property Details

accountName

Property Value

url

Property Value

Method Details

create(ShareCreateOptions)

Parameters

Returns

createDirectory(string, DirectoryCreateOptions)

Parameters

Returns

createFile(string, number, FileCreateOptions)

Parameters

Returns

createIfNotExists(ShareCreateOptions)

Parameters

Returns

createPermission(string, ShareCreatePermissionOptions)

Parameters

Returns

createSnapshot(ShareCreateSnapshotOptions)

Parameters

Returns

delete(ShareDeleteMethodOptions)

Parameters

Returns

deleteDirectory(string, DirectoryDeleteOptions)

Parameters

Returns

deleteFile(string, FileDeleteOptions)

Parameters

Returns

deleteIfExists(ShareDeleteMethodOptions)

Parameters

Returns

exists(ShareExistsOptions)

Parameters

Returns

generateSasUrl(ShareGenerateSasUrlOptions)

Parameters

Returns

getAccessPolicy(ShareGetAccessPolicyOptions)

Parameters

Returns

getDirectoryClient(string)

Parameters

Returns

getPermission(string, ShareGetPermissionOptions)

Parameters

Returns

getProperties(ShareGetPropertiesOptions)

Parameters

Returns

getStatistics(ShareGetStatisticsOptions)

Parameters

Returns

setAccessPolicy(SignedIdentifier[], ShareSetAccessPolicyOptions)

Parameters

Returns

setMetadata(Metadata, ShareSetMetadataOptions)

Parameters

Returns