[Fileshare] Added support for set share properties including access t…

…ier (Azure#14355)

* added access tiers

* fixed async sample

* removed comments

* added sync test

* added all tests

* docstrings

* reset checks

* pylint

* changed method to set share properties

* forgot to comment out

* removed ShareSetPropertiesOptions

sdk/storage/azure-storage-file-share/azure/storage/fileshare/__init__.py

@@ -34,7 +34,8 @@
     ContentSettings,
     NTFSAttributes)
 from ._generated.models import (
-    HandleItem
+    HandleItem,
+    ShareAccessTier
 )
 
 __version__ = VERSION
@@ -56,6 +57,7 @@
     'RetentionPolicy',
     'CorsRule',
     'ShareSmbSettings',
+    'ShareAccessTier',
     'SmbMultichannel',
     'ShareProtocolSettings',
     'AccessPolicy',

sdk/storage/azure-storage-file-share/azure/storage/fileshare/_models.py

@@ -308,6 +308,8 @@ class ShareProperties(DictMixin):
         conditionally.
     :ivar int quota:
         The allocated quota.
+    :ivar str access_tier:
+        The share's access tier.
     :ivar dict metadata: A dict with name_value pairs to associate with the
         share as metadata.
     :ivar str snapshot:
@@ -331,6 +333,7 @@ def __init__(self, **kwargs):
         self.last_modified = kwargs.get('Last-Modified')
         self.etag = kwargs.get('ETag')
         self.quota = kwargs.get('x-ms-share-quota')
+        self.access_tier = kwargs.get('x-ms-access-tier')
         self.next_allowed_quota_downgrade_time = kwargs.get('x-ms-share-next-allowed-quota-downgrade-time')
         self.metadata = kwargs.get('metadata')
         self.snapshot = None
@@ -350,6 +353,7 @@ def _from_generated(cls, generated):
         props.last_modified = generated.properties.last_modified
         props.etag = generated.properties.etag
         props.quota = generated.properties.quota
+        props.access_tier = generated.properties.access_tier
         props.next_allowed_quota_downgrade_time = generated.properties.next_allowed_quota_downgrade_time
         props.metadata = generated.metadata
         props.snapshot = generated.snapshot

sdk/storage/azure-storage-file-share/azure/storage/fileshare/_share_client.py

@@ -305,6 +305,13 @@ def create_share(self, **kwargs):
             Name-value pairs associated with the share as metadata.
         :keyword int quota:
             The quota to be allotted.
