CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-azure--azure-storage-blob

Microsoft Azure client library for Blob Storage - Azure Blob Storage is Microsoft's object storage solution for the cloud, optimized for storing massive amounts of unstructured data such as text or binary data.

—

Pending
Overview
Eval results
Files

service-client.mddocs/

Service Client Operations

Service clients provide the entry point for Azure Blob Storage operations, handling authentication, service-level configuration, and container management.

BlobServiceClient

The synchronous client for Azure Blob Storage service operations.

Creating a Service Client

import com.azure.storage.blob.BlobServiceClient;
import com.azure.storage.blob.BlobServiceClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.storage.common.StorageSharedKeyCredential;

// Using connection string (development/testing)
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .connectionString("DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net")
    .buildClient();

// Using Azure Identity (production recommended)
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .endpoint("https://myaccount.blob.core.windows.net")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

// Using shared key credential
StorageSharedKeyCredential credential = new StorageSharedKeyCredential("myaccount", "mykey");
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .endpoint("https://myaccount.blob.core.windows.net")
    .credential(credential)
    .buildClient();

// Using SAS token
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .endpoint("https://myaccount.blob.core.windows.net")
    .sasToken("sv=2023-11-03&ss=b&srt=sco&sp=rwdlacupx&se=2024-01-01T00:00:00Z&st=2023-12-01T00:00:00Z&spr=https&sig=signature")
    .buildClient();

Container Management

import com.azure.storage.blob.models.*;
import com.azure.core.http.rest.PagedIterable;
import com.azure.core.http.rest.Response;
import com.azure.core.util.Context;

// Create container
BlobContainerClient containerClient = serviceClient.createBlobContainer("mycontainer");

// Create container with options
Map<String, String> metadata = Map.of(
    "environment", "production",
    "team", "backend"
);
Response<BlobContainerClient> response = serviceClient.createBlobContainerWithResponse(
    "mycontainer",
    metadata,
    PublicAccessType.BLOB,
    Context.NONE
);

// Create container if not exists
BlobContainerClient containerClient = serviceClient.createBlobContainerIfNotExists("mycontainer");

// Get existing container client
BlobContainerClient containerClient = serviceClient.getBlobContainerClient("mycontainer");

// Delete container
serviceClient.deleteBlobContainer("mycontainer");

// Delete container if exists
boolean deleted = serviceClient.deleteBlobContainerIfExists("mycontainer");

// Undelete container (if soft delete is enabled)
BlobContainerClient restoredContainer = serviceClient.undeleteBlobContainer(
    "mycontainer", 
    "01D64EAD4C6B7A00"  // deletion version
);

Listing Containers

import com.azure.storage.blob.models.ListBlobContainersOptions;
import java.time.Duration;

// List all containers
PagedIterable<BlobContainerItem> containers = serviceClient.listBlobContainers();
for (BlobContainerItem container : containers) {
    System.out.println("Container: " + container.getName());
    System.out.println("Last Modified: " + container.getProperties().getLastModified());
    System.out.println("Public Access: " + container.getProperties().getPublicAccess());
}

// List containers with filtering and options
ListBlobContainersOptions options = new ListBlobContainersOptions()
    .setPrefix("test-")
    .setDetails(new BlobContainerListDetails()
        .setRetrieveDeleted(true)
        .setRetrieveMetadata(true))
    .setMaxResultsPerPage(50);

PagedIterable<BlobContainerItem> filteredContainers = serviceClient.listBlobContainers(
    options, 
    Duration.ofSeconds(30)
);

for (BlobContainerItem container : filteredContainers) {
    System.out.println("Container: " + container.getName());
    System.out.println("Metadata: " + container.getMetadata());
    System.out.println("Deleted: " + container.isDeleted());
}

Service Properties

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

// Get service properties
BlobServiceProperties properties = serviceClient.getProperties();
System.out.println("Default service version: " + properties.getDefaultServiceVersion());
System.out.println("Hour metrics enabled: " + properties.getHourMetrics().isEnabled());

// Configure service properties
BlobServiceProperties newProperties = new BlobServiceProperties();

// Configure logging
BlobAnalyticsLogging logging = new BlobAnalyticsLogging()
    .setVersion("1.0")
    .setDeleteEnabled(true)
    .setReadEnabled(true)
    .setWriteEnabled(true)
    .setRetentionPolicy(new BlobRetentionPolicy()
        .setEnabled(true)
        .setDays(30));
newProperties.setLogging(logging);

// Configure metrics
BlobMetrics hourMetrics = new BlobMetrics()
    .setVersion("1.0")
    .setEnabled(true)
    .setIncludeApis(true)
    .setRetentionPolicy(new BlobRetentionPolicy()
        .setEnabled(true)
        .setDays(7));
newProperties.setHourMetrics(hourMetrics);

// Configure CORS
List<BlobCorsRule> corsRules = List.of(
    new BlobCorsRule()
        .setAllowedOrigins("https://example.com")
        .setAllowedMethods("GET,PUT,POST")
        .setAllowedHeaders("x-ms-*,content-type")
        .setExposedHeaders("x-ms-*")
        .setMaxAgeInSeconds(3600)
);
newProperties.setCors(corsRules);

