Package com.azure.storage.file.share

Class ShareServiceClient

java.lang.Object
com.azure.storage.file.share.ShareServiceClient
public final class ShareServiceClient extends Object
This class provides a shareServiceAsyncClient that contains all the operations for interacting with a file account in Azure Storage. Operations allowed by the shareServiceAsyncClient are creating, listing, and deleting shares and retrieving and updating properties of the account.

Instantiating a Synchronous File Service Client

 ShareServiceClient client = new ShareServiceClientBuilder()
     .connectionString("${connectionString}")
     .endpoint("${endpoint}")
     .buildClient();

View this for additional ways to construct the shareServiceAsyncClient.

See Also:

  • Method Details

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

    • getShareClient

      public ShareClient getShareClient(String shareName)
      Constructs a ShareClient that interacts with the specified share.

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

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

    • listShares

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

      Code Samples

      List all shares in the account

       fileServiceClient.listShares().forEach(
     shareItem -> System.out.printf("Share %s exists in the account", shareItem.getName())
 );

      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.PagedIterable<ShareItem> listShares(ListSharesOptions options, Duration timeout, com.azure.core.util.Context context)
      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"

       fileServiceClient.listShares(new ListSharesOptions().setPrefix("azure"), Duration.ofSeconds(1),
     new Context(key1, value1)).forEach(
         shareItem -> System.out.printf("Share %s exists in the account", shareItem.getName())
 );

      List all shares including their snapshots and metadata

       fileServiceClient.listShares(new ListSharesOptions().setIncludeMetadata(true)
     .setIncludeSnapshots(true), Duration.ofSeconds(1), new Context(key1, value1)).forEach(
         shareItem -> System.out.printf("Share %s exists in the account", shareItem.getName())
 );

      For more information, see the Azure Docs.

      Parameters:
      options - Options for listing shares. If iterating by page, the page size passed to byPage methods such as ContinuablePagedIterable.iterableByPage(int) will be preferred over the value set on these options.
      timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      Shares in the storage account that satisfy the filter requirements
      Throws:
      RuntimeException - if the operation doesn't complete before the timeout concludes.

    • getProperties

      public 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

       ShareServiceProperties properties = fileServiceClient.getProperties();
 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 com.azure.core.http.rest.Response<ShareServiceProperties> getPropertiesWithResponse(Duration timeout, com.azure.core.util.Context context)
      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

       ShareServiceProperties properties = fileServiceClient.getPropertiesWithResponse(
     Duration.ofSeconds(1), new Context(key1, value1)).getValue();
 System.out.printf("Hour metrics enabled: %b, Minute metrics enabled: %b", properties.getHourMetrics().isEnabled(),
     properties.getMinuteMetrics().isEnabled());

      For more information, see the Azure Docs.

      Parameters:
      timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A response containing the Storage account File service properties with headers and response status code
      Throws:
      RuntimeException - if the operation doesn't complete before the timeout concludes.

    • setProperties

      public 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

      Clear CORS in the File service

       ShareServiceProperties properties = fileServiceClient.getProperties();
 properties.setCors(Collections.emptyList());

 Response<Void> response = fileServiceClient.setPropertiesWithResponse(properties,
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Setting File service properties completed with status code %d", response.getStatusCode());

      Enable Minute and Hour Metrics

       ShareServiceProperties properties = fileServiceClient.getProperties();

 properties.getMinuteMetrics().setEnabled(true);
 properties.getHourMetrics().setEnabled(true);

 fileServiceClient.setProperties(properties);
 System.out.println("Setting File service properties completed.");

      For more information, see the Azure Docs.

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

    • setPropertiesWithResponse

      public com.azure.core.http.rest.Response<Void> setPropertiesWithResponse(ShareServiceProperties properties, Duration timeout, com.azure.core.util.Context context)
      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

       ShareServiceProperties properties = fileServiceClient.getProperties();
 properties.setCors(Collections.emptyList());

 Response<Void> response = fileServiceClient.setPropertiesWithResponse(properties,
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Setting File service properties completed with status code %d", response.getStatusCode());

      Enable Minute and Hour Metrics

       ShareServiceProperties properties = fileServiceClient.getPropertiesWithResponse(
     Duration.ofSeconds(1), new Context(key1, value1)).getValue();

 properties.getMinuteMetrics().setEnabled(true);
 properties.getHourMetrics().setEnabled(true);

 Response<Void> response = fileServiceClient.setPropertiesWithResponse(properties,
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Setting File service properties completed with status code %d", response.getStatusCode());

      For more information, see the Azure Docs.

      Parameters:
      properties - Storage account File service properties
      timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A response that only contains headers and response status code
      Throws:
      ShareStorageException - When one of the following is true
      RuntimeException - if the operation doesn't complete before the timeout concludes.

    • createShare

      public ShareClient createShare(String shareName)
      Creates a share in the storage account with the specified name and returns a ShareClient to interact with it.

      Code Samples

      Create the share with share name of "myshare"

       fileServiceClient.createShare("myshare");
 System.out.println("Creating the share completed.");

      For more information, see the Azure Docs.

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

    • createShareWithResponse

      public com.azure.core.http.rest.Response<ShareClient> createShareWithResponse(String shareName, Map<String,String> metadata, Integer quotaInGB, Duration timeout, com.azure.core.util.Context context)
      Creates a share in the storage account with the specified name and metadata and returns a ShareClient to interact with it.

      Code Samples

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

       Response<ShareClient> response = fileServiceClient.createShareWithResponse("test",
     Collections.singletonMap("share", "metadata"), null, Duration.ofSeconds(5),
     new Context(key1, value1));
 System.out.printf("Creating the share completed with status code %d", response.getStatusCode());

      For more information, see the Azure Docs.

      For more information on updated max file share size values, 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. The default value is 5120. Refer to the Azure Docs for updated values.
      timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A response containing the ShareClient 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.
      RuntimeException - if the operation doesn't complete before the timeout concludes.

    • createShareWithResponse

      public com.azure.core.http.rest.Response<ShareClient> createShareWithResponse(String shareName, ShareCreateOptions options, Duration timeout, com.azure.core.util.Context context)
      Creates a share in the storage account with the specified name and options and returns a ShareClient to interact with it.

      Code Samples

       Response<ShareClient> response = fileServiceClient.createShareWithResponse("test",
     new ShareCreateOptions().setMetadata(Collections.singletonMap("share", "metadata")).setQuotaInGb(1)
     .setAccessTier(ShareAccessTier.HOT), Duration.ofSeconds(5), new Context(key1, value1));
 System.out.printf("Creating the share completed with status code %d", response.getStatusCode());

      For more information, see the Azure Docs.

      Parameters:
      shareName - Name of the share
      options - ShareCreateOptions
      timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A response containing the ShareClient 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.
      RuntimeException - if the operation doesn't complete before the timeout concludes.

    • deleteShare

      public void deleteShare(String shareName)
      Deletes the share in the storage account with the given name

      Code Samples

      Delete the share "test"

       fileServiceClient.deleteShare("myshare");

      For more information, see the Azure Docs.

      Parameters:
      shareName - Name of the share
      Throws:
      ShareStorageException - If the share doesn't exist

    • deleteShareWithResponse

      public com.azure.core.http.rest.Response<Void> deleteShareWithResponse(String shareName, String snapshot, Duration timeout, com.azure.core.util.Context context)
      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);
 Response<Void> response = fileServiceClient.deleteShareWithResponse("test", midnight.toString(),
     Duration.ofSeconds(1), new Context(key1, value1));
 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
      timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
      context - Additional context that is passed through the Http pipeline during the service call.
      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
      RuntimeException - if the operation doesn't complete before the timeout concludes.

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

      Generating an account SAS

      The snippet below generates an AccountSasSignatureValues object that lasts for two days and gives the user read and list access to blob 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 = fileServiceClient.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 = fileServiceClient.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.

    • generateAccountSas

      public String generateAccountSas(AccountSasSignatureValues accountSasSignatureValues, Consumer<String> stringToSignHandler, 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.

      Parameters:
      accountSasSignatureValues - AccountSasSignatureValues
      stringToSignHandler - For debugging purposes only. Returns the string to sign that was used to generate the signature.
      context - Additional context that is passed through the code when generating a SAS.
      Returns:
      A String representing the SAS query parameters.

    • undeleteShare

      public ShareClient 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);
 fileServiceClient.listShares(listSharesOptions, Duration.ofSeconds(1), context).forEach(
     deletedShare -> {
         ShareClient shareClient = fileServiceClient.undeleteShare(
             deletedShare.getName(), deletedShare.getVersion());
     }
 );

      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 ShareClient used to interact with the restored share.

    • undeleteShareWithResponse

      public com.azure.core.http.rest.Response<ShareClient> undeleteShareWithResponse(String deletedShareName, String deletedShareVersion, Duration timeout, com.azure.core.util.Context context)
      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);
 fileServiceClient.listShares(listSharesOptions, Duration.ofSeconds(1), context).forEach(
     deletedShare -> {
         ShareClient shareClient = fileServiceClient.undeleteShareWithResponse(
             deletedShare.getName(), deletedShare.getVersion(), Duration.ofSeconds(1), context).getValue();
     }
 );

      For more information, see the Azure Docs.

      Parameters:
      deletedShareName - The name of the previously deleted share.
      deletedShareVersion - The version of the previously deleted share.
      timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A Response whose value contains the ShareClient used to interact with the restored share.