+        :keyword access_tier:
+            Specifies the access tier of the share.
+            Possible values: 'TransactionOptimized', 'Hot', 'Cool'
+        :paramtype access_tier: str or ~azure.storage.fileshare.models.ShareAccessTier
+
+            .. versionadded:: 12.6.0
+
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :returns: Share-updated property dict (Etag and last modified).
@@ -321,6 +328,7 @@ def create_share(self, **kwargs):
         """
         metadata = kwargs.pop('metadata', None)
         quota = kwargs.pop('quota', None)
+        access_tier = kwargs.pop('access_tier', None)
         timeout = kwargs.pop('timeout', None)
         headers = kwargs.pop('headers', {})
         headers.update(add_metadata_headers(metadata)) # type: ignore
@@ -330,6 +338,7 @@ def create_share(self, **kwargs):
                 timeout=timeout,
                 metadata=metadata,
                 quota=quota,
+                access_tier=access_tier,
                 cls=return_response_headers,
                 headers=headers,
                 **kwargs)
@@ -504,6 +513,55 @@ def set_share_quota(self, quota, **kwargs):
             return self._client.share.set_properties( # type: ignore
                 timeout=timeout,
                 quota=quota,
+                access_tier=None,
+                lease_access_conditions=access_conditions,
+                cls=return_response_headers,
+                **kwargs)
+        except StorageErrorException as error:
+            process_storage_error(error)
+
+    @distributed_trace
+    def set_share_properties(self, **kwargs):
+        # type: (Any) ->  Dict[str, Any]
+        """Sets the share properties.
+
+        .. versionadded:: 12.6.0
+
+        :keyword access_tier:
+            Specifies the access tier of the share.
+            Possible values: 'TransactionOptimized', 'Hot', and 'Cool'
+        :paramtype access_tier: str or ~azure.storage.fileshare.models.ShareAccessTier
+        :keyword int quota:
+            Specifies the maximum size of the share, in gigabytes.
+            Must be greater than 0, and less than or equal to 5TB.
+        :keyword int timeout:
+            The timeout parameter is expressed in seconds.
+        :keyword lease:
+            Required if the share has an active lease. Value can be a ShareLeaseClient object
+            or the lease ID as a string.
+        :returns: Share-updated property dict (Etag and last modified).
+        :rtype: dict(str, Any)
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/file_samples_share.py
+                :start-after: [START set_share_properties]
+                :end-before: [END set_share_properties]
+                :language: python
+                :dedent: 12
+                :caption: Sets the share properties.
+        """
+        access_conditions = get_access_conditions(kwargs.pop('lease', None))
+        timeout = kwargs.pop('timeout', None)
+        access_tier = kwargs.pop('access_tier', None)
+        quota = kwargs.pop('quota', None)
+        if all(parameter is None for parameter in [access_tier, quota]):
+            raise ValueError("set_share_properties should be called with at least one parameter.")
+        try:
+            return self._client.share.set_properties( # type: ignore
+                timeout=timeout,
+                quota=quota,
+                access_tier=access_tier,
                 lease_access_conditions=access_conditions,
                 cls=return_response_headers,
                 **kwargs)

sdk/storage/azure-storage-file-share/azure/storage/fileshare/aio/_share_client_async.py

@@ -176,6 +176,13 @@ async def create_share(self, **kwargs):
             Name-value pairs associated with the share as metadata.
         :keyword int quota:
             The quota to be allotted.
+        :keyword access_tier:
+            Specifies the access tier of the share.
+            Possible values: 'TransactionOptimized', 'Hot', 'Cool'
+        :paramtype access_tier: str or ~azure.storage.fileshare.models.ShareAccessTier
+
+            .. versionadded:: 12.6.0
+
         :keyword int timeout:
             The timeout parameter is expressed in seconds.
         :returns: Share-updated property dict (Etag and last modified).
@@ -192,6 +199,7 @@ async def create_share(self, **kwargs):
         """
         metadata = kwargs.pop('metadata', None)
         quota = kwargs.pop('quota', None)
+        access_tier = kwargs.pop('access_tier', None)
         timeout = kwargs.pop('timeout', None)
         headers = kwargs.pop('headers', {})
         headers.update(add_metadata_headers(metadata)) # type: ignore
@@ -201,6 +209,7 @@ async def create_share(self, **kwargs):
                 timeout=timeout,
                 metadata=metadata,
                 quota=quota,
+                access_tier=access_tier,
                 cls=return_response_headers,
                 headers=headers,
                 **kwargs)
@@ -374,12 +383,60 @@ async def set_share_quota(self, quota, **kwargs):
             return await self._client.share.set_properties( # type: ignore
                 timeout=timeout,
                 quota=quota,
+                access_tier=None,
                 cls=return_response_headers,
                 lease_access_conditions=access_conditions,
                 **kwargs)
         except StorageErrorException as error:
             process_storage_error(error)
 
