Movatterモバイル変換

This article shows you how to connect to Azure Blob Storage by using the Azure Blob Storage client library for Java. Once connected, use thedeveloper guides to learn how your code can operate on containers, blobs, and features of the Blob Storage service.

If you're looking to start with a complete example, seeQuickstart: Azure Blob Storage client library for Java.

API reference |Package (Maven) |Library source code |Samples |Give feedback

Prerequisites

Azure subscription -create one for free
Azure storage account -create a storage account
Java Development Kit (JDK) version 8 or above
Apache Maven is used for project management in this example

Set up your project

Note

This article uses the Maven build tool to build and run the sample code. Other build tools, such as Gradle, also work with the Azure SDK for Java.

Use Maven to create a new console app, or open an existing project. Follow these steps to install packages and add the necessaryimport directives.

Install packages

Open thepom.xml file in your text editor. Install the packages byincluding the BOM file, orincluding a direct dependency.

Include the BOM file

Addazure-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. Usingazure-sdk-bom keeps you from having to specify the version of each individual dependency. To learn more about the BOM, see theAzure 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>

Add the following dependency elements to the group of dependencies. Theazure-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-storage-common</artifactId></dependency><dependency>    <groupId>com.azure</groupId>    <artifactId>azure-identity</artifactId></dependency>

Include a direct dependency

To take dependency on a particular version of the library, add the direct dependency to your project:

<dependency>    <groupId>com.azure</groupId>    <artifactId>azure-storage-blob</artifactId>    <version>{package_version_to_target}</version></dependency><dependency>      <groupId>com.azure</groupId>      <artifactId>azure-storage-common</artifactId>      <version>{package_version_to_target}</version></dependency><dependency>    <groupId>com.azure</groupId>    <artifactId>azure-identity</artifactId>    <version>{package_version_to_target}</version></dependency>

Include import directives

Then open your code file and add the necessaryimport directives. In this example, we add the following directives in theApp.java file:

import com.azure.core.credential.*;import com.azure.identity.*;import com.azure.storage.blob.*;import com.azure.storage.blob.models.*;import com.azure.storage.blob.specialized.*;import com.azure.storage.common.*;

Blob client library information:

com.azure.storage.blob: Contains the primary classes (client objects) that you can use to operate on the service, containers, and blobs.
com.azure.storage.blob.models: Contains utility classes, structures, and enumeration types.
com.azure.storage.blob.specialized: Contains classes that you can use to perform operations specific to a blob type (For example: append blobs).

Authorize access and connect to Blob Storage

To connect an app to Blob Storage, create an instance of theBlobServiceClient class. You can also use theBlobServiceAsyncClient class forasynchronous programming. This object is your starting point to interact with data resources at the storage account level. You can use it to operate on the storage account and its containers. You can also use the service client to create container clients or blob clients, depending on the resource you need to work with.

To learn more about creating and managing client objects, seeCreate and manage client objects that interact with data resources.

You can authorize aBlobServiceClient object by using a Microsoft Entra authorization token, an account access key, or a shared access signature (SAS). For optimal security, Microsoft recommends using Microsoft Entra ID with managed identities to authorize requests against blob data. For more information, seeAuthorize access to blobs using Microsoft Entra ID.

To authorize with Microsoft Entra ID, you'll need to use asecurity principal. Which type of security principal you need depends on where your app runs. Use the following table as a guide:

Where the app runs	Security principal	Guidance
Local machine (developing and testing)	Service principal	To learn how to register the app, set up a Microsoft Entra group, assign roles, and configure environment variables, seeAuthorize access using developer service principals.
Local machine (developing and testing)	User identity	To learn how to set up a Microsoft Entra group, assign roles, and sign in to Azure, seeAuthorize access using developer credentials.
Hosted in Azure	Managed identity	To learn how to enable managed identity and assign roles, seeAuthorize access from Azure-hosted apps using a managed identity.
Hosted outside of Azure (for example, on-premises apps)	Service principal	To learn how to register the app, assign roles, and configure environment variables, seeAuthorize access from on-premises apps using an application service principal

Authorize access using DefaultAzureCredential

An easy and secure way to authorize access and connect to Blob Storage is to obtain an OAuth token by creating aDefaultAzureCredential instance. You can then use that credential to create aBlobServiceClient object.

Make sure you have the correct dependencies in pom.xml and the necessary import directives, as described inSet up your project.

The following example usesBlobServiceClientBuilder to build aBlobServiceClient object usingDefaultAzureCredential, and shows how to create container and blob clients, if needed:

// Azure SDK client builders accept the credential as a parameter// TODO: Replace <storage-account-name> with your actual storage account nameBlobServiceClient blobServiceClient = new BlobServiceClientBuilder()        .endpoint("https://<storage-account-name>.blob.core.windows.net/")        .credential(new DefaultAzureCredentialBuilder().build())        .buildClient();// If needed, you can create a BlobContainerClient object from the BlobServiceClientBlobContainerClient containerClient = blobServiceClient        .getBlobContainerClient("<container-name>");// If needed, you can create a BlobClient object from the BlobContainerClientBlobClient blobClient = containerClient        .getBlobClient("<blob-name>");

UseBlobServiceClientBuilder to build aBlobServiceClient object using a SAS token:

public static BlobServiceClient GetBlobServiceClientSAS(String sasToken) {    // TODO: Replace <storage-account-name> with your actual storage account name    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()            .endpoint("https://<storage-account-name>.blob.core.windows.net/")            .sasToken(sasToken)            .buildClient();    return blobServiceClient;}

To learn more about generating and managing SAS tokens, see the following articles:

Note

For scenarios where shared access signatures (SAS) are used, Microsoft recommends using a user delegation SAS. A user delegation SAS is secured with Microsoft Entra credentials instead of the account key.

Create aStorageSharedKeyCredential by using the storage account name and account key. Then use that object to initialize aBlobServiceClient object.

public static BlobServiceClient GetBlobServiceClientAccountKey(String accountName, String accountKey) {    StorageSharedKeyCredential credential = new StorageSharedKeyCredential(accountName, accountKey);    // Azure SDK client builders accept the credential as a parameter    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()            .endpoint(String.format("https://%s.blob.core.windows.net/", accountName))            .credential(credential)            .buildClient();    return blobServiceClient;        }

You can also create aBlobServiceClient object using a connection string.

public static BlobServiceClient GetBlobServiceClientConnectionString(String connectionString) {    // Azure SDK client builders accept the credential as a parameter    // TODO: Replace <storage-account-name> with your actual storage account name    BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()            .endpoint("https://<storage-account-name>.blob.core.windows.net/")            .connectionString(connectionString)            .buildClient();    return blobServiceClient;        }

For information about how to obtain account keys and best practice guidelines for properly managing and safeguarding your keys, seeManage storage account access keys.

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.

Configure the JVM TTL for DNS name lookups

The Java Virtual Machine (JVM) caches responses from successful DNS name lookups for a specified period of time, known as time-to-live (TTL). The default TTL value for many JVMs is-1, which means that the JVM caches the response indefinitely, or until the JVM is restarted.

Because Azure resources use DNS name entries that can change, we recommend that you set the JVM TTL value to 10 seconds. This configuration ensures that an updated IP address for a resource is returned with the next DNS query.

To change the TTL value globally for all applications using the JVM, set thenetworkaddress.cache.ttl property in thejava.security file.

networkaddress.cache.ttl=10

For Java 8, thejava.security file is located in the$JAVA_HOME/jre/lib/security directory. For Java 11 and higher, the file is located in the$JAVA_HOME/conf/security directory.

Build your app

As you build apps to work with data resources in Azure Blob Storage, your code primarily interacts with three resource types: storage accounts, containers, and blobs. To learn more about these resource types, how they relate to one another, and how apps interact with resources, seeUnderstand how apps interact with Blob Storage data resources.

The following guides show you how to access data and perform specific actions using the Azure Storage client library for Java:

Guide	Description
Configure a retry policy	Implement retry policies for client operations.
Copy blobs	Copy a blob from one location to another.
Create a container	Create blob containers.
Create a user delegation SAS	Create a user delegation SAS for a container or blob.
Create and manage blob leases	Establish and manage a lock on a blob.
Create and manage container leases	Establish and manage a lock on a container.
Delete and restore blobs	Delete blobs, and if soft-delete is enabled, restore deleted blobs.
Delete and restore containers	Delete containers, and if soft-delete is enabled, restore deleted containers.
Download blobs	Download blobs by using strings, streams, and file paths.
Find blobs using tags	Set and retrieve tags as well as use tags to find blobs.
List blobs	List blobs in different ways.
List containers	List containers in an account and the various options available to customize a listing.
Manage properties and metadata (blobs)	Get and set properties and metadata for blobs.
Manage properties and metadata (containers)	Get and set properties and metadata for containers.
Performance tuning for data transfers	Optimize performance for data transfer operations.
Set or change a blob's access tier	Set or change the access tier for a block blob.
Upload blobs	Learn how to upload blobs by using strings, streams, file paths, and other methods.