Package com.azure.storage.file.share

Class ShareServiceAsyncClient

  • public final class ShareServiceAsyncClient
extends Object
    This class provides a azureFileStorageClient that contains all the operations for interacting with a file account in Azure Storage. Operations allowed by the azureFileStorageClient are creating, listing, and deleting shares and retrieving and updating properties of the account.

    Instantiating an Asynchronous File Service Client

     ShareAsyncClient client = new ShareClientBuilder()
     .connectionString("${connectionString}")
     .endpoint("${endpoint}")
     .buildAsyncClient();

    View this for additional ways to construct the azureFileStorageClient.

    See Also:
    ShareServiceClientBuilder, ShareServiceClient, StorageSharedKeyCredential

    • Method Detail

      • getFileServiceUrl

        public String getFileServiceUrl()
        Get the url of the storage file service client.
        Returns:
        the url of the Storage File service.

      • getServiceVersion

        public ShareServiceVersion getServiceVersion()
        Gets the service version the client is using.
        Returns:
        the service version the client is using.

      • getShareAsyncClient

        public ShareAsyncClient getShareAsyncClient​(String shareName)
        Constructs a ShareAsyncClient that interacts with the specified share.

        If the share doesn't exist in the storage account create in the azureFileStorageClient will need to be called before interaction with the share can happen.

        Parameters:
        shareName - Name of the share
        Returns:
        a ShareAsyncClient that interacts with the specified share

      • getShareAsyncClient

        public ShareAsyncClient getShareAsyncClient​(String shareName,
                                            String snapshot)
        Constructs a ShareAsyncClient that interacts with the specified share.

        If the share doesn't exist in the storage account create in the azureFileStorageClient will need to be called before interaction with the share can happen.

        Parameters:
        shareName - Name of the share
        snapshot - Snapshot ID of the share
        Returns:
        a ShareAsyncClient that interacts with the specified share

      • listShares

        public com.azure.core.http.rest.PagedFlux<ShareItem> listShares()
        Lists all shares in the storage account without their metadata or snapshots.

        Code Samples

        List all shares in the account

         fileServiceAsyncClient.listShares().subscribe(
     shareItem -> System.out.printf("Share %s exists in the account", shareItem.getName()),
     error -> System.err.print(error.toString()),
     () -> System.out.println("Complete listing the shares!")
 );

        For more information, see the Azure Docs.

        Returns:
        Shares in the storage account without their metadata or snapshots

      • listShares

        public com.azure.core.http.rest.PagedFlux<ShareItem> listShares​(ListSharesOptions options)
        Lists the shares in the Storage account that pass the options filter.

        Set starts with name filter using prefix to filter shares that are listed.

        Pass true to includeMetadata to have metadata returned for the shares.

        Pass true to includeSnapshots to have snapshots of the shares listed.

        Code Samples

        List all shares that begin with "azure"

         fileServiceAsyncClient.listShares(new ListSharesOptions().setPrefix("azure")).subscribe(
     shareItem -> System.out.printf("Share %s exists in the account", shareItem.getName()),
     error -> System.err.print(error.toString()),
     () -> System.out.println("Complete listing the shares!")
 );

        List all shares including their snapshots and metadata

         fileServiceAsyncClient.listShares(new ListSharesOptions().setIncludeMetadata(true).setIncludeSnapshots(true))
     .subscribe(
         shareItem -> System.out.printf("Share %s exists in the account", shareItem.getName()),
         error -> System.err.print(error.toString()),
         () -> System.out.println("Complete listing the shares!")
     );

        For more information, see the Azure Docs.

        Parameters:
        options - Options for listing shares
        Returns:
        Shares in the storage account that satisfy the filter requirements

      • getProperties

        public Mono<ShareServiceProperties> getProperties()
        Retrieves the properties of the storage account's File service. The properties range from storage analytics and metrics to CORS (Cross-Origin Resource Sharing).

        Code Samples

        Retrieve File service properties

         fileServiceAsyncClient.getProperties()
     .subscribe(properties -> {
         System.out.printf("Hour metrics enabled: %b, Minute metrics enabled: %b",
             properties.getHourMetrics().isEnabled(), properties.getMinuteMetrics().isEnabled());
     });

        For more information, see the Azure Docs.

        Returns:
        Storage account File service properties

      • getPropertiesWithResponse

        public Mono<com.azure.core.http.rest.Response<ShareServiceProperties>> getPropertiesWithResponse()
        Retrieves the properties of the storage account's File service. The properties range from storage analytics and metrics to CORS (Cross-Origin Resource Sharing).

        Code Samples

        Retrieve File service properties

         fileServiceAsyncClient.getPropertiesWithResponse()
     .subscribe(properties -> System.out.printf("Hour metrics enabled: %b, Minute metrics enabled: %b",
         properties.getValue().getHourMetrics().isEnabled(),
         properties.getValue().getMinuteMetrics().isEnabled()));

        For more information, see the Azure Docs.

        Returns:
        A response containing the Storage account File service properties

      • setProperties

        public Mono<Void> setProperties​(ShareServiceProperties properties)
        Sets the properties for the storage account's File service. The properties range from storage analytics and metric to CORS (Cross-Origin Resource Sharing). To maintain the CORS in the Queue service pass a null value for CORS. To disable all CORS in the Queue service pass an empty list for CORS.

        Code Sample

        Enable Minute and Hour Metrics

         fileServiceAsyncClient.getProperties().subscribe(properties -> {
     properties.getMinuteMetrics().setEnabled(true);
     properties.getHourMetrics().setEnabled(true);

     fileServiceAsyncClient.setProperties(properties)
         .subscribe(r -> System.out.println("Setting File service properties completed."));
 });

        For more information, see the Azure Docs.

        Parameters:
        properties - Storage account File service properties
        Returns:
        An empty response
        Throws:
        ShareStorageException - When one of the following is true

      • setPropertiesWithResponse

        public Mono<com.azure.core.http.rest.Response<Void>> setPropertiesWithResponse​(ShareServiceProperties properties)
        Sets the properties for the storage account's File service. The properties range from storage analytics and metric to CORS (Cross-Origin Resource Sharing). To maintain the CORS in the Queue service pass a null value for CORS. To disable all CORS in the Queue service pass an empty list for CORS.

        Code Sample

        Clear CORS in the File service

         fileServiceAsyncClient.getProperties().subscribe(properties -> {
     properties.setCors(Collections.emptyList());

     fileServiceAsyncClient.setPropertiesWithResponse(properties).subscribe(response ->
         System.out.printf("Setting File service properties completed with status code %d",
             response.getStatusCode()));
 });

        Enable Minute and Hour Metrics

         fileServiceAsyncClient.getPropertiesWithResponse().subscribe(response -> {
     ShareServiceProperties properties = response.getValue();
     properties.getMinuteMetrics().setEnabled(true);
     properties.getHourMetrics().setEnabled(true);

     fileServiceAsyncClient.setPropertiesWithResponse(properties).subscribe(r ->
         System.out.printf("Setting File service properties completed with status code %d", r.getStatusCode()));
 });

        For more information, see the Azure Docs.

        Parameters:
        properties - Storage account File service properties
        Returns:
        A response that only contains headers and response status code
        Throws:
        ShareStorageException - When one of the following is true

      • createShare

        public Mono<ShareAsyncClient> createShare​(String shareName)
        Creates a share in the storage account with the specified name and returns a ShareAsyncClient to interact with it.

        Code Samples

        Create the share "test"

         fileServiceAsyncClient.createShare("myshare").subscribe(
     response -> { },
     error -> System.err.print(error.toString()),
     () -> System.out.println("Complete creating the share!")
 );

        For more information, see the Azure Docs.

        Parameters:
        shareName - Name of the share
        Returns:
        The ShareAsyncClient
        Throws:
        ShareStorageException - If a share with the same name already exists

      • createShareWithResponse

        public Mono<com.azure.core.http.rest.Response<ShareAsyncClient>> createShareWithResponse​(String shareName,
                                                                                         Map<String,​String> metadata,
                                                                                         Integer quotaInGB)
        Creates a share in the storage account with the specified name, metadata, and quota and returns a ShareAsyncClient to interact with it.

        Code Samples

        Create the share "test" with metadata "share:metadata"

         fileServiceAsyncClient.createShareWithResponse("test", Collections.singletonMap("share", "metadata"), null)
     .subscribe(
         response -> System.out.printf("Creating the share completed with status code %d", response.getStatusCode()),
         error -> System.err.print(error.toString()),
         () -> System.out.println("Complete creating the share!")
     );

        Create the share "test" with a quota of 10 GB

         fileServiceAsyncClient.createShareWithResponse("test", null, 10)
     .subscribe(
         response -> System.out.printf("Creating the share completed with status code %d",
             response.getStatusCode()),
         error -> System.err.print(error.toString()),
         () -> System.out.println("Complete creating the share!")
     );

        For more information, see the Azure Docs.

        Parameters:
        shareName - Name of the share
        metadata - Optional metadata to associate with the share
        quotaInGB - Optional maximum size the share is allowed to grow to in GB. This must be greater than 0 and less than or equal to 5120. The default value is 5120.
        Returns:
        A response containing the ShareAsyncClient and the status of creating the share.
        Throws:
        ShareStorageException - If a share with the same name already exists or quotaInGB is outside the allowed range.

      • createShareWithResponse

        public Mono<com.azure.core.http.rest.Response<ShareAsyncClient>> createShareWithResponse​(String shareName,
                                                                                         ShareCreateOptions options)
        Creates a share in the storage account with the specified name, and options and returns a ShareAsyncClient to interact with it.

        Code Samples

         fileServiceAsyncClient.createShareWithResponse("test", new ShareCreateOptions()
     .setMetadata(Collections.singletonMap("share", "metadata")).setQuotaInGb(1)
     .setAccessTier(ShareAccessTier.HOT)).subscribe(
         response -> System.out.printf("Creating the share completed with status code %d",
             response.getStatusCode()),
         error -> System.err.print(error.toString()),
         () -> System.out.println("Complete creating the share!")
 );

        For more information, see the Azure Docs.

        Parameters:
        shareName - Name of the share
        options - ShareCreateOptions
        Returns:
        A response containing the ShareAsyncClient and the status of creating the share.
        Throws:
        ShareStorageException - If a share with the same name already exists or quotaInGB is outside the allowed range.

      • deleteShare

        public Mono<Void> deleteShare​(String shareName)
        Deletes the share in the storage account with the given name.

        Code Samples

        Delete the share "test"

         fileServiceAsyncClient.deleteShare("test").doOnSuccess(
     response -> System.out.println("Deleting the share completed.")
 );

        For more information, see the Azure Docs.

        Parameters:
        shareName - Name of the share
        Returns:
        An empty response
        Throws:
        ShareStorageException - If the share doesn't exist

      • deleteShareWithResponse

        public Mono<com.azure.core.http.rest.Response<Void>> deleteShareWithResponse​(String shareName,
                                                                             String snapshot)
        Deletes the specific snapshot of the share in the storage account with the given name. Snapshot are identified by the time they were created.

        Code Samples

        Delete the snapshot of share "test" that was created at current time.

         OffsetDateTime midnight = OffsetDateTime.of(LocalDateTime.now(), ZoneOffset.UTC);
 fileServiceAsyncClient.deleteShareWithResponse("test", midnight.toString())
     .subscribe(response -> System.out.printf("Deleting the snapshot completed with status code %d",
         response.getStatusCode()));

        For more information, see the Azure Docs.

        Parameters:
        shareName - Name of the share
        snapshot - Identifier of the snapshot
        Returns:
        A response that only contains headers and response status code
        Throws:
        ShareStorageException - If the share doesn't exist or the snapshot doesn't exist

      • getAccountName

        public String getAccountName()
        Get associated account name.
        Returns:
        account name associated with this storage resource.

      • getHttpPipeline

        public com.azure.core.http.HttpPipeline getHttpPipeline()
        Gets the HttpPipeline powering this client.
        Returns:
        The pipeline.

      • generateAccountSas

        public String generateAccountSas​(AccountSasSignatureValues accountSasSignatureValues)
        Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.

        Note : The client must be authenticated via StorageSharedKeyCredential

        See AccountSasSignatureValues for more information on how to construct an account SAS.

        The snippet below generates a SAS that lasts for two days and gives the user read and list access to blob containers and file shares.

         AccountSasPermission permissions = new AccountSasPermission()
     .setListPermission(true)
     .setReadPermission(true);
 AccountSasResourceType resourceTypes = new AccountSasResourceType().setContainer(true);
 AccountSasService services = new AccountSasService().setBlobAccess(true).setFileAccess(true);
 OffsetDateTime expiryTime = OffsetDateTime.now().plus(Duration.ofDays(2));

 AccountSasSignatureValues sasValues =
     new AccountSasSignatureValues(expiryTime, permissions, services, resourceTypes);

 // Client must be authenticated via StorageSharedKeyCredential
 String sas = fileServiceAsyncClient.generateAccountSas(sasValues);
        Parameters:
        accountSasSignatureValues - AccountSasSignatureValues
        Returns:
        A String representing the SAS query parameters.

      • generateAccountSas

        public String generateAccountSas​(AccountSasSignatureValues accountSasSignatureValues,
                                 com.azure.core.util.Context context)
        Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.

        Note : The client must be authenticated via StorageSharedKeyCredential

        See AccountSasSignatureValues for more information on how to construct an account SAS.

        The snippet below generates a SAS that lasts for two days and gives the user read and list access to blob containers and file shares.

         AccountSasPermission permissions = new AccountSasPermission()
     .setListPermission(true)
     .setReadPermission(true);
 AccountSasResourceType resourceTypes = new AccountSasResourceType().setContainer(true);
 AccountSasService services = new AccountSasService().setBlobAccess(true).setFileAccess(true);
 OffsetDateTime expiryTime = OffsetDateTime.now().plus(Duration.ofDays(2));

 AccountSasSignatureValues sasValues =
     new AccountSasSignatureValues(expiryTime, permissions, services, resourceTypes);

 // Client must be authenticated via StorageSharedKeyCredential
 String sas = fileServiceAsyncClient.generateAccountSas(sasValues, new Context("key", "value"));
        Parameters:
        accountSasSignatureValues - AccountSasSignatureValues
        context - Additional context that is passed through the code when generating a SAS.
        Returns:
        A String representing the SAS query parameters.

      • undeleteShare

        public Mono<ShareAsyncClient> undeleteShare​(String deletedShareName,
                                            String deletedShareVersion)
        Restores a previously deleted share.

        If the share associated with provided deletedShareName already exists, this call will result in a 409 (conflict).

        This API is only functional if Share Soft Delete is enabled for the storage account associated with the share. For more information, see the Azure Docs.

        Code Samples

         ListSharesOptions listSharesOptions = new ListSharesOptions();
 listSharesOptions.setIncludeDeleted(true);
 fileServiceAsyncClient.listShares(listSharesOptions).flatMap(
     deletedShare -> {
         Mono<ShareAsyncClient> shareAsyncClient = fileServiceAsyncClient.undeleteShare(
             deletedShare.getName(), deletedShare.getVersion());
         return shareAsyncClient;
     }
 ).blockFirst();

        For more information, see the Azure Docs.

        Parameters:
        deletedShareName - The name of the previously deleted share.
        deletedShareVersion - The version of the previously deleted share.
        Returns:
        A Mono containing a ShareAsyncClient used to interact with the restored share.

      • undeleteShareWithResponse

        public Mono<com.azure.core.http.rest.Response<ShareAsyncClient>> undeleteShareWithResponse​(String deletedShareName,
                                                                                           String deletedShareVersion)
        Restores a previously deleted share.

        If the share associated with provided deletedShareName already exists, this call will result in a 409 (conflict).

        This API is only functional if Share Soft Delete is enabled for the storage account associated with the share. For more information, see the Azure Docs.

        Code Samples

         ListSharesOptions listSharesOptions = new ListSharesOptions();
 listSharesOptions.setIncludeDeleted(true);
 fileServiceAsyncClient.listShares(listSharesOptions).flatMap(
     deletedShare -> {
         Mono<ShareAsyncClient> shareAsyncClient = fileServiceAsyncClient.undeleteShareWithResponse(
             deletedShare.getName(), deletedShare.getVersion()).map(Response::getValue);
         return shareAsyncClient;
     }
 ).blockFirst();

        For more information, see the Azure Docs.

        Parameters:
        deletedShareName - The name of the previously deleted share.
        deletedShareVersion - The version of the previously deleted share.
        Returns:
        A Mono containing a Response whose value contains a ShareAsyncClient used to interact with the restored share.