Feedback Edit

ShareServiceClient Class

  • Reference

A client to interact with the File Share Service at the account level.

This client provides operations to retrieve and configure the account properties as well as list, create and delete shares within the account. For operations relating to a specific share, a client for that entity can also be retrieved using the get_share_client function.

Inheritance
azure.storage.fileshare._shared.base_client_async.AsyncStorageAccountHostsMixin
ShareServiceClient
azure.storage.fileshare._share_service_client.ShareServiceClient
ShareServiceClient

Constructor

ShareServiceClient(account_url: str, credential: Optional[Any] = None, **kwargs: Any)

Parameters

account_url
str
Required

The URL to the file share storage account. Any other entities included in the URL path (e.g. share or file) will be discarded. This URL can be optionally authenticated with a SAS token.

credential
default value: None

The credential with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, an instance of a AzureSasCredential from azure.core.credentials or an account shared access key.

api_version
str

The Storage API version to use for requests. Default value is the most recent service version that is compatible with the current SDK. Setting to an older version may result in reduced feature compatibility.

New in version 12.1.0.

secondary_hostname
str

The hostname of the secondary endpoint.

loop

The event loop to run the asynchronous tasks.

max_range_size
int

The maximum range size used for a file upload. Defaults to 4*1024*1024.

Examples

Create the share service client with url and credential.


   from azure.storage.fileshare.aio import ShareServiceClient
   share_service_client = ShareServiceClient(
       account_url=self.account_url,
       credential=self.access_key
   )

Methods

create_share

Creates a new share under the specified account. If the share with the same name already exists, the operation fails. Returns a client with which to interact with the newly created share.
delete_share

Marks the specified share for deletion. The share is later deleted during garbage collection.
get_service_properties

Gets the properties of a storage account's File Share service, including Azure Storage Analytics.
get_share_client

Get a client to interact with the specified share. The share need not already exist.
list_shares

Returns auto-paging iterable of dict-like ShareProperties under the specified account. The generator will lazily follow the continuation tokens returned by the service and stop when all shares have been returned.
set_service_properties

Sets the properties of a storage account's File Share service, including Azure Storage Analytics. If an element (e.g. hour_metrics) is left as None, the existing settings on the service for that functionality are preserved.
undelete_share

Restores soft-deleted share.

Operation will only be successful if used within the specified number of days set in the delete retention policy.

New in version 12.2.0: This operation was introduced in API version '2019-12-12'.

create_share

Creates a new share under the specified account. If the share with the same name already exists, the operation fails. Returns a client with which to interact with the newly created share.

async create_share(share_name: str, **kwargs) -> azure.storage.fileshare.aio._share_client_async.ShareClient

Parameters

share_name
str
Required

The name of the share to create.

metadata
dict(<xref:str,str>)

A dict with name_value pairs to associate with the share as metadata. Example:{'Category':'test'}

quota
int

Quota in bytes.

timeout
int

The timeout parameter is expressed in seconds.

Return type

ShareClient

Examples

Create a share in the file share service.


   await file_service.create_share(share_name="fileshare1")

delete_share

Marks the specified share for deletion. The share is later deleted during garbage collection.

async delete_share(share_name: Union[ShareProperties, str], delete_snapshots: Optional[bool] = False, **kwargs) -> None

Parameters

share_name
str or ShareProperties
Required

The share to delete. This can either be the name of the share, or an instance of ShareProperties.

delete_snapshots
bool
Required

Indicates if snapshots are to be deleted.

timeout
int

The timeout parameter is expressed in seconds.

Return type

None

Examples

Delete a share in the file share service.


   await file_service.delete_share(share_name="fileshare1")

get_service_properties

Gets the properties of a storage account's File Share service, including Azure Storage Analytics.

async get_service_properties(**kwargs: Any) -> Dict[str, Any]

Parameters

timeout
int

The timeout parameter is expressed in seconds.

Returns

A dictionary containing file service properties such as analytics logging, hour/minute metrics, cors rules, etc.

Return type

<xref:Dict>[str, <xref:Any>]

Examples

Get file share service properties.


   properties = await file_service.get_service_properties()

get_share_client

Get a client to interact with the specified share. The share need not already exist.

get_share_client(share: Union[ShareProperties, str], snapshot: Optional[Union[Dict[str, Any], str]] = None) -> ShareClient

Parameters

share
str or ShareProperties
Required

The share. This can either be the name of the share, or an instance of ShareProperties.

snapshot
str
default value: None

An optional share snapshot on which to operate. This can be the snapshot ID string or the response returned from <xref:azure.storage.fileshare.aio.create_snapshot>.

Returns

A ShareClient.

Return type

ShareClient

Examples

Gets the share client.


   from azure.storage.fileshare.aio import ShareServiceClient
   file_service = ShareServiceClient.from_connection_string(self.connection_string)

   # Get a share client to interact with a specific share
   share = file_service.get_share_client("fileshare2")

list_shares

Returns auto-paging iterable of dict-like ShareProperties under the specified account. The generator will lazily follow the continuation tokens returned by the service and stop when all shares have been returned.

list_shares(name_starts_with: Optional[str] = None, include_metadata: Optional[bool] = False, include_snapshots: Optional[bool] = False, **kwargs: Any) -> azure.core.async_paging.AsyncItemPaged

Parameters

name_starts_with
str
Required

Filters the results to return only shares whose names begin with the specified name_starts_with.

include_metadata
bool
Required

Specifies that share metadata be returned in the response.

include_snapshots
bool
Required

Specifies that share snapshot be returned in the response.

include_deleted
bool

Specifies that deleted shares be returned in the response. This is only for share soft delete enabled account.

timeout
int

The timeout parameter is expressed in seconds.

Returns

An iterable (auto-paging) of ShareProperties.

Return type

AsyncItemPaged[ShareProperties]

Examples

List shares in the file share service.


   # List the shares in the file service
   my_shares = []
   async for s in file_service.list_shares():
       my_shares.append(s)

   # Print the shares
   for share in my_shares:
       print(share)

set_service_properties

Sets the properties of a storage account's File Share service, including Azure Storage Analytics. If an element (e.g. hour_metrics) is left as None, the existing settings on the service for that functionality are preserved.

async set_service_properties(hour_metrics: Optional[Metrics] = None, minute_metrics: Optional[Metrics] = None, cors: Optional[List[CorsRule]] = None, protocol: Optional[ShareProtocolSettings], = None, **kwargs) -> None

Parameters

hour_metrics
Metrics
Required

The hour metrics settings provide a summary of request statistics grouped by API in hourly aggregates for files.

minute_metrics
Metrics
Required

The minute metrics settings provide request statistics for each minute for files.

cors
list(CorsRule)
Required

You can include up to five CorsRule elements in the list. If an empty list is specified, all CORS rules will be deleted, and CORS will be disabled for the service.

protocol_settings
Required

Sets protocol settings

timeout
int

The timeout parameter is expressed in seconds.

Return type

None

Examples

Sets file share service properties.


   # Create service properties
   from azure.storage.fileshare import Metrics, CorsRule, RetentionPolicy

   # Create metrics for requests statistics
   hour_metrics = Metrics(enabled=True, include_apis=True, retention_policy=RetentionPolicy(enabled=True, days=5))
   minute_metrics = Metrics(enabled=True, include_apis=True,
                            retention_policy=RetentionPolicy(enabled=True, days=5))

   # Create CORS rules
   cors_rule1 = CorsRule(['www.xyz.com'], ['GET'])
   allowed_origins = ['www.xyz.com', "www.ab.com", "www.bc.com"]
   allowed_methods = ['GET', 'PUT']
   max_age_in_seconds = 500
   exposed_headers = ["x-ms-meta-data*", "x-ms-meta-source*", "x-ms-meta-abc", "x-ms-meta-bcd"]
   allowed_headers = ["x-ms-meta-data*", "x-ms-meta-target*", "x-ms-meta-xyz", "x-ms-meta-foo"]
   cors_rule2 = CorsRule(
       allowed_origins,
       allowed_methods,
       max_age_in_seconds=max_age_in_seconds,
       exposed_headers=exposed_headers,
       allowed_headers=allowed_headers)

   cors = [cors_rule1, cors_rule2]

   async with file_service:
       # Set the service properties
       await file_service.set_service_properties(hour_metrics, minute_metrics, cors)

undelete_share

Restores soft-deleted share.

Operation will only be successful if used within the specified number of days set in the delete retention policy.

New in version 12.2.0: This operation was introduced in API version '2019-12-12'.

async undelete_share(deleted_share_name: str, deleted_share_version: str, **kwargs: Any) -> azure.storage.fileshare.aio._share_client_async.ShareClient

Parameters

deleted_share_name
str
Required

Specifies the name of the deleted share to restore.

deleted_share_version
str
Required

Specifies the version of the deleted share to restore.

timeout
int

The timeout parameter is expressed in seconds.

Return type

ShareClient