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.

For more optional configuration, please click here.

Inheritance: azure.storage.fileshare._shared.base_client.StorageAccountHostsMixin

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.

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 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.
from_connection_string	Create ShareServiceClient from a Connection String.
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'.

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: str, **kwargs) -> azure.storage.fileshare._share_client.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.


   file_service.create_share(share_name="fileshare1")

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

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.


   file_service.delete_share(share_name="fileshare1")

from_connection_string

Create ShareServiceClient from a Connection String.

from_connection_string(conn_str: str, credential: Optional[Any] = None, **kwargs: Any) -> azure.storage.fileshare._share_service_client.ShareServiceClient

Parameters

conn_str: str

Required

A connection string to an Azure Storage account.

credential

Required

credential

default value: None

Returns

A File Share service client.

Return type

ShareServiceClient

Examples

Create the share service client with connection string.


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

get_service_properties

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

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 = file_service.get_service_properties()

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

Returns

A ShareClient.

Return type

ShareClient

Examples

Gets the share client.


   from azure.storage.fileshare 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) -> ItemPaged[ShareProperties]

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

ItemPaged[ShareProperties]

Examples

List shares in the file share service.


   # List the shares in the file service
   my_shares = list(file_service.list_shares())

   # 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: 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: ShareProtocolSettings

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]

   # Set the service properties
   file_service.set_service_properties(hour_metrics, minute_metrics, cors)

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

undelete_share(deleted_share_name: str, deleted_share_version: str, **kwargs: Any) -> azure.storage.fileshare._share_client.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

ShareServiceClient Class

Constructor

Parameters

Examples

Methods

create_share

Parameters

Return type

Examples

delete_share

Parameters

Return type

Examples

from_connection_string

Parameters

Returns

Return type

Examples

get_service_properties

Parameters

Returns

Return type

Examples

get_share_client

Parameters

Returns

Return type

Examples

list_shares

Parameters

Returns

Return type

Examples

set_service_properties

Parameters

Return type

Examples

undelete_share

Parameters

Return type

Feedback