+    async def set_share_properties(self, **kwargs):
+        # type: (Any) ->  Dict[str, Any]
+        """Sets the share properties.
+
+        .. versionadded:: 12.6.0
+
+        :keyword access_tier:
+            Specifies the access tier of the share.
+            Possible values: 'TransactionOptimized', 'Hot', and 'Cool'
+        :paramtype access_tier: str or ~azure.storage.fileshare.models.ShareAccessTier
+        :keyword int quota:
+            Specifies the maximum size of the share, in gigabytes.
+            Must be greater than 0, and less than or equal to 5TB.
+        :keyword int timeout:
+            The timeout parameter is expressed in seconds.
+        :keyword lease:
+            Required if the share has an active lease. Value can be a ShareLeaseClient object
+            or the lease ID as a string.
+        :returns: Share-updated property dict (Etag and last modified).
+        :rtype: dict(str, Any)
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/file_samples_share_async.py
+                :start-after: [START set_share_properties]
+                :end-before: [END set_share_properties]
+                :language: python
+                :dedent: 16
+                :caption: Sets the share properties.
+        """
+        access_conditions = get_access_conditions(kwargs.pop('lease', None))
+        timeout = kwargs.pop('timeout', None)
+        access_tier = kwargs.pop('access_tier', None)
+        quota = kwargs.pop('quota', None)
+        if all(parameter is None for parameter in [access_tier, quota]):
+            raise ValueError("set_share_properties should be called with at least one parameter.")
+        try:
+            return await self._client.share.set_properties( # type: ignore
+                timeout=timeout,
+                quota=quota,
+                access_tier=access_tier,
+                lease_access_conditions=access_conditions,
+                cls=return_response_headers,
+                **kwargs)
+        except StorageErrorException as error:
+            process_storage_error(error)
+
     @distributed_trace_async
     async def set_share_metadata(self, metadata, **kwargs):
         # type: (Dict[str, Any], Any) ->  Dict[str, Any]

sdk/storage/azure-storage-file-share/samples/file_samples_share.py