// Configure static website
BlobStaticWebsite staticWebsite = new BlobStaticWebsite()
    .setEnabled(true)
    .setIndexDocument("index.html")
    .setErrorDocument404Path("error.html");
newProperties.setStaticWebsite(staticWebsite);

// Apply properties
serviceClient.setProperties(newProperties);

Account Information

// Get account information
StorageAccountInfo accountInfo = serviceClient.getAccountInfo();
System.out.println("Account kind: " + accountInfo.getAccountKind());
System.out.println("SKU name: " + accountInfo.getSkuName());
System.out.println("Hierarchical namespace: " + accountInfo.isHierarchicalNamespaceEnabled());

// Get service statistics (geo-replication info)
BlobServiceStatistics stats = serviceClient.getStatistics();
if (stats.getGeoReplication() != null) {
    System.out.println("Geo-replication status: " + stats.getGeoReplication().getStatus());
    System.out.println("Last sync time: " + stats.getGeoReplication().getLastSyncTime());
}

Finding Blobs by Tags

// Find blobs across all containers using tag queries
String tagQuery = "environment='production' AND team='backend'";
PagedIterable<TaggedBlobItem> taggedBlobs = serviceClient.findBlobsByTags(tagQuery);

for (TaggedBlobItem taggedBlob : taggedBlobs) {
    System.out.println("Blob: " + taggedBlob.getName());
    System.out.println("Container: " + taggedBlob.getContainerName());
    System.out.println("Tags: " + taggedBlob.getTags().toMap());
}

// Find with pagination
FindBlobsOptions findOptions = new FindBlobsOptions(tagQuery)
    .setMaxResultsPerPage(100);
    
PagedIterable<TaggedBlobItem> pagedResults = serviceClient.findBlobsByTags(findOptions, Duration.ofMinutes(1));

User Delegation Keys

import java.time.OffsetDateTime;

// Get user delegation key for SAS generation (Azure AD authentication only)
OffsetDateTime keyStart = OffsetDateTime.now();
OffsetDateTime keyExpiry = keyStart.plusDays(7);

try {
    UserDelegationKey userDelegationKey = serviceClient.getUserDelegationKey(keyStart, keyExpiry);
    
    System.out.println("Delegation key acquired");
    System.out.println("Signed object ID: " + userDelegationKey.getSignedObjectId());
    System.out.println("Valid until: " + userDelegationKey.getSignedExpiry());
    
    // Use the key to generate SAS tokens
    // (See security documentation for SAS generation details)
    
} catch (Exception ex) {
    System.err.println("Failed to get user delegation key: " + ex.getMessage());
}

Account SAS Generation

import com.azure.storage.common.sas.*;
import java.time.OffsetDateTime;

// Generate account-level SAS token
OffsetDateTime expiryTime = OffsetDateTime.now().plusHours(24);

AccountSasSignatureValues accountSasValues = new AccountSasSignatureValues(
    expiryTime,
    AccountSasPermission.parse("rwdlacup"), // permissions
    AccountSasService.parse("b"),           // blob service
    AccountSasResourceType.parse("sco")     // service, container, object
)
.setStartTime(OffsetDateTime.now())
.setProtocol(SasProtocol.HTTPS_ONLY)
.setSasIpRange(SasIpRange.parse("168.1.5.60-168.1.5.70"));

String accountSas = serviceClient.generateAccountSas(accountSasValues);
System.out.println("Account SAS: " + accountSas);

BlobServiceAsyncClient

The asynchronous client for Azure Blob Storage service operations using reactive programming.

Creating an Async Service Client

import com.azure.storage.blob.BlobServiceAsyncClient;
import reactor.core.publisher.Mono;
import reactor.core.publisher.Flux;

// Create async client
BlobServiceAsyncClient asyncServiceClient = new BlobServiceClientBuilder()
    .connectionString("DefaultEndpointsProtocol=https;AccountName=myaccount;...")
    .buildAsyncClient();

// All operations return Mono<T> or Flux<T>

Async Container Operations

// Create container asynchronously
Mono<BlobContainerAsyncClient> containerMono = asyncServiceClient.createBlobContainer("mycontainer");

// Chain operations
containerMono
    .flatMap(container -> container.create())
    .doOnSuccess(response -> System.out.println("Container created"))
    .doOnError(error -> System.err.println("Creation failed: " + error.getMessage()))
    .subscribe();

// List containers asynchronously
Flux<BlobContainerItem> containerFlux = asyncServiceClient.listBlobContainers();
containerFlux
    .take(10) // Limit to first 10 containers
    .doOnNext(container -> System.out.println("Container: " + container.getName()))
    .doOnComplete(() -> System.out.println("Listing complete"))
    .subscribe();

Async Service Configuration

// Get properties asynchronously
Mono<BlobServiceProperties> propertiesMono = asyncServiceClient.getProperties();

propertiesMono
    .doOnNext(props -> {
        System.out.println("Default version: " + props.getDefaultServiceVersion());
        System.out.println("Static website enabled: " + 
            (props.getStaticWebsite() != null && props.getStaticWebsite().isEnabled()));
    })
    .subscribe();

// Update properties
BlobServiceProperties newProps = new BlobServiceProperties()
    .setDefaultServiceVersion("2023-11-03");

Mono<Void> updateMono = asyncServiceClient.setProperties(newProps);
updateMono
    .doOnSuccess(v -> System.out.println("Properties updated"))
    .doOnError(ex -> System.err.println("Update failed: " + ex.getMessage()))
    .subscribe();

Error Handling with Async Client

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

// Handle errors in reactive chains
asyncServiceClient.createBlobContainer("invalid/container/name")
    .doOnSuccess(container -> System.out.println("Container created"))
    .onErrorResume(BlobStorageException.class, ex -> {
        System.err.println("Storage error: " + ex.getErrorCode());
        System.err.println("Status: " + ex.getStatusCode());
        return Mono.empty(); // Continue with empty result
    })
    .onErrorResume(Exception.class, ex -> {
        System.err.println("General error: " + ex.getMessage());
        return Mono.error(ex); // Re-throw other exceptions
    })
    .subscribe();

// Blocking operations (use sparingly)
try {
    BlobContainerAsyncClient container = asyncServiceClient
        .createBlobContainer("mycontainer")
        .block(Duration.ofSeconds(30));
    System.out.println("Container created: " + container.getBlobContainerName());
} catch (Exception ex) {
    System.err.println("Operation failed: " + ex.getMessage());
}

Client Configuration

Custom HTTP Configuration

import com.azure.core.http.HttpClient;
import com.azure.core.http.netty.NettyAsyncHttpClientBuilder;
import com.azure.core.http.policy.*;
import java.time.Duration;

// Configure HTTP client
HttpClient httpClient = new NettyAsyncHttpClientBuilder()
    .connectionTimeout(Duration.ofSeconds(60))
    .responseTimeout(Duration.ofSeconds(120))
    .maxIdleTime(Duration.ofSeconds(60))
    .build();

// Configure retry policy
RetryPolicy retryPolicy = new RetryPolicy("fixed", 3);

// Build service client with custom configuration
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .endpoint("https://myaccount.blob.core.windows.net")
    .credential(new DefaultAzureCredentialBuilder().build())
    .httpClient(httpClient)
    .retryPolicy(retryPolicy)
    .addPolicy(new UserAgentPolicy("MyApp/1.0"))
    .serviceVersion(BlobServiceVersion.V2023_11_03)
    .buildClient();

Customer-Provided Encryption

import com.azure.storage.blob.models.CustomerProvidedKey;
import com.azure.storage.blob.models.EncryptionAlgorithmType;

// Configure customer-provided encryption key
CustomerProvidedKey cpk = new CustomerProvidedKey("myEncryptionKey")
    .setEncryptionAlgorithm(EncryptionAlgorithmType.AES256);

BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .connectionString("DefaultEndpointsProtocol=https;AccountName=myaccount;...")
    .customerProvidedKey(cpk)
    .buildClient();

// All operations will use the provided encryption key

Encryption Scope

// Configure encryption scope
BlobServiceClient serviceClient = new BlobServiceClientBuilder()
    .connectionString("DefaultEndpointsProtocol=https;AccountName=myaccount;...")
    .encryptionScope("myencryptionscope")
    .buildClient();

// All blobs created through this client will use the encryption scope

Service Client Properties

Key Properties

// Get service client properties
String accountUrl = serviceClient.getAccountUrl();
String accountName = serviceClient.getAccountName();
BlobServiceVersion serviceVersion = serviceClient.getServiceVersion();

System.out.println("Account URL: " + accountUrl);
System.out.println("Account Name: " + accountName);
System.out.println("Service Version: " + serviceVersion.getVersion());

// Access HTTP pipeline for advanced scenarios
HttpPipeline pipeline = serviceClient.getHttpPipeline();

Constants

// Important service-level constants
public static final String ROOT_CONTAINER_NAME = "$root";
public static final String STATIC_WEBSITE_CONTAINER_NAME = "$web";
public static final String LOG_CONTAINER_NAME = "$logs";

// Use these for special containers
BlobContainerClient rootContainer = serviceClient.getBlobContainerClient(BlobContainerClient.ROOT_CONTAINER_NAME);
BlobContainerClient webContainer = serviceClient.getBlobContainerClient(BlobContainerClient.STATIC_WEBSITE_CONTAINER_NAME);

Related Documentation

  • ← Back to Overview
  • Container Management →
  • Blob Operations →
  • Security & Authentication →
  • Configuration Options →

Install with Tessl CLI

npx tessl i tessl/maven-com-azure--azure-storage-blob

docs

blob-client.md

container-client.md

index.md

models.md

options.md

security.md

service-client.md

specialized-clients.md

streaming.md

tile.json