ShareClient class

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 | SharePermission, 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.

generateSasStringToSign(ShareGenerateSasUrlOptions)

Only available for ShareClient constructed with a shared key credential.

Generates string to sign for 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

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.

getShareLeaseClient(string)

Get a ShareLeaseClient that manages leases on the file.

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

ShareClient(string, Credential_2 | TokenCredential, ShareClientOptions)

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.

ShareClient(string, Pipeline, ShareClientConfig)

Creates an instance of ShareClient.

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

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".

pipeline
Pipeline

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

ShareClient(string, string, ShareClientOptions)

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

name

The name of the share

string name

Property Value

string

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.

ShareDirectoryClient rootDirectoryClient

Property Value

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

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

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

Parameters

options
ShareCreateOptions

Options to Share Create operation.

Returns

Response data for the Share Create operation.

createDirectory(string, DirectoryCreateOptions)

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.

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

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.

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

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

Parameters

Returns

createPermission(string | SharePermission, 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

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

Parameters

filePermission

string | SharePermission

File permission described in the SDDL

options
ShareCreatePermissionOptions

Options to Share Create Permission operation.

Returns

createSnapshot(ShareCreateSnapshotOptions)

Creates a read-only snapshot of a share.

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

Parameters

options
ShareCreateSnapshotOptions

Options to Share Create Snapshot operation.

Returns

Response data for the Share Create Snapshot operation.

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

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

Parameters

options
ShareDeleteMethodOptions

Options to Share Delete operation.

Returns

Response data for the Share Delete operation.

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

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

Parameters

directoryName

string

options
DirectoryDeleteOptions

Options to Directory Delete operation.

Returns

Directory deletion response data.

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

function deleteFile(fileName: string, options?: FileDeleteOptions): Promise<FileDeleteResponse>

Parameters

fileName

string

options
FileDeleteOptions

Options to File Delete operation.

Returns

Promise File Delete response data.

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

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

Parameters

Returns

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.

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

Parameters

options
ShareExistsOptions

options to Exists operation.

Returns

Promise<boolean>

generateSasStringToSign(ShareGenerateSasUrlOptions)

Only available for ShareClient constructed with a shared key credential.

Generates string to sign for 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 generateSasStringToSign(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.

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

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.

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

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

Parameters

Returns

Response data for the Share Get Access Policy operation.

getDirectoryClient(string)

Creates a ShareDirectoryClient object.

function getDirectoryClient(directoryName: string): ShareDirectoryClient

Parameters

directoryName

string

A directory name

Returns

The ShareDirectoryClient object for the given directory name.

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

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

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.

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

Parameters

Returns

Response data for the Share Get Properties operation.

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.

getStatistics(ShareGetStatisticsOptions)

Retrieves statistics related to the share.

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

Parameters

Returns

Response data for the Share Get Statistics operation.

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

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.

Returns

Response data for the Share Set Access Policy operation.

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

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

Parameters

metadata
Metadata

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

Returns

Response data for the Share Set Metadata operation.

setProperties(ShareSetPropertiesOptions)

Sets properties of the share.

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

Parameters

Returns

Response data for the Share Set Properties operation.

setQuota(number, ShareSetQuotaOptions)

Warning

This API is now deprecated.

Use setProperties instead.

Sets quota for the specified share.

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

Parameters

quotaInGB

number

Specifies the maximum size of the share in gigabytes

Returns

Response data for the Share Get Quota operation.

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.

function withSnapshot(snapshot: string): ShareClient

Parameters

snapshot

string

The snapshot timestamp.

Returns

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