Share via

ShareServiceClient class

  • Reference
Package:
@azure/storage-file-share

A ShareServiceClient represents a URL to the Azure Storage File service allowing you to manipulate file shares.

Extends

StorageClient

Constructors

ShareServiceClient(string, Credential_2 | TokenCredential, ShareClientOptions)

Creates an instance of ShareServiceClient.
ShareServiceClient(string, Pipeline, ShareClientConfig)

Creates an instance of ShareServiceClient.

Inherited Properties

accountName
url

URL string value.

Methods

createShare(string, ShareCreateOptions)

Creates a Share.
deleteShare(string, ShareDeleteMethodOptions)

Deletes a Share.
fromConnectionString(string, ShareClientOptions)

Creates an instance of ShareServiceClient from connection string.
generateAccountSasUrl(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for ShareServiceClient constructed with a shared key credential.

Generates an account 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/create-account-sas
generateSasStringToSign(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for ShareServiceClient constructed with a shared key credential.

Generates string to sign for an account 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/create-account-sas
getProperties(ServiceGetPropertiesOptions)

Gets the properties of a storage account’s file service, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-file-service-properties
getShareClient(string)

Creates a ShareClient object.
listShares(ServiceListSharesOptions)

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

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

Example using for await syntax:

let i = 1;
for await (const share of serviceClient.listShares()) {
  console.log(`Share ${i++}: ${share.name}`);
}

Example using iter.next():

let i = 1;
let iter = serviceClient.listShares();
let shareItem = await iter.next();
while (!shareItem.done) {
  console.log(`Share ${i++}: ${shareItem.value.name}`);
  shareItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of serviceClient.listShares().byPage({ maxPageSize: 20 })) {
  if (response.shareItems) {
   for (const share of response.shareItems) {
       console.log(`Share ${i++}: ${share.name}`);
    }
  }
}

Example using paging with a marker:

let i = 1;
let iterator = serviceClient.listShares().byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

// Prints 2 share names
if (response.shareItems) {
  for (const share of response.shareItems) {
    console.log(`Share ${i++}: ${share.name}`);
  }
}

// Gets next marker
let marker = response.continuationToken;

// Passing next marker as continuationToken
iterator = serviceClient.listShares().byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 share names
if (response.shareItems) {
  for (const share of response.shareItems) {
    console.log(`Share ${i++}: ${share.name}`);
  }
}
setProperties(FileServiceProperties, ServiceSetPropertiesOptions)

Sets properties for a storage account’s file service endpoint, including properties for Storage Analytics, CORS (Cross-Origin Resource Sharing) rules and soft delete settings.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-service-properties
undeleteShare(string, string, ServiceUndeleteShareOptions)

Restores a previously deleted share. This API is only functional if Share Soft Delete is enabled for the storage account associated with the share.

Constructor Details

ShareServiceClient(string, Credential_2 | TokenCredential, ShareClientOptions)

Creates an instance of ShareServiceClient.

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

Parameters

url

string

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

credential

Credential | TokenCredential

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

options
ShareClientOptions

Optional. Options to configure the HTTP pipeline.

ShareServiceClient(string, Pipeline, ShareClientConfig)

Creates an instance of ShareServiceClient.

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

Parameters

url

string

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

pipeline
Pipeline

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

options
ShareClientConfig

Optional. Options to configure the HTTP pipeline.

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

createShare(string, ShareCreateOptions)

Creates a Share.

function createShare(shareName: string, options?: ShareCreateOptions): Promise<{ shareClient: ShareClient, shareCreateResponse: ShareCreateResponse }>

Parameters

shareName

string

options
ShareCreateOptions

Returns

Promise<{ shareClient: ShareClient, shareCreateResponse: ShareCreateResponse }>

Share creation response and the corresponding share client.

deleteShare(string, ShareDeleteMethodOptions)

Deletes a Share.

function deleteShare(shareName: string, options?: ShareDeleteMethodOptions): Promise<ShareDeleteResponse>

Parameters

shareName

string

options
ShareDeleteMethodOptions

Returns

Promise<ShareDeleteResponse>

Share deletion response and the corresponding share client.

fromConnectionString(string, ShareClientOptions)

Creates an instance of ShareServiceClient from connection string.

static function fromConnectionString(connectionString: string, options?: ShareClientOptions): ShareServiceClient

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

options
ShareClientOptions

Options to configure the HTTP pipeline.

Returns

ShareServiceClient

A new ShareServiceClient from the given connection string.

generateAccountSasUrl(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for ShareServiceClient constructed with a shared key credential.

Generates an account 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/create-account-sas

function generateAccountSasUrl(expiresOn?: Date, permissions?: AccountSASPermissions, resourceTypes?: string, options?: ServiceGenerateAccountSasUrlOptions): string

Parameters

expiresOn

Date

Optional. The time at which the shared access signature becomes invalid. Default to an hour later if not specified.

permissions
AccountSASPermissions

Specifies the list of permissions to be associated with the SAS.

resourceTypes

string

Specifies the resource types associated with the shared access signature.

options
ServiceGenerateAccountSasUrlOptions

Optional parameters.

Returns

string

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

generateSasStringToSign(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for ShareServiceClient constructed with a shared key credential.

Generates string to sign for an account 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/create-account-sas

function generateSasStringToSign(expiresOn?: Date, permissions?: AccountSASPermissions, resourceTypes?: string, options?: ServiceGenerateAccountSasUrlOptions): string

Parameters

expiresOn

Date

Optional. The time at which the shared access signature becomes invalid. Default to an hour later if not specified.

permissions
AccountSASPermissions

Specifies the list of permissions to be associated with the SAS.

resourceTypes

string

Specifies the resource types associated with the shared access signature.

options
ServiceGenerateAccountSasUrlOptions

Optional parameters.

Returns

string

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

getProperties(ServiceGetPropertiesOptions)

Gets the properties of a storage account’s file service, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

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

function getProperties(options?: ServiceGetPropertiesOptions): Promise<ServiceGetPropertiesResponse>

Parameters

options
ServiceGetPropertiesOptions

Options to Get Properties operation.

Returns

Promise<ServiceGetPropertiesResponse>

Response data for the Get Properties operation.

getShareClient(string)

Creates a ShareClient object.

function getShareClient(shareName: string): ShareClient

Parameters

shareName

string

Name of a share.

Returns

ShareClient

The ShareClient object for the given share name.

Example usage:

const shareClient = serviceClient.getShareClient("<share name>");
await shareClient.create();
console.log("Created share successfully!");

listShares(ServiceListSharesOptions)

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

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

Example using for await syntax:

let i = 1;
for await (const share of serviceClient.listShares()) {
  console.log(`Share ${i++}: ${share.name}`);
}

Example using iter.next():

let i = 1;
let iter = serviceClient.listShares();
let shareItem = await iter.next();
while (!shareItem.done) {
  console.log(`Share ${i++}: ${shareItem.value.name}`);
  shareItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of serviceClient.listShares().byPage({ maxPageSize: 20 })) {
  if (response.shareItems) {
   for (const share of response.shareItems) {
       console.log(`Share ${i++}: ${share.name}`);
    }
  }
}

Example using paging with a marker:

let i = 1;
let iterator = serviceClient.listShares().byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

// Prints 2 share names
if (response.shareItems) {
  for (const share of response.shareItems) {
    console.log(`Share ${i++}: ${share.name}`);
  }
}

// Gets next marker
let marker = response.continuationToken;

// Passing next marker as continuationToken
iterator = serviceClient.listShares().byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 share names
if (response.shareItems) {
  for (const share of response.shareItems) {
    console.log(`Share ${i++}: ${share.name}`);
  }
}

function listShares(options?: ServiceListSharesOptions): PagedAsyncIterableIterator<ShareItem, ServiceListSharesSegmentResponse, PageSettings>

Parameters

options
ServiceListSharesOptions

Options to list shares operation.

An asyncIterableIterator that supports paging.

Returns

PagedAsyncIterableIterator<ShareItem, ServiceListSharesSegmentResponse, PageSettings>

setProperties(FileServiceProperties, ServiceSetPropertiesOptions)

Sets properties for a storage account’s file service endpoint, including properties for Storage Analytics, CORS (Cross-Origin Resource Sharing) rules and soft delete settings.

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

function setProperties(properties: FileServiceProperties, options?: ServiceSetPropertiesOptions): Promise<ServiceSetPropertiesResponse>

Parameters

properties
FileServiceProperties
options
ServiceSetPropertiesOptions

Options to Set Properties operation.

Returns

Promise<ServiceSetPropertiesResponse>

Response data for the Set Properties operation.

undeleteShare(string, string, ServiceUndeleteShareOptions)

Restores a previously deleted share. This API is only functional if Share Soft Delete is enabled for the storage account associated with the share.

function undeleteShare(deletedShareName: string, deletedShareVersion: string, options?: ServiceUndeleteShareOptions): Promise<ShareClient>

Parameters

deletedShareName

string

The name of the previously deleted share.

deletedShareVersion

string

The version of the previously deleted share.

options
ServiceUndeleteShareOptions

Options to Share undelete operation.

Returns

Promise<ShareClient>

Restored share.