@@ -22,6 +22,7 @@
 """
 
 import os
+from azure.storage.fileshare import ShareAccessTier
 
 SOURCE_FILE = './SampleSource.txt'
 DEST_FILE = './SampleDestination.txt'
@@ -37,7 +38,8 @@ def create_share_snapshot(self):
         share = ShareClient.from_connection_string(self.connection_string, "sharesamples1")
 
         # [START create_share]
-        share.create_share()
+        # Create share with Access Tier set to Hot
+        share.create_share(access_tier=ShareAccessTier("Hot"))
         # [END create_share]
         try:
             # [START create_share_snapshot]
@@ -75,10 +77,40 @@ def set_share_quota_and_metadata(self):
             # Delete the share
             share.delete_share()
 
+    def set_share_properties(self):
+        from azure.storage.fileshare import ShareClient
+        share1 = ShareClient.from_connection_string(self.connection_string, "sharesamples3a")
+        share2 = ShareClient.from_connection_string(self.connection_string, "sharesamples3b")
+
+        # Create the share
+        share1.create_share()
+        share2.create_share()
+
+        try:
+            # [START set_share_properties]
+            # Set the tier for the first share to Hot
+            share1.set_share_properties(access_tier="Hot")
+            # Set the quota for the first share to 3
+            share1.set_share_properties(quota=3)
+            # Set the tier for the second share to Cool and quota to 2
+            share2.set_share_properties(access_tier=ShareAccessTier("Cool"), quota=2)
+
+            # Get the shares' properties
+            print(share1.get_share_properties().access_tier)
+            print(share1.get_share_properties().quota)
+            print(share2.get_share_properties().access_tier)
+            print(share2.get_share_properties().quota)
+            # [END set_share_properties]
+
+        finally:
+            # Delete the shares
+            share1.delete_share()
+            share2.delete_share()
+
     def list_directories_and_files(self):
         # Instantiate the ShareClient from a connection string
         from azure.storage.fileshare import ShareClient
-        share = ShareClient.from_connection_string(self.connection_string, "sharesamples3")
+        share = ShareClient.from_connection_string(self.connection_string, "sharesamples4")
 
         # Create the share
         share.create_share()
@@ -103,7 +135,7 @@ def list_directories_and_files(self):
     def get_directory_or_file_client(self):
         # Instantiate the ShareClient from a connection string
         from azure.storage.fileshare import ShareClient
-        share = ShareClient.from_connection_string(self.connection_string, "sharesamples4")
+        share = ShareClient.from_connection_string(self.connection_string, "sharesamples5")
 
         # Get the directory client to interact with a specific directory
         my_dir = share.get_directory_client("dir1")
@@ -131,6 +163,7 @@ def acquire_share_lease(self):
     sample = ShareSamples()
     sample.create_share_snapshot()
     sample.set_share_quota_and_metadata()
+    sample.set_share_properties()
     sample.list_directories_and_files()
     sample.get_directory_or_file_client()
     sample.acquire_share_lease()

sdk/storage/azure-storage-file-share/samples/file_samples_share_async.py

@@ -23,6 +23,7 @@
 
 import os
 import asyncio
+from azure.storage.fileshare import ShareAccessTier
 
 SOURCE_FILE = './SampleSource.txt'
 DEST_FILE = './SampleDestination.txt'
@@ -39,7 +40,8 @@ async def create_share_snapshot_async(self):
 
         async with share:
             # [START create_share]
-            await share.create_share()
+            # Create share with Access Tier set to Hot
+            await share.create_share(access_tier=ShareAccessTier("Hot"))
             # [END create_share]
             try:
                 # [START create_share_snapshot]
@@ -78,10 +80,43 @@ async def set_share_quota_and_metadata_async(self):
                 # Delete the share
                 await share.delete_share()
 
+    async def set_share_properties(self):
+        from azure.storage.fileshare.aio import ShareClient
+        share1 = ShareClient.from_connection_string(self.connection_string, "sharesamples3a")
+        share2 = ShareClient.from_connection_string(self.connection_string, "sharesamples3b")
+
+        # Create the share
+        async with share1 and share2:
+            await share1.create_share()
+            await share2.create_share()
+
+            try:
+                # [START set_share_properties]
+                # Set the tier for the first share to Hot
+                await share1.set_share_properties(access_tier="Hot")
+                # Set the quota for the first share to 3
+                await share1.set_share_properties(quota=3)
+                # Set the tier for the second share to Cool and quota to 2
+                await share2.set_share_properties(access_tier=ShareAccessTier("Cool"), quota=2)
+
+                # Get the shares' properties
+                props1 = await share1.get_share_properties()
+                props2 = await share2.get_share_properties()
+                print(props1.access_tier)
+                print(props1.quota)
+                print(props2.access_tier)
+                print(props2.quota)
+                # [END set_share_properties]
+
+            finally:
+                # Delete the shares
+                await share1.delete_share()
+                await share2.delete_share()
+
     async def list_directories_and_files_async(self):
         # Instantiate the ShareClient from a connection string
         from azure.storage.fileshare.aio import ShareClient
-        share = ShareClient.from_connection_string(self.connection_string, "sharesamples3")
+        share = ShareClient.from_connection_string(self.connection_string, "sharesamples4")
 
         # Create the share
         async with share:
@@ -109,7 +144,7 @@ async def list_directories_and_files_async(self):
     async def get_directory_or_file_client_async(self):
         # Instantiate the ShareClient from a connection string
         from azure.storage.fileshare.aio import ShareClient
-        share = ShareClient.from_connection_string(self.connection_string, "sharesamples4")
+        share = ShareClient.from_connection_string(self.connection_string, "sharesamples5")
 
         # Get the directory client to interact with a specific directory
         my_dir = share.get_directory_client("dir1")
@@ -122,6 +157,7 @@ async def main():
     sample = ShareSamplesAsync()
     await sample.create_share_snapshot_async()
     await sample.set_share_quota_and_metadata_async()
+    await sample.set_share_properties()
     await sample.list_directories_and_files_async()
     await sample.get_directory_or_file_client_async()