Package com.azure.storage.blob

Class BlobServiceClient

java.lang.Object
com.azure.storage.blob.BlobServiceClient
public final class BlobServiceClient extends Object
Client to a storage account. It may only be instantiated through a BlobServiceClientBuilder. This class does not hold any state about a particular storage account but is instead a convenient way of sending off appropriate requests to the resource on the service. It may also be used to construct URLs to blobs and containers.

This client contains operations on a blob. Operations on a container are available on BlobContainerClient through getBlobContainerClient(String), and operations on a blob are available on BlobClient.

Please see here for more information on containers.

  • Method Details

    • getBlobContainerClient

      public BlobContainerClient getBlobContainerClient(String containerName)
      Initializes a BlobContainerClient object pointing to the specified container. This method does not create a container. It simply constructs the URL to the container and offers access to methods relevant to containers.

      Code Samples

       BlobContainerClient blobContainerClient = client.getBlobContainerClient("containerName");
      Parameters:
      containerName - The name of the container to point to.
      Returns:
      A BlobContainerClient object pointing to the specified container

    • getHttpPipeline

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

    • getServiceVersion

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

    • createBlobContainer

      public BlobContainerClient createBlobContainer(String containerName)
      Creates a new container within a storage account. If a container with the same name already exists, the operation fails. For more information, see the Azure Docs.

      Code Samples

       BlobContainerClient blobContainerClient = client.createBlobContainer("containerName");
      Parameters:
      containerName - Name of the container to create
      Returns:
      The BlobContainerClient used to interact with the container created.

    • createBlobContainerWithResponse

      public com.azure.core.http.rest.Response<BlobContainerClient> createBlobContainerWithResponse(String containerName, Map<String,String> metadata, PublicAccessType accessType, com.azure.core.util.Context context)
      Creates a new container within a storage account. If a container with the same name already exists, the operation fails. For more information, see the Azure Docs.

      Code Samples

       Map<String, String> metadata = Collections.singletonMap("metadata", "value");
 Context context = new Context("Key", "Value");

 BlobContainerClient blobContainerClient = client.createBlobContainerWithResponse(
     "containerName",
     metadata,
     PublicAccessType.CONTAINER,
     context).getValue();
      Parameters:
      containerName - Name of the container to create
      metadata - Metadata to associate with the container. If there is leading or trailing whitespace in any metadata key or value, it must be removed or encoded.
      accessType - Specifies how the data in this container is available to the public. See the x-ms-blob-public-access header in the Azure Docs for more information. Pass null for no public access.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A Response whose value contains the BlobContainerClient used to interact with the container created.

    • createBlobContainerIfNotExists

      public BlobContainerClient createBlobContainerIfNotExists(String containerName)
      Creates a new container within a storage account if it does not exist. For more information, see the Azure Docs.

      Code Samples

       BlobContainerClient blobContainerClient = client.createBlobContainerIfNotExists("containerName");
      Parameters:
      containerName - Name of the container to create
      Returns:
      The BlobContainerClient used to interact with the container created.

    • createBlobContainerIfNotExistsWithResponse

      public com.azure.core.http.rest.Response<BlobContainerClient> createBlobContainerIfNotExistsWithResponse(String containerName, BlobContainerCreateOptions options, com.azure.core.util.Context context)
      Creates a new container within a storage account if it does not exist. For more information, see the Azure Docs.

      Code Samples

       Map<String, String> metadata = Collections.singletonMap("metadata", "value");
 Context context = new Context("Key", "Value");
 BlobContainerCreateOptions options = new BlobContainerCreateOptions().setMetadata(metadata)
     .setPublicAccessType(PublicAccessType.CONTAINER);

 Response<BlobContainerClient> response = client.createBlobContainerIfNotExistsWithResponse("containerName",
     options, context);

 if (response.getStatusCode() == 409) {
     System.out.println("Already existed.");
 } else {
     System.out.printf("Create completed with status %d%n", response.getStatusCode());
 }
      Parameters:
      containerName - Name of the container to create
      options - BlobContainerCreateOptions
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A Response whose value contains the BlobContainerClient used to interact with the container created. If Response's status code is 201, a new container was successfully created. If status code is 409, a container with the same name already existed at this location.

    • deleteBlobContainer

      public void deleteBlobContainer(String containerName)
      Deletes the specified container in the storage account. If the container doesn't exist the operation fails. For more information see the Azure Docs.

      Code Samples

       try {
     client.deleteBlobContainer("container Name");
     System.out.printf("Delete container completed with status %n");
 } catch (UnsupportedOperationException error) {
     System.out.printf("Delete container failed: %s%n", error);
 }
      Parameters:
      containerName - Name of the container to delete

    • deleteBlobContainerWithResponse

      public com.azure.core.http.rest.Response<Void> deleteBlobContainerWithResponse(String containerName, com.azure.core.util.Context context)
      Deletes the specified container in the storage account. If the container doesn't exist the operation fails. For more information see the Azure Docs.
      Parameters:
      containerName - Name of the container to delete
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A response containing status code and HTTP headers

    • deleteBlobContainerIfExists

      public boolean deleteBlobContainerIfExists(String containerName)
      Deletes the specified container in the storage account if it exists. For more information see the Azure Docs.

      Code Samples

       boolean result = client.deleteBlobContainerIfExists("container Name");
 System.out.println("Delete container completed: " + result);
      Parameters:
      containerName - Name of the container to delete
      Returns:
      true if the container is successfully deleted, false if the container does not exist.

    • deleteBlobContainerIfExistsWithResponse

      public com.azure.core.http.rest.Response<Boolean> deleteBlobContainerIfExistsWithResponse(String containerName, com.azure.core.util.Context context)
      Deletes the specified container in the storage account if it exists. For more information see the Azure Docs.

      Code Samples

       Context context = new Context("Key", "Value");

 Response<Boolean> response = client.deleteBlobContainerIfExistsWithResponse("containerName", context);
 if (response.getStatusCode() == 404) {
     System.out.println("Does not exist.");
 } else {
     System.out.printf("Delete completed with status %d%n", response.getStatusCode());
 }
      Parameters:
      containerName - Name of the container to delete
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A response containing status code and HTTP headers. If Response's status code is 202, the blob container was successfully deleted. If status code is 404, the container does not exist.

    • getAccountUrl

      public String getAccountUrl()
      Gets the URL of the storage account represented by this client.
      Returns:
      the URL.

    • listBlobContainers

      public com.azure.core.http.rest.PagedIterable<BlobContainerItem> listBlobContainers()
      Returns a lazy loaded list of containers in this account. The returned PagedIterable can be consumed while new items are automatically retrieved as needed. For more information, see the Azure Docs.

      Code Samples

       client.listBlobContainers().forEach(container -> System.out.printf("Name: %s%n", container.getName()));
      Returns:
      The list of containers.

    • listBlobContainers

      public com.azure.core.http.rest.PagedIterable<BlobContainerItem> listBlobContainers(ListBlobContainersOptions options, Duration timeout)
      Returns a lazy loaded list of containers in this account. The returned PagedIterable can be consumed while new items are automatically retrieved as needed. For more information, see the Azure Docs.

      Code Samples

       ListBlobContainersOptions options = new ListBlobContainersOptions()
     .setPrefix("containerNamePrefixToMatch")
     .setDetails(new BlobContainerListDetails().setRetrieveMetadata(true));

 client.listBlobContainers(options, timeout).forEach(container -> System.out.printf("Name: %s%n", container.getName()));
      Parameters:
      options - A ListBlobContainersOptions which specifies what data should be returned by the service. 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 value beyond which a RuntimeException will be raised.
      Returns:
      The list of containers.

    • findBlobsByTags

      public com.azure.core.http.rest.PagedIterable<TaggedBlobItem> findBlobsByTags(String query)
      Returns a lazy loaded list of blobs in this account whose tags match the query expression. The returned PagedIterable can be consumed while new items are automatically retrieved as needed. For more information, including information on the query syntax, see the Azure Docs.

      Code Samples

       client.findBlobsByTags("where=tag=value").forEach(blob -> System.out.printf("Name: %s%n", blob.getName()));
      Parameters:
      query - Filters the results to return only blobs whose tags match the specified expression.
      Returns:
      The list of blobs.

    • findBlobsByTags

      public com.azure.core.http.rest.PagedIterable<TaggedBlobItem> findBlobsByTags(FindBlobsOptions options, Duration timeout, com.azure.core.util.Context context)
      Returns a lazy loaded list of blobs in this account whose tags match the query expression. The returned PagedIterable can be consumed while new items are automatically retrieved as needed. For more information, including information on the query syntax, see the Azure Docs.

      Code Samples

       Context context = new Context("Key", "Value");
 client.findBlobsByTags(new FindBlobsOptions("where=tag=value").setMaxResultsPerPage(10), timeout, context)
     .forEach(blob -> System.out.printf("Name: %s%n", blob.getName()));
      Parameters:
      options - FindBlobsOptions. 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 value beyond which a RuntimeException will be raised.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      The list of blobs.

    • getProperties

      public BlobServiceProperties getProperties()
      Gets the properties of a storage account’s Blob service. For more information, see the Azure Docs.

      Code Samples

       BlobServiceProperties properties = client.getProperties();

 System.out.printf("Hour metrics enabled: %b, Minute metrics enabled: %b%n",
     properties.getHourMetrics().isEnabled(),
     properties.getMinuteMetrics().isEnabled());
      Returns:
      The storage account properties.

    • getPropertiesWithResponse

      public com.azure.core.http.rest.Response<BlobServiceProperties> getPropertiesWithResponse(Duration timeout, com.azure.core.util.Context context)
      Gets the properties of a storage account’s Blob service. For more information, see the Azure Docs.

      Code Samples

       Context context = new Context("Key", "Value");
 BlobServiceProperties properties = client.getPropertiesWithResponse(timeout, context).getValue();

 System.out.printf("Hour metrics enabled: %b, Minute metrics enabled: %b%n",
     properties.getHourMetrics().isEnabled(),
     properties.getMinuteMetrics().isEnabled());
      Parameters:
      timeout - An optional timeout value beyond which a RuntimeException will be raised.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A Response whose value contains the storage account properties.

    • setProperties

      public void setProperties(BlobServiceProperties properties)
      Sets properties for a storage account's Blob service endpoint. For more information, see the Azure Docs. Note that setting the default service version has no effect when using this client because this client explicitly sets the version header on each request, overriding the default.

      This method checks to ensure the properties being sent follow the specifications indicated in the Azure Docs. If CORS policies are set, CORS parameters that are not set default to the empty string.

      Code Samples

       BlobRetentionPolicy loggingRetentionPolicy = new BlobRetentionPolicy().setEnabled(true).setDays(3);
 BlobRetentionPolicy metricsRetentionPolicy = new BlobRetentionPolicy().setEnabled(true).setDays(1);

 BlobServiceProperties properties = new BlobServiceProperties()
     .setLogging(new BlobAnalyticsLogging()
         .setWrite(true)
         .setDelete(true)
         .setRetentionPolicy(loggingRetentionPolicy))
     .setHourMetrics(new BlobMetrics()
         .setEnabled(true)
         .setRetentionPolicy(metricsRetentionPolicy))
     .setMinuteMetrics(new BlobMetrics()
         .setEnabled(true)
         .setRetentionPolicy(metricsRetentionPolicy));

 try {
     client.setProperties(properties);
     System.out.printf("Setting properties completed%n");
 } catch (UnsupportedOperationException error) {
     System.out.printf("Setting properties failed: %s%n", error);
 }
      Parameters:
      properties - Configures the service.

    • setPropertiesWithResponse

      public com.azure.core.http.rest.Response<Void> setPropertiesWithResponse(BlobServiceProperties properties, Duration timeout, com.azure.core.util.Context context)
      Sets properties for a storage account's Blob service endpoint. For more information, see the Azure Docs. Note that setting the default service version has no effect when using this client because this client explicitly sets the version header on each request, overriding the default.

      This method checks to ensure the properties being sent follow the specifications indicated in the Azure Docs. If CORS policies are set, CORS parameters that are not set default to the empty string.

      Code Samples

       BlobRetentionPolicy loggingRetentionPolicy = new BlobRetentionPolicy().setEnabled(true).setDays(3);
 BlobRetentionPolicy metricsRetentionPolicy = new BlobRetentionPolicy().setEnabled(true).setDays(1);

 BlobServiceProperties properties = new BlobServiceProperties()
     .setLogging(new BlobAnalyticsLogging()
         .setWrite(true)
         .setDelete(true)
         .setRetentionPolicy(loggingRetentionPolicy))
     .setHourMetrics(new BlobMetrics()
         .setEnabled(true)
         .setRetentionPolicy(metricsRetentionPolicy))
     .setMinuteMetrics(new BlobMetrics()
         .setEnabled(true)
         .setRetentionPolicy(metricsRetentionPolicy));

 Context context = new Context("Key", "Value");

 System.out.printf("Setting properties completed with status %d%n",
     client.setPropertiesWithResponse(properties, timeout, context).getStatusCode());
      Parameters:
      properties - Configures the service.
      timeout - An optional timeout value beyond which a RuntimeException will be raised.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      The storage account properties.

    • getUserDelegationKey

      public UserDelegationKey getUserDelegationKey(OffsetDateTime start, OffsetDateTime expiry)
      Gets a user delegation key for use with this account's blob storage. Note: This method call is only valid when using TokenCredential in this object's HttpPipeline.

      Code Samples

       System.out.printf("User delegation key: %s%n",
     client.getUserDelegationKey(delegationKeyStartTime, delegationKeyExpiryTime));
      Parameters:
      start - Start time for the key's validity. Null indicates immediate start.
      expiry - Expiration of the key's validity.
      Returns:
      The user delegation key.

    • getUserDelegationKeyWithResponse

      public com.azure.core.http.rest.Response<UserDelegationKey> getUserDelegationKeyWithResponse(OffsetDateTime start, OffsetDateTime expiry, Duration timeout, com.azure.core.util.Context context)
      Gets a user delegation key for use with this account's blob storage. Note: This method call is only valid when using TokenCredential in this object's HttpPipeline.

      Code Samples

       System.out.printf("User delegation key: %s%n",
     client.getUserDelegationKeyWithResponse(delegationKeyStartTime, delegationKeyExpiryTime, timeout, context));
      Parameters:
      start - Start time for the key's validity. Null indicates immediate start.
      expiry - Expiration of the key's validity.
      timeout - An optional timeout value beyond which a RuntimeException will be raised.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A Response whose value contains the user delegation key.

    • getStatistics

      public BlobServiceStatistics getStatistics()
      Retrieves statistics related to replication for the Blob service. It is only available on the secondary location endpoint when read-access geo-redundant replication is enabled for the storage account. For more information, see the Azure Docs.

      Code Samples

       System.out.printf("Geo-replication status: %s%n",
     client.getStatistics().getGeoReplication().getStatus());
      Returns:
      The storage account statistics.

    • getStatisticsWithResponse

      public com.azure.core.http.rest.Response<BlobServiceStatistics> getStatisticsWithResponse(Duration timeout, com.azure.core.util.Context context)
      Retrieves statistics related to replication for the Blob service. It is only available on the secondary location endpoint when read-access geo-redundant replication is enabled for the storage account. For more information, see the Azure Docs.

      Code Samples

       System.out.printf("Geo-replication status: %s%n",
     client.getStatisticsWithResponse(timeout, context).getValue().getGeoReplication().getStatus());
      Parameters:
      timeout - An optional timeout value beyond which a RuntimeException will be raised.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A Response whose value the storage account statistics.

    • getAccountInfo

      public StorageAccountInfo getAccountInfo()
      Returns the sku name and account kind for the account. For more information, please see the Azure Docs.

      Code Samples

       StorageAccountInfo accountInfo = client.getAccountInfo();

 System.out.printf("Account kind: %s, SKU: %s%n", accountInfo.getAccountKind(), accountInfo.getSkuName());
      Returns:
      The storage account info.

    • getAccountInfoWithResponse

      public com.azure.core.http.rest.Response<StorageAccountInfo> getAccountInfoWithResponse(Duration timeout, com.azure.core.util.Context context)
      Returns the sku name and account kind for the account. For more information, please see the Azure Docs.
      Parameters:
      timeout - An optional timeout value beyond which a RuntimeException will be raised.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A Response whose value contains the storage account info.

    • getAccountName

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

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

      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 = client.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.

    • undeleteBlobContainer

      public BlobContainerClient undeleteBlobContainer(String deletedContainerName, String deletedContainerVersion)
      Restores a previously deleted container. If the container associated with provided deletedContainerName already exists, this call will result in a 409 (conflict). This API is only functional if Container Soft Delete is enabled for the storage account associated with the container.

      Code Samples

       ListBlobContainersOptions listBlobContainersOptions = new ListBlobContainersOptions();
 listBlobContainersOptions.getDetails().setRetrieveDeleted(true);
 client.listBlobContainers(listBlobContainersOptions, null).forEach(
     deletedContainer -> {
         BlobContainerClient blobContainerClient = client.undeleteBlobContainer(
             deletedContainer.getName(), deletedContainer.getVersion());
     }
 );
      Parameters:
      deletedContainerName - The name of the previously deleted container.
      deletedContainerVersion - The version of the previously deleted container.
      Returns:
      The BlobContainerClient used to interact with the restored container.

    • undeleteBlobContainerWithResponse

      public com.azure.core.http.rest.Response<BlobContainerClient> undeleteBlobContainerWithResponse(UndeleteBlobContainerOptions options, Duration timeout, com.azure.core.util.Context context)
      Restores a previously deleted container. The restored container will be renamed to the destinationContainerName if provided in options. Otherwise deletedContainerName is used as destination container name. If the container associated with provided destinationContainerName already exists, this call will result in a 409 (conflict). This API is only functional if Container Soft Delete is enabled for the storage account associated with the container.

      Code Samples

       ListBlobContainersOptions listBlobContainersOptions = new ListBlobContainersOptions();
 listBlobContainersOptions.getDetails().setRetrieveDeleted(true);
 client.listBlobContainers(listBlobContainersOptions, null).forEach(
     deletedContainer -> {
         BlobContainerClient blobContainerClient = client.undeleteBlobContainerWithResponse(
             new UndeleteBlobContainerOptions(deletedContainer.getName(), deletedContainer.getVersion()),
             timeout, context).getValue();
     }
 );
      Parameters:
      options - UndeleteBlobContainerOptions.
      timeout - An optional timeout value beyond which a RuntimeException will be raised.
      context - Additional context that is passed through the Http pipeline during the service call.
      Returns:
      A Response whose value contains the BlobContainerClient used to interact with the restored container.