title | description | author | ms.author | ms.custom | ms.date | ms.service | ms.topic | ms.devlang | zone_pivot_groups |
---|---|---|---|---|---|---|---|---|---|
Quickstart: Azure Blob Storage library - Java |
In this quickstart, you learn how to use the Azure Blob Storage client library for Java to create a container and a blob in Blob (object) storage. Next, you learn how to download the blob to your local computer, and how to list all of the blobs in a container. |
pauljewellmsft |
pauljewell |
devx-track-java, mode-api, passwordless-java, devx-track-extended-java, devx-track-extended-azdevcli |
03/04/2024 |
azure-blob-storage |
quickstart |
java |
azure-blob-storage-quickstart-options |
::: zone pivot="blob-storage-quickstart-scratch"
Note
The Build from scratch option walks you step by step through the process of creating a new project, installing packages, writing the code, and running a basic console app. This approach is recommended if you want to understand all the details involved in creating an app that connects to Azure Blob Storage. If you prefer to automate deployment tasks and start with a completed project, choose Start with a template.
::: zone-end
::: zone pivot="blob-storage-quickstart-template"
Note
The Start with a template option uses the Azure Developer CLI to automate deployment tasks and starts you off with a completed project. This approach is recommended if you want to explore the code as quickly as possible without going through the setup tasks. If you prefer step by step instructions to build the app, choose Build from scratch.
::: zone-end
Get started with the Azure Blob Storage client library for Java to manage blobs and containers.
::: zone pivot="blob-storage-quickstart-scratch"
In this article, you follow steps to install the package and try out example code for basic tasks.
::: zone-end
::: zone pivot="blob-storage-quickstart-template"
In this article, you use the Azure Developer CLI to deploy Azure resources and run a completed console app with just a few commands.
::: zone-end
Tip
If you're working with Azure Storage resources in a Spring application, we recommend that you consider Spring Cloud Azure as an alternative. Spring Cloud Azure is an open-source project that provides seamless Spring integration with Azure services. To learn more about Spring Cloud Azure, and to see an example using Blob Storage, see Upload a file to an Azure Storage Blob.
API reference documentation | Library source code | Package (Maven) | Samples
::: zone pivot="blob-storage-quickstart-scratch"
- Azure account with an active subscription - create an account for free
- Azure Storage account - create a storage account.
- Java Development Kit (JDK) version 8 or above
- Apache Maven
::: zone-end
::: zone pivot="blob-storage-quickstart-template"
- Azure subscription - create one for free
- Java Development Kit (JDK) version 8 or above
- Apache Maven
- Azure Developer CLI
::: zone-end
::: zone pivot="blob-storage-quickstart-scratch"
This section walks you through preparing a project to work with the Azure Blob Storage client library for Java.
Create a Java application named blob-quickstart.
-
In a console window (such as PowerShell or Bash), use Maven to create a new console app with the name blob-quickstart. Type the following mvn command to create a "Hello world!" Java project.
mvn archetype:generate ` --define interactiveMode=n ` --define groupId=com.blobs.quickstart ` --define artifactId=blob-quickstart ` --define archetypeArtifactId=maven-archetype-quickstart ` --define archetypeVersion=1.4
mvn archetype:generate \ --define interactiveMode=n \ --define groupId=com.blobs.quickstart \ --define artifactId=blob-quickstart \ --define archetypeArtifactId=maven-archetype-quickstart \ --define archetypeVersion=1.4
-
The output from generating the project should look something like this:
[INFO] Scanning for projects... [INFO] [INFO] ------------------< org.apache.maven:standalone-pom >------------------- [INFO] Building Maven Stub Project (No POM) 1 [INFO] --------------------------------[ pom ]--------------------------------- [INFO] [INFO] >>> maven-archetype-plugin:3.1.2:generate (default-cli) > generate-sources @ standalone-pom >>> [INFO] [INFO] <<< maven-archetype-plugin:3.1.2:generate (default-cli) < generate-sources @ standalone-pom <<< [INFO] [INFO] [INFO] --- maven-archetype-plugin:3.1.2:generate (default-cli) @ standalone-pom --- [INFO] Generating project in Batch mode [INFO] ---------------------------------------------------------------------------- [INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4 [INFO] ---------------------------------------------------------------------------- [INFO] Parameter: groupId, Value: com.blobs.quickstart [INFO] Parameter: artifactId, Value: blob-quickstart [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: package, Value: com.blobs.quickstart [INFO] Parameter: packageInPathFormat, Value: com/blobs/quickstart [INFO] Parameter: version, Value: 1.0-SNAPSHOT [INFO] Parameter: package, Value: com.blobs.quickstart [INFO] Parameter: groupId, Value: com.blobs.quickstart [INFO] Parameter: artifactId, Value: blob-quickstart [INFO] Project created from Archetype in dir: C:\QuickStarts\blob-quickstart [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 7.056 s [INFO] Finished at: 2019-10-23T11:09:21-07:00 [INFO] ------------------------------------------------------------------------ ```
-
Switch to the newly created blob-quickstart folder.
cd blob-quickstart
-
In side the blob-quickstart directory, create another directory called data. This folder is where the blob data files will be created and stored.
mkdir data
Open the pom.xml
file in your text editor.
Add azure-sdk-bom to take a dependency on the latest version of the library. In the following snippet, replace the {bom_version_to_target}
placeholder with the version number. Using azure-sdk-bom keeps you from having to specify the version of each individual dependency. To learn more about the BOM, see the Azure SDK BOM README.
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-sdk-bom</artifactId>
<version>{bom_version_to_target}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Then add the following dependency elements to the group of dependencies. The azure-identity dependency is needed for passwordless connections to Azure services.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-blob</artifactId>
</dependency>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
</dependency>
From the project directory, follow steps to create the basic structure of the app:
- Navigate to the /src/main/java/com/blobs/quickstart directory
- Open the
App.java
file in your editor - Delete the line
System.out.println("Hello world!");
- Add the necessary
import
directives
The code should resemble this framework:
package com.blobs.quickstart;
/**
* Azure Blob Storage quickstart
*/
import com.azure.identity.*;
import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;
import java.io.*;
public class App
{
public static void main(String[] args) throws IOException
{
// Quickstart code goes here
}
}
::: zone-end
::: zone pivot="blob-storage-quickstart-template"
With Azure Developer CLI installed, you can create a storage account and run the sample code with just a few commands. You can run the project in your local development environment, or in a DevContainer.
From an empty directory, follow these steps to initialize the azd
template, provision Azure resources, and get started with the code:
-
Clone the quickstart repository assets from GitHub and initialize the template locally:
azd init --template blob-storage-quickstart-java
You'll be prompted for the following information:
- Environment name: This value is used as a prefix for all Azure resources created by Azure Developer CLI. The name must be unique across all Azure subscriptions and must be between 3 and 24 characters long. The name can contain numbers and lowercase letters only.
-
Log in to Azure:
azd auth login
-
Provision and deploy the resources to Azure:
azd up
You'll be prompted for the following information:
- Subscription: The Azure subscription that your resources are deployed to.
- Location: The Azure region where your resources are deployed.
The deployment might take a few minutes to complete. The output from the
azd up
command includes the name of the newly created storage account, which you'll need later to run the code.
At this point, the resources are deployed to Azure and the code is almost ready to run. Follow these steps to update the name of the storage account in the code, and run the sample console app:
- Update the storage account name:
- In the local directory, navigate to the blob-quickstart/src/main/java/com/blobs/quickstart directory.
- Open the file named App.java in your editor. Find the
<storage-account-name>
placeholder and replace it with the actual name of the storage account created by theazd up
command. - Save the changes.
- Run the project:
- Navigate to the blob-quickstart directory containing the
pom.xml
file. Compile the project by using the followingmvn
command:mvn compile
- Package the compiled code in its distributable format:
mvn package
- Run the following
mvn
command to execute the app:mvn exec:java
- Navigate to the blob-quickstart directory containing the
- Observe the output: This app creates a test file in your local data folder and uploads it to a container in the storage account. The example then lists the blobs in the container and downloads the file with a new name so that you can compare the old and new files.
To learn more about how the sample code works, see Code examples.
When you're finished testing the code, see the Clean up resources section to delete the resources created by the azd up
command.
::: zone-end
Azure Blob Storage is optimized for storing massive amounts of unstructured data. Unstructured data doesn't adhere to a particular data model or definition, such as text or binary data. Blob storage offers three types of resources:
- The storage account
- A container in the storage account
- A blob in the container
The following diagram shows the relationship between these resources.
Use the following Java classes to interact with these resources:
- BlobServiceClient: The
BlobServiceClient
class allows you to manipulate Azure Storage resources and blob containers. The storage account provides the top-level namespace for the Blob service. - BlobServiceClientBuilder: The
BlobServiceClientBuilder
class provides a fluent builder API to help aid the configuration and instantiation ofBlobServiceClient
objects. - BlobContainerClient: The
BlobContainerClient
class allows you to manipulate Azure Storage containers and their blobs. - BlobClient: The
BlobClient
class allows you to manipulate Azure Storage blobs. - BlobItem: The
BlobItem
class represents individual blobs returned from a call to listBlobs.
These example code snippets show you how to perform the following actions with the Azure Blob Storage client library for Java:
- Authenticate to Azure and authorize access to blob data
- Create a container
- Upload blobs to a container
- List the blobs in a container
- Download blobs
- Delete a container
::: zone pivot="blob-storage-quickstart-scratch"
Important
Make sure you have the correct dependencies in pom.xml and the necessary directives for the code samples to work, as described in the setting up section.
::: zone-end
::: zone pivot="blob-storage-quickstart-template"
Note
The Azure Developer CLI template includes a file with sample code already in place. The following examples provide detail for each part of the sample code. The template implements the recommended passwordless authentication method, as described in the Authenticate to Azure section. The connection string method is shown as an alternative, but isn't used in the template and isn't recommended for production code.
::: zone-end
[!INCLUDE storage-quickstart-passwordless-auth-intro]
DefaultAzureCredential
is a class provided by the Azure Identity client library for Java. DefaultAzureCredential
supports multiple authentication methods and determines which method should be used at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code.
The order and locations in which DefaultAzureCredential
looks for credentials can be found in the Azure Identity library overview.
For example, your app can authenticate using your Visual Studio Code sign-in credentials with when developing locally. Your app can then use a managed identity once it has been deployed to Azure. No code changes are required for this transition.
[!INCLUDE assign-roles]
You can authorize access to data in your storage account using the following steps:
-
Make sure you're authenticated with the same Microsoft Entra account you assigned the role to on your storage account. You can authenticate via the Azure CLI, Visual Studio Code, or Azure PowerShell.
Sign-in to Azure through the Azure CLI using the following command:
az login
You'll need to install the Azure CLI to work with
DefaultAzureCredential
through Visual Studio Code.On the main menu of Visual Studio Code, navigate to Terminal > New Terminal.
Sign-in to Azure through the Azure CLI using the following command:
az login
Sign-in to Azure using PowerShell via the following command:
Connect-AzAccount
-
To use
DefaultAzureCredential
, make sure that the azure-identity dependency is added inpom.xml
:<dependency> <groupId>com.azure</groupId> <artifactId>azure-identity</artifactId> </dependency>
-
Add this code to the
Main
method. When the code runs on your local workstation, it will use the developer credentials of the prioritized tool you're logged into to authenticate to Azure, such as the Azure CLI or Visual Studio Code.:::code language="java" source="~/azure-storage-snippets/blobs/quickstarts/Java/blob-quickstart/src/main/java/com/blobs/quickstart/App.java" id="Snippet_CreateServiceClientDAC":::
-
Make sure to update the storage account name in the URI of your
BlobServiceClient
. The storage account name can be found on the overview page of the Azure portal.:::image type="content" source="./media/storage-quickstart-blobs-java/storage-account-name.png" alt-text="A screenshot showing how to find the storage account name.":::
[!NOTE] When deployed to Azure, this same code can be used to authorize requests to Azure Storage from an application running in Azure. However, you'll need to enable managed identity on your app in Azure. Then configure your storage account to allow that managed identity to connect. For detailed instructions on configuring this connection between Azure services, see the Auth from Azure-hosted apps tutorial.
A connection string includes the storage account access key and uses it to authorize requests. Always be careful to never expose the keys in an unsecure location.
Note
To authorize data access with the storage account access key, you'll need permissions for the following Azure RBAC action: Microsoft.Storage/storageAccounts/listkeys/action. The least privileged built-in role with permissions for this action is Reader and Data Access, but any role which includes this action will work.
[!INCLUDE retrieve credentials]
After you copy the connection string, write it to a new environment variable on the local machine running the application. To set the environment variable, open a console window, and follow the instructions for your operating system. Replace <yourconnectionstring>
with your actual connection string.
Windows:
setx AZURE_STORAGE_CONNECTION_STRING "<yourconnectionstring>"
After you add the environment variable in Windows, you must start a new instance of the command window.
Linux:
export AZURE_STORAGE_CONNECTION_STRING="<yourconnectionstring>"
The code below retrieves the connection string for the storage account from the environment variable created earlier, and uses the connection string to construct a service client object.
::: zone pivot="blob-storage-quickstart-scratch"
Add this code to the end of the Main
method:
::: zone-end
// Retrieve the connection string for use with the application.
String connectStr = System.getenv("AZURE_STORAGE_CONNECTION_STRING");
// Create a BlobServiceClient object using a connection string
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
.connectionString(connectStr)
.buildClient();
Important
The account access key should be used with caution. If your account access key is lost or accidentally placed in an insecure location, your service may become vulnerable. Anyone who has the access key is able to authorize requests against the storage account, and effectively has access to all the data. DefaultAzureCredential
provides enhanced security features and benefits and is the recommended approach for managing authorization to Azure services.
Create a new container in your storage account by calling the createBlobContainer method on the blobServiceClient
object. In this example, the code appends a GUID value to the container name to ensure that it's unique.
::: zone pivot="blob-storage-quickstart-scratch"
Add this code to the end of the Main
method:
::: zone-end
:::code language="java" source="~/azure-storage-snippets/blobs/quickstarts/Java/blob-quickstart/src/main/java/com/blobs/quickstart/App.java" id="Snippet_CreateContainer":::
To learn more about creating a container, and to explore more code samples, see Create a blob container with Java.
Important
Container names must be lowercase. For more information about naming containers and blobs, see Naming and Referencing Containers, Blobs, and Metadata.
Upload a blob to a container by calling the uploadFromFile method. The example code creates a text file in the local data directory to upload to the container.
::: zone pivot="blob-storage-quickstart-scratch"
Add this code to the end of the Main
method:
::: zone-end
:::code language="java" source="~/azure-storage-snippets/blobs/quickstarts/Java/blob-quickstart/src/main/java/com/blobs/quickstart/App.java" id="Snippet_UploadBlobFromFile":::
To learn more about uploading blobs, and to explore more code samples, see Upload a blob with Java.
List the blobs in the container by calling the listBlobs method. In this case, only one blob has been added to the container, so the listing operation returns just that one blob.
::: zone pivot="blob-storage-quickstart-scratch"
Add this code to the end of the Main
method:
::: zone-end
:::code language="java" source="~/azure-storage-snippets/blobs/quickstarts/Java/blob-quickstart/src/main/java/com/blobs/quickstart/App.java" id="Snippet_ListBlobs":::
To learn more about listing blobs, and to explore more code samples, see List blobs with Java.
Download the previously created blob by calling the downloadToFile method. The example code adds a suffix of "DOWNLOAD" to the file name so that you can see both files in local file system.
::: zone pivot="blob-storage-quickstart-scratch"
Add this code to the end of the Main
method:
::: zone-end
:::code language="java" source="~/azure-storage-snippets/blobs/quickstarts/Java/blob-quickstart/src/main/java/com/blobs/quickstart/App.java" id="Snippet_DownloadBlob":::
To learn more about downloading blobs, and to explore more code samples, see Download a blob with Java.
The following code cleans up the resources the app created by removing the entire container using the delete method. It also deletes the local files created by the app.
The app pauses for user input by calling System.console().readLine()
before it deletes the blob, container, and local files. This is a good chance to verify that the resources were created correctly, before they're deleted.
::: zone pivot="blob-storage-quickstart-scratch"
Add this code to the end of the Main
method:
::: zone-end
:::code language="java" source="~/azure-storage-snippets/blobs/quickstarts/Java/blob-quickstart/src/main/java/com/blobs/quickstart/App.java" id="Snippet_DeleteContainer":::
To learn more about deleting a container, and to explore more code samples, see Delete and restore a blob container with Java.
::: zone pivot="blob-storage-quickstart-scratch"
This app creates a test file in your local folder and uploads it to Blob storage. The example then lists the blobs in the container and downloads the file with a new name so that you can compare the old and new files.
Follow steps to compile, package, and run the code
- Navigate to the directory containing the
pom.xml
file and compile the project by using the followingmvn
command:mvn compile
- Package the compiled code in its distributable format:
mvn package
- Run the following
mvn
command to execute the app:To simplify the run step, you can addmvn exec:java -D exec.mainClass=com.blobs.quickstart.App -D exec.cleanupDaemonThreads=false
exec-maven-plugin
topom.xml
and configure as shown below:With this configuration, you can execute the app with the following command:<plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>exec-maven-plugin</artifactId> <version>1.4.0</version> <configuration> <mainClass>com.blobs.quickstart.App</mainClass> <cleanupDaemonThreads>false</cleanupDaemonThreads> </configuration> </plugin>
mvn exec:java
The output of the app is similar to the following example (UUID values omitted for readability):
Azure Blob Storage - Java quickstart sample
Uploading to Blob storage as blob:
https://mystorageacct.blob.core.windows.net/quickstartblobsUUID/quickstartUUID.txt
Listing blobs...
quickstartUUID.txt
Downloading blob to
./data/quickstartUUIDDOWNLOAD.txt
Press the Enter key to begin clean up
Deleting blob container...
Deleting the local source and downloaded files...
Done
Before you begin the cleanup process, check your data folder for the two files. You can compare them and observe that they're identical.
::: zone-end
::: zone pivot="blob-storage-quickstart-scratch"
After you've verified the files and finished testing, press the Enter key to delete the test files along with the container you created in the storage account. You can also use Azure CLI to delete resources.
::: zone-end
::: zone pivot="blob-storage-quickstart-template"
When you're done with the quickstart, you can clean up the resources you created by running the following command:
azd down
You'll be prompted to confirm the deletion of the resources. Enter y
to confirm.
::: zone-end
In this quickstart, you learned how to upload, download, and list blobs using Java.
To see Blob storage sample apps, continue to:
[!div class="nextstepaction"] Azure Blob Storage library for Java samples
- To learn more, see the Azure Blob Storage client libraries for Java.
- For tutorials, samples, quickstarts, and other documentation, visit Azure for Java developers.