Azure Storage - Blobs
Package	Description
com.azure.storage.blob	Package containing the classes for BlobServiceClient.
com.azure.storage.blob.models	Package containing classes for AzureBlobStorage.
com.azure.storage.blob.sas	Package containing SAS (shared access signature) classes used by Azure Storage Blobs.
com.azure.storage.blob.specialized	Package containing specialized clients for Azure Storage Blobs.

Azure Storage Blob client library for Java

Azure Blob Storage is Microsoft's object storage solution for the cloud. Blob Storage is optimized for storing massive amounts of unstructured data. Unstructured data is data that does not adhere to a particular data model or definition, such as text or binary data.

Source code | API reference documentation | REST API documentation | Product documentation | Samples

Getting started

Prerequisites

Java Development Kit (JDK) with version 8 or above
Azure Subscription
Create Storage Account

Adding the package to your product

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>12.0.0</version>
</dependency>

Default HTTP Client

All client libraries, by default, use the Netty HTTP client. Adding the above dependency will automatically configure Storage Blob to use the Netty HTTP client.

Alternate HTTP client

If, instead of Netty it is preferable to use OkHTTP, there is an HTTP client available for that too. Exclude the default Netty and include the OkHTTP client in your pom.xml.

<!-- Add the Storage Blob dependency without the Netty HTTP client -->
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-storage-blob</artifactId>
    <version>12.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>com.azure</groupId>
            <artifactId>azure-core-http-netty</artifactId>
        </exclusion>
    </exclusions>
</dependency>

<!-- Add the OkHTTP client to use with Storage Blob -->
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-core-http-okhttp</artifactId>
    <version>1.0.0</version>
</dependency>

Configuring HTTP Clients

When an HTTP client is included on the classpath, as shown above, it is not necessary to specify it in the client library builders unless you want to customize the HTTP client in some fashion. If this is desired, the httpClient builder method is often available to achieve just this by allowing users to provide custom (or customized) com.azure.core.http.HttpClient instances.

For starters, by having the Netty or OkHTTP dependencies on your classpath, as shown above, you can create new instances of these HttpClient types using their builder APIs. For example, here is how you would create a Netty HttpClient instance:

HttpClient client = new NettyAsyncHttpClientBuilder()
        .port(8080)
        .wiretap(true)
        .build();

Create a Storage Account

To create a Storage Account you can use the Azure Portal or Azure CLI.

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

Authenticate the client

In order to interact with the Storage Service (Blob, Queue, Message, MessageId, File) you'll need to create an instance of the Service Client class. To make this possible you'll need the Account SAS (shared access signature) string of the Storage Account. Learn more at SAS Token

Get credentials

SAS Token

a. Use the Azure CLI snippet below to get the SAS token from the Storage Account.

az storage blob generate-sas \
    --account-name {Storage Account name} \
    --container-name {container name} \
    --name {blob name} \
    --permissions {permissions to grant} \
    --expiry {datetime to expire the SAS token} \
    --services {storage services the SAS allows} \
    --resource-types {resource types the SAS allows}

Example:

CONNECTION_STRING=<connection-string>

az storage blob generate-sas \
    --account-name MyStorageAccount \
    --container-name MyContainer \
    --name MyBlob \
    --permissions racdw \
    --expiry 2020-06-15

b. Alternatively, get the Account SAS Token from the Azure Portal.

Go to your Storage Account
Select Shared access signature from the menu on the left
Click on Generate SAS and connection string (after setup)

Shared Key Credential

a. Use Account name and Account key. Account name is your Storage Account name.

Go to your Storage Account
Select Access keys from the menu on the left
Under key1/key2 copy the contents of the Key field

b. Use the connection string.

Go to your Storage Account
Select Access keys from the menu on the left
Under key1/key2 copy the contents of the Connection string field

Key concepts

Blob Storage is designed for:

Serving images or documents directly to a browser
Storing files for distributed access
Streaming video and audio
Writing to log files
Storing data for backup and restore, disaster recovery, and archiving
Storing data for analysis by an on-premises or Azure-hosted service

Examples

The following sections provide several code snippets covering some of the most common Azure Storage Blob tasks, including:

Create a BlobServiceClient
Create a BlobContainerClient
Create a BlobClient
Create a container
Upload a blob from a stream
Upload a blob from local path
Download a blob to a stream
Download a blob to local path
Enumerate blobs
Authenticate with Azure Identity

Create a `BlobServiceClient`

Create a BlobServiceClient using the sasToken generated above.

BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("<your-storage-blob-url>")
        .sasToken("<your-sasToken>")
        .buildClient();

Create a `BlobContainerClient`

Create a BlobContainerClient using a BlobServiceClient.

BlobContainerClient blobContainerClient = blobServiceClient.getBlobContainerClient("mycontainer");

Create a BlobContainerClient from the builder sasToken generated above.

BlobContainerClient blobContainerClient = new BlobContainerClientBuilder()
        .endpoint("<your-storage-blob-url>")
        .sasToken("<your-sasToken>")
        .containerName("mycontainer")
        .buildClient();

Create a `BlobClient`

Create a BlobClient using a BlobContainerClient.

BlobClient blobClient = blobContainerClient.getBlobClient("myblob");

Create a BlobClient from the builder sasToken generated above.

BlobClient blobClient = new BlobClientBuilder()
        .endpoint("<your-storage-blob-url>")
        .sasToken("<your-sasToken>")
        .containerName("mycontainer")
        .blobName("myblob")
        .buildClient();

Create a container

Create a container using a BlobServiceClient.

blobServiceClient.createBlobContainer("mycontainer");

Create a container using a BlobContainerClient.

blobContainerClient.create();

Upload a blob from a stream

Upload from an InputStream to a blob using a BlockBlobClient generated from a BlobContainerClient.

BlockBlobClient blockBlobClient = blobContainerClient.getBlobClient("myblockblob").getBlockBlobClient();
String dataSample = "samples";
try (ByteArrayInputStream dataStream = new ByteArrayInputStream(dataSample.getBytes())) {
    blockBlobClient.upload(dataStream, dataSample.length());
}

Upload a blob from local path

Upload a file to a blob using a BlobClient generated from a BlobContainerClient.

BlobClient blobClient = blobContainerClient.getBlobClient("myblockblob");
blobClient.uploadFromFile("local-file.jpg");

Download a blob to a stream

Download a blob to an OutputStream using a BlobClient.

try(ByteArrayOutputStream outputStream = new ByteArrayOutputStream()) {
    blobClient.download(outputStream);
}

Download a blob to local path

Download blob to a local file using a BlobClient.

blobClient.downloadToFile("downloaded-file.jpg");

Enumerate blobs

Enumerating all blobs using a BlobContainerClient.

blobContainerClient.listBlobs()
        .forEach(
            blobItem -> System.out.println("This is the blob name: " + blobItem.getName())
        );

Authenticate with Azure Identity

The Azure Identity library provides Azure Active Directory support for authenticating with Azure Storage.

BlobServiceClient blobStorageClient = new BlobServiceClientBuilder()
        .endpoint(endpoint)
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

Troubleshooting

When interacting with blobs using this Java client library, errors returned by the service correspond to the same HTTP status codes returned for REST API requests. For example, if you try to retrieve a container or blob that doesn't exist in your Storage Account, a 404 error is returned, indicating Not Found.

Next steps

Several Storage blob Java SDK samples are available to you in the SDK's GitHub repository. These samples provide example code for additional scenarios commonly encountered while working with Key Vault:

Next steps Samples

Samples are explained in detail here.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Impressions

Azure SDK for Java Reference Documentation