BlobAsyncClient Class
- java.
lang. Object - com.
azure. storage. blob. specialized. BlobAsyncClientBase - com.
azure. storage. blob. BlobAsyncClient
- com.
- com.
public class BlobAsyncClient
extends BlobAsyncClientBase
This class provides a client that contains generic blob operations for Azure Storage Blobs. Operations allowed by the client are uploading and downloading, copying a blob, retrieving and setting metadata, retrieving and setting HTTP headers, and deleting and un-deleting a blob.
This client is instantiated through BlobClientBuilder or retrieved via getBlobAsyncClient(String blobName).
For operations on a specific blob type (i.e. append, block, or page) use getAppendBlobAsyncClient(), getBlockBlobAsyncClient(), or getPageBlobAsyncClient() to construct a client that allows blob specific operations.
Please refer to the Azure Docs for more information.
Field Summary
| Modifier and Type | Field and Description |
|---|---|
| static final int |
BLOB_DEFAULT_HTBB_UPLOAD_BLOCK_SIZE
If a blob is known to be greater than 100MB, using a larger block size will trigger some server-side optimizations. |
| static final int |
BLOB_DEFAULT_NUMBER_OF_BUFFERS
The number of buffers to use if none is specified on the buffered upload method. |
| static final int |
BLOB_DEFAULT_UPLOAD_BLOCK_SIZE
The block size to use if none is specified in parallel operations. |
Constructor Summary
Method Summary
Methods inherited from BlobAsyncClientBase
Methods inherited from java.lang.Object
Field Details
BLOB_DEFAULT_HTBB_UPLOAD_BLOCK_SIZE
public static final int BLOB_DEFAULT_HTBB_UPLOAD_BLOCK_SIZE
If a blob is known to be greater than 100MB, using a larger block size will trigger some server-side optimizations. If the block size is not set and the size of the blob is known to be greater than 100MB, this value will be used.
BLOB_DEFAULT_NUMBER_OF_BUFFERS
public static final int BLOB_DEFAULT_NUMBER_OF_BUFFERS
The number of buffers to use if none is specified on the buffered upload method.
BLOB_DEFAULT_UPLOAD_BLOCK_SIZE
public static final int BLOB_DEFAULT_UPLOAD_BLOCK_SIZE
The block size to use if none is specified in parallel operations.
Constructor Details
BlobAsyncClient
protected BlobAsyncClient(HttpPipeline pipeline, String url, BlobServiceVersion serviceVersion, String accountName, String containerName, String blobName, String snapshot, CpkInfo customerProvidedKey)
Protected constructor for use by BlobClientBuilder.
Parameters:
null to interact with the blob directly.
null to allow the service to use its own encryption.
BlobAsyncClient
protected BlobAsyncClient(HttpPipeline pipeline, String url, BlobServiceVersion serviceVersion, String accountName, String containerName, String blobName, String snapshot, CpkInfo customerProvidedKey, EncryptionScope encryptionScope)
Protected constructor for use by BlobClientBuilder.
Parameters:
null to interact with the blob directly.
null to allow the service to use its own encryption.
null to allow the service to use its own encryption.
BlobAsyncClient
protected BlobAsyncClient(HttpPipeline pipeline, String url, BlobServiceVersion serviceVersion, String accountName, String containerName, String blobName, String snapshot, CpkInfo customerProvidedKey, EncryptionScope encryptionScope, String versionId)
Protected constructor for use by BlobClientBuilder.
Parameters:
null to interact with the blob directly.
null to allow the service to use its own encryption.
null to allow the service to use its own encryption.
null to interact with the latest blob version.
Method Details
getAppendBlobAsyncClient
public AppendBlobAsyncClient getAppendBlobAsyncClient()
Creates a new AppendBlobAsyncClient associated with this blob.
Returns:
getBlockBlobAsyncClient
public BlockBlobAsyncClient getBlockBlobAsyncClient()
Creates a new BlockBlobAsyncClient associated with this blob.
Returns:
getCustomerProvidedKeyAsyncClient
public BlobAsyncClient getCustomerProvidedKeyAsyncClient(CustomerProvidedKey customerProvidedKey)
Creates a new BlobAsyncClient with the specified customerProvidedKey.
Overrides:
BlobAsyncClient.getCustomerProvidedKeyAsyncClient(CustomerProvidedKey customerProvidedKey)Parameters:
null to use no customer provided key.
Returns:
customerProvidedKey.getEncryptionScopeAsyncClient
public BlobAsyncClient getEncryptionScopeAsyncClient(String encryptionScope)
Creates a new BlobAsyncClient with the specified encryptionScope.
Overrides:
BlobAsyncClient.getEncryptionScopeAsyncClient(String encryptionScope)Parameters:
null to use no encryption scope.
Returns:
encryptionScope.getPageBlobAsyncClient
public PageBlobAsyncClient getPageBlobAsyncClient()
Creates a new PageBlobAsyncClient associated with this blob.
Returns:
getSnapshotClient
public BlobAsyncClient getSnapshotClient(String snapshot)
Creates a new BlobAsyncClient linked to the snapshot of this blob resource.
Overrides:
BlobAsyncClient.getSnapshotClient(String snapshot)Parameters:
Returns:
getVersionClient
public BlobAsyncClient getVersionClient(String versionId)
Creates a new BlobAsyncClient linked to the versionId of this blob resource.
Overrides:
BlobAsyncClient.getVersionClient(String versionId)Parameters:
null to interact with the latest blob version.
Returns:
upload
public Mono
Creates a new block blob. By default, this method will not overwrite an existing blob.
Code Samples
client.upload(BinaryData.fromString("Data!")).subscribe(response ->
System.out.printf("Uploaded BlockBlob MD5 is %s%n",
Base64.getEncoder().encodeToString(response.getContentMd5())));
Parameters:
Returns:
upload
public Mono
Creates a new block blob, or updates the content of an existing block blob.
Code Samples
boolean overwrite = false; // Default behavior
client.upload(BinaryData.fromString("Data!"), overwrite).subscribe(response ->
System.out.printf("Uploaded BlockBlob MD5 is %s%n",
Base64.getEncoder().encodeToString(response.getContentMd5())));
Parameters:
Returns:
upload
public Mono
Creates a new block blob. By default, this method will not overwrite an existing blob.
Updating an existing block blob overwrites any existing metadata on the blob. Partial updates are not supported with this method; the content of the existing blob is overwritten with the new content. To perform a partial update of a block blob's, use stageBlock(String base64BlockId, Flux<ByteBuffer> data, long length) and commitBlockList(List<String> base64BlockIds). For more information, see the Azure Docs for Put Block and the Azure Docs for Put Block List.
The data passed need not support multiple subscriptions/be replayable as is required in other upload methods when retries are enabled, and the length of the data need not be known in advance. Therefore, this method does support uploading any arbitrary data source, including network streams. This behavior is possible because this method will perform some internal buffering as configured by the blockSize and numBuffers parameters, so while this method may offer additional convenience, it will not be as performant as other options, which should be preferred when possible.
Typically, the greater the number of buffers used, the greater the possible parallelism when transferring the data. Larger buffers means we will have to stage fewer blocks and therefore require fewer IO operations. The trade-offs between these values are context-dependent, so some experimentation may be required to optimize inputs for a given scenario.
Code Samples
ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
.setBlockSizeLong(blockSize)
.setMaxConcurrency(maxConcurrency);
client.upload(data, parallelTransferOptions).subscribe(response ->
System.out.printf("Uploaded BlockBlob MD5 is %s%n",
Base64.getEncoder().encodeToString(response.getContentMd5())));
Parameters:
Flux be replayable. In other words, it does not have to support multiple subscribers and is not expected
to produce the same values across subscriptions.
Returns:
upload
public Mono
Creates a new block blob, or updates the content of an existing block blob.
Updating an existing block blob overwrites any existing metadata on the blob. Partial updates are not supported with this method; the content of the existing blob is overwritten with the new content. To perform a partial update of a block blob's, use stageBlock(String base64BlockId, Flux<ByteBuffer> data, long length) and commitBlockList(List<String> base64BlockIds). For more information, see the Azure Docs for Put Block and the Azure Docs for Put Block List.
The data passed need not support multiple subscriptions/be replayable as is required in other upload methods when retries are enabled, and the length of the data need not be known in advance. Therefore, this method does support uploading any arbitrary data source, including network streams. This behavior is possible because this method will perform some internal buffering as configured by the blockSize and numBuffers parameters, so while this method may offer additional convenience, it will not be as performant as other options, which should be preferred when possible.
Typically, the greater the number of buffers used, the greater the possible parallelism when transferring the data. Larger buffers means we will have to stage fewer blocks and therefore require fewer IO operations. The trade-offs between these values are context-dependent, so some experimentation may be required to optimize inputs for a given scenario.
Code Samples
ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
.setBlockSizeLong(blockSize)
.setMaxConcurrency(maxConcurrency);
boolean overwrite = false; // Default behavior
client.upload(data, parallelTransferOptions, overwrite).subscribe(response ->
System.out.printf("Uploaded BlockBlob MD5 is %s%n",
Base64.getEncoder().encodeToString(response.getContentMd5())));
Parameters:
Flux be replayable. In other words, it does not have to support multiple subscribers and is not expected
to produce the same values across subscriptions.
Returns:
uploadFileResourceSupplier
@Deprecated
protected AsynchronousFileChannel uploadFileResourceSupplier(String filePath)
Deprecated
RESERVED FOR INTERNAL USE. Resource Supplier for UploadFile.
Parameters:
Returns:
AsynchronousFileChanneluploadFromFile
public Mono
Creates a new block blob with the content of the specified file. By default, this method will not overwrite an existing blob.
Code Samples
client.uploadFromFile(filePath)
.doOnError(throwable -> System.err.printf("Failed to upload from file %s%n", throwable.getMessage()))
.subscribe(completion -> System.out.println("Upload from file succeeded"));
Parameters:
Returns:
uploadFromFile
public Mono
Creates a new block blob, or updates the content of an existing block blob, with the content of the specified file.
Code Samples
boolean overwrite = false; // Default behavior
client.uploadFromFile(filePath, overwrite)
.doOnError(throwable -> System.err.printf("Failed to upload from file %s%n", throwable.getMessage()))
.subscribe(completion -> System.out.println("Upload from file succeeded"));
Parameters:
Returns:
uploadFromFile
public Mono
Creates a new block blob, or updates the content of an existing block blob, with the content of the specified file.
To avoid overwriting, pass "*" to setIfNoneMatch(String ifNoneMatch).
Code Samples
BlobHttpHeaders headers = new BlobHttpHeaders()
.setContentMd5("data".getBytes(StandardCharsets.UTF_8))
.setContentLanguage("en-US")
.setContentType("binary");
Map<String, String> metadata = Collections.singletonMap("metadata", "value");
BlobRequestConditions requestConditions = new BlobRequestConditions()
.setLeaseId(leaseId)
.setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
client.uploadFromFile(filePath,
new ParallelTransferOptions().setBlockSizeLong(BlockBlobClient.MAX_STAGE_BLOCK_BYTES_LONG),
headers, metadata, AccessTier.HOT, requestConditions)
.doOnError(throwable -> System.err.printf("Failed to upload from file %s%n", throwable.getMessage()))
.subscribe(completion -> System.out.println("Upload from file succeeded"));
Parameters:
Returns:
uploadFromFileWithResponse
public Mono<>
Creates a new block blob, or updates the content of an existing block blob, with the content of the specified file.
To avoid overwriting, pass "*" to setIfNoneMatch(String ifNoneMatch).
Code Samples
BlobHttpHeaders headers = new BlobHttpHeaders()
.setContentMd5("data".getBytes(StandardCharsets.UTF_8))
.setContentLanguage("en-US")
.setContentType("binary");
Map<String, String> metadata = Collections.singletonMap("metadata", "value");
Map<String, String> tags = Collections.singletonMap("tag", "value");
BlobRequestConditions requestConditions = new BlobRequestConditions()
.setLeaseId(leaseId)
.setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
client.uploadFromFileWithResponse(new BlobUploadFromFileOptions(filePath)
.setParallelTransferOptions(
new ParallelTransferOptions().setBlockSizeLong(BlobAsyncClient.BLOB_MAX_UPLOAD_BLOCK_SIZE))
.setHeaders(headers).setMetadata(metadata).setTags(tags).setTier(AccessTier.HOT)
.setRequestConditions(requestConditions))
.doOnError(throwable -> System.err.printf("Failed to upload from file %s%n", throwable.getMessage()))
.subscribe(completion -> System.out.println("Upload from file succeeded"));
Parameters:
Returns:
uploadWithResponse
public Mono<>
Creates a new block blob, or updates the content of an existing block blob.
Updating an existing block blob overwrites any existing metadata on the blob. Partial updates are not supported with this method; the content of the existing blob is overwritten with the new content. To perform a partial update of a block blob's, use stageBlock(String base64BlockId, Flux<ByteBuffer> data, long length) and commitBlockList(List<String> base64BlockIds). For more information, see the Azure Docs for Put Block and the Azure Docs for Put Block List.
The data passed need not support multiple subscriptions/be replayable as is required in other upload methods when retries are enabled, and the length of the data need not be known in advance. Therefore, this method does support uploading any arbitrary data source, including network streams. This behavior is possible because this method will perform some internal buffering as configured by the blockSize and numBuffers parameters, so while this method may offer additional convenience, it will not be as performant as other options, which should be preferred when possible.
Typically, the greater the number of buffers used, the greater the possible parallelism when transferring the data. Larger buffers means we will have to stage fewer blocks and therefore require fewer IO operations. The trade-offs between these values are context-dependent, so some experimentation may be required to optimize inputs for a given scenario.
To avoid overwriting, pass "*" to setIfNoneMatch(String ifNoneMatch).
Code Samples
BlobHttpHeaders headers = new BlobHttpHeaders()
.setContentMd5("data".getBytes(StandardCharsets.UTF_8))
.setContentLanguage("en-US")
.setContentType("binary");
Map<String, String> metadata = Collections.singletonMap("metadata", "value");
Map<String, String> tags = Collections.singletonMap("tag", "value");
BlobRequestConditions requestConditions = new BlobRequestConditions()
.setLeaseId(leaseId)
.setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions().setBlockSizeLong(blockSize)
.setMaxConcurrency(maxConcurrency).setProgressListener(bytesTransferred ->
System.out.printf("Upload progress: %s bytes sent", bytesTransferred));
client.uploadWithResponse(new BlobParallelUploadOptions(data)
.setParallelTransferOptions(parallelTransferOptions).setHeaders(headers).setMetadata(metadata).setTags(tags)
.setTier(AccessTier.HOT).setRequestConditions(requestConditions))
.subscribe(response -> System.out.printf("Uploaded BlockBlob MD5 is %s%n",
Base64.getEncoder().encodeToString(response.getValue().getContentMd5())));
Using Progress Reporting
BlobHttpHeaders headers = new BlobHttpHeaders()
.setContentMd5("data".getBytes(StandardCharsets.UTF_8))
.setContentLanguage("en-US")
.setContentType("binary");
Map<String, String> metadata = Collections.singletonMap("metadata", "value");
Map<String, String> tags = Collections.singletonMap("tag", "value");
BlobRequestConditions requestConditions = new BlobRequestConditions()
.setLeaseId(leaseId)
.setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions().setBlockSizeLong(blockSize)
.setMaxConcurrency(maxConcurrency).setProgressListener(bytesTransferred ->
System.out.printf("Upload progress: %s bytes sent", bytesTransferred));
client.uploadWithResponse(new BlobParallelUploadOptions(data)
.setParallelTransferOptions(parallelTransferOptions).setHeaders(headers).setMetadata(metadata).setTags(tags)
.setTier(AccessTier.HOT).setRequestConditions(requestConditions))
.subscribe(response -> System.out.printf("Uploaded BlockBlob MD5 is %s%n",
Base64.getEncoder().encodeToString(response.getValue().getContentMd5())));
Parameters:
Flux be replayable. In other words, it does not have to support multiple subscribers and is not
expected to produce the same values across subscriptions.
Returns:
uploadWithResponse
public Mono<>
Creates a new block blob, or updates the content of an existing block blob.
Updating an existing block blob overwrites any existing metadata on the blob. Partial updates are not supported with this method; the content of the existing blob is overwritten with the new content. To perform a partial update of a block blob's, use stageBlock(String base64BlockId, Flux<ByteBuffer> data, long length) and commitBlockList(List<String> base64BlockIds). For more information, see the Azure Docs for Put Block and the Azure Docs for Put Block List.
The data passed need not support multiple subscriptions/be replayable as is required in other upload methods when retries are enabled, and the length of the data need not be known in advance. Therefore, this method does support uploading any arbitrary data source, including network streams. This behavior is possible because this method will perform some internal buffering as configured by the blockSize and numBuffers parameters, so while this method may offer additional convenience, it will not be as performant as other options, which should be preferred when possible.
Typically, the greater the number of buffers used, the greater the possible parallelism when transferring the data. Larger buffers means we will have to stage fewer blocks and therefore require fewer IO operations. The trade-offs between these values are context-dependent, so some experimentation may be required to optimize inputs for a given scenario.
To avoid overwriting, pass "*" to setIfNoneMatch(String ifNoneMatch).
Code Samples
BlobHttpHeaders headers = new BlobHttpHeaders()
.setContentMd5("data".getBytes(StandardCharsets.UTF_8))
.setContentLanguage("en-US")
.setContentType("binary");
Map<String, String> metadata = Collections.singletonMap("metadata", "value");
BlobRequestConditions requestConditions = new BlobRequestConditions()
.setLeaseId(leaseId)
.setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
.setBlockSizeLong(blockSize)
.setMaxConcurrency(maxConcurrency);
client.uploadWithResponse(data, parallelTransferOptions, headers, metadata, AccessTier.HOT, requestConditions)
.subscribe(response -> System.out.printf("Uploaded BlockBlob MD5 is %s%n",
Base64.getEncoder().encodeToString(response.getValue().getContentMd5())));
Using Progress Reporting
BlobHttpHeaders headers = new BlobHttpHeaders()
.setContentMd5("data".getBytes(StandardCharsets.UTF_8))
.setContentLanguage("en-US")
.setContentType("binary");
Map<String, String> metadata = Collections.singletonMap("metadata", "value");
BlobRequestConditions requestConditions = new BlobRequestConditions()
.setLeaseId(leaseId)
.setIfUnmodifiedSince(OffsetDateTime.now().minusDays(3));
ParallelTransferOptions parallelTransferOptions = new ParallelTransferOptions()
.setBlockSizeLong(blockSize)
.setMaxConcurrency(maxConcurrency)
.setProgressListener(bytesTransferred -> System.out.printf("Upload progress: %s bytes sent", bytesTransferred));
client.uploadWithResponse(data, parallelTransferOptions, headers, metadata, AccessTier.HOT, requestConditions)
.subscribe(response -> System.out.printf("Uploaded BlockBlob MD5 is %s%n",
Base64.getEncoder().encodeToString(response.getValue().getContentMd5())));
Parameters:
Flux be replayable. In other words, it does not have to support multiple subscribers and is not expected
to produce the same values across subscriptions.
Returns:
Applies to
Azure SDK for Java
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for