ShareServiceClient class

Definition

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(share, snapshot=None) function.

ShareServiceClient(account_url, credential=None, **kwargs)
Inheritance
builtins.object
azure.storage.fileshare._shared.base_client_async.AsyncStorageAccountHostsMixin
ShareServiceClient
azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin
azure.storage.fileshare._share_service_client.ShareServiceClient
ShareServiceClient

Parameters

account_url
str

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

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 or an account shared access key.

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.

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.

create_share(share_name, **kwargs)

Parameters

share_name
str
Required

The name of the share to create.

Return type

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.

delete_share(share_name, delete_snapshots=False, **kwargs)

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.

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.

get_service_properties(**kwargs)

Returns

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

Return type

Dict[str, 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, snapshot=None)

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

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=None, include_metadata=False, include_snapshots=False, **kwargs)

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.

Returns

An iterable (auto-paging) of ShareProperties.

Return type

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.

set_service_properties(hour_metrics=None, minute_metrics=None, cors=None, **kwargs)

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.

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)