Use blob index tags to manage and find data with Java

  • Article

This article shows how to use blob index tags to manage and find data using the Azure Storage client library for Java.

Prerequisites

Set up your environment

If you don't have an existing project, this section shows you how to set up a project to work with the Azure Blob Storage client library for Java. For more information, see Get started with Azure Blob Storage and Java.

To work with the code examples in this article, follow these steps to set up your project.

Note

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

Install packages

Open the pom.xml file in your text editor. Install the packages by including the BOM file, or including a direct dependency.

Add import statements

Add the following import statements:

import com.azure.storage.blob.*;
import com.azure.storage.blob.models.*;

import java.util.*;

Authorization

The authorization mechanism must have the necessary permissions to work with blob index tags. For authorization with Microsoft Entra ID (recommended), you need Azure RBAC built-in role Storage Blob Data Owner or higher. To learn more, see the authorization guidance for Get Blob Tags (REST API), Set Blob Tags (REST API), or Find Blobs by Tags (REST API).

Create a client object

To connect an app to Blob Storage, create an instance of BlobServiceClient.

The following example uses BlobServiceClientBuilder to build a BlobServiceClient object using DefaultAzureCredential, 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 name
BlobServiceClient blobServiceClient = new BlobServiceClientBuilder()
        .endpoint("https://<storage-account-name>.blob.core.chinacloudapi.cn/")
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

// If needed, you can create a BlobContainerClient object from the BlobServiceClient
BlobContainerClient containerClient = blobServiceClient
        .getBlobContainerClient("<container-name>");

// If needed, you can create a BlobClient object from the BlobContainerClient
BlobClient blobClient = containerClient
        .getBlobClient("<blob-name>");

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

About blob index tags

Blob index tags categorize data in your storage account using key-value tag attributes. These tags are automatically indexed and exposed as a searchable multi-dimensional index to easily find data. This article shows you how to set, get, and find data using blob index tags.

Blob index tags aren't supported for storage accounts with hierarchical namespace enabled. To learn more about the blob index tag feature along with known issues and limitations, see Manage and find Azure Blob data with blob index tags.

Set tags

You can set index tags if your code has authorized access to blob data through one of the following mechanisms:

For more information, see Setting blob index tags.

You can set tags by using the following method:

The specified tags in this method will replace existing tags. If old values must be preserved, they must be downloaded and included in the call to this method. The following example shows how to set tags:

public void setBlobTags(BlobClient blobClient) {
    // Get any existing tags for the blob if they need to be preserved
    Map<String, String> tags = blobClient.getTags();

    // Add or modify tags
    tags.put("Sealed", "false");
    tags.put("Content", "image");
    tags.put("Date", "2022-01-01");

    // setTags will replace existing tags with the map entries we pass in
    blobClient.setTags(tags);
}

You can delete all tags by passing an empty Map object into the setTags method:

public void clearBlobTags(BlobClient blobClient) {
    Map<String, String> tags = new HashMap<String, String>();
    blobClient.setTags(tags);
}

Get tags

You can get index tags if your code has authorized access to blob data through one of the following mechanisms:

For more information, see Getting and listing blob index tags.

You can get tags by using the following method:

The following example shows how to retrieve and iterate over the blob's tags:

public void getBlobTags(BlobClient blobClient) {
    Map<String, String> tags = blobClient.getTags();

    System.out.println("Blob tags:");
    for (Map.Entry<String, String> entry : tags.entrySet())
        System.out.println("Key = " + entry.getKey() + ", Value = " + entry.getValue());
}

Filter and find data with blob index tags

You can use index tags to find and filter data if your code has authorized access to blob data through one of the following mechanisms:

For more information, see Finding data using blob index tags.

Note

You can't use index tags to retrieve previous versions. Tags for previous versions aren't passed to the blob index engine. For more information, see Conditions and known issues.

You can find data by using the following method:

The following example finds all blobs tagged as an image:

public void findBlobsByTag(BlobContainerClient blobContainerClient) {
    String query = "\"Content\"='image'";

    blobContainerClient.findBlobsByTags(query)
            .forEach(blob -> System.out.printf("Name: %s%n", blob.getName()));
}

Resources

To learn more about how to use index tags to manage and find data using the Azure Blob Storage client library for Java, see the following resources.

Code samples

REST API operations

The Azure SDK for Java contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar Java paradigms. The client library methods for managing and using blob index tags use the following REST API operations:

Client library resources

See also

Related content

  • This article is part of the Blob Storage developer guide for Java. To learn more, see the full list of developer guide articles at Build your Java app.