-
Notifications
You must be signed in to change notification settings - Fork 0
Storage Blob Service SDK Migration Guide from 10.x to 12.x
In this section, we list main changes you need to be aware of when converting your Storage Blob SDK library from Version 10 to Version 12.
Java Development Kit (JDK) with version 8 or above
The biggest payoff here is the switch to Reactor and ReactorNetty. Both Reactor and Reactor-Netty are much more mature than the ReactiveX + custom-ReactiveX-Netty-interface we were using. Both Reactor and ReactorNetty are maintained by Spring and support other large projects, making them safer and more modern, while similar to what was present in v10. For more info, please refer Reactor Project
Perf increases over purely synchronous HTTP Clients (e.g. OkHttp). In our long running stress tests, we have observed 3x better performance using Reactor-Netty over OkHttp when using our sync apis. The async apis perform even better. Stress tests result. (placeholder)
Class name in V10:
ServiceURL
ContainerURL
BlobURL
BlockBlobURL
AppendBlobURL
PageBlobURL
Sync Class name in V12:
BlobServiceClient
ContainerClient
BlobClient
BlockBlobClient
AppendBlobClient
PageBlobClient
Async Class name in V12:
BlobServiceAsyncClient
ContainerAsyncClient
BlobAsyncClient
BlockBlobAsyncClient
AppendBlobAsyncClient
PageBlobAsyncClient
Each type (Container, Blob, etc.) has both a sync and async client. It is easy and intuitive to use whichever one is preferable in a given context without having to bother about clutter from the other.
- Example of using Async API in V12. (Suppose the
containerClienthas
been initialized. Please refer the Build Client section.)
Mono<Response<BlobProperties>> response = containerClient.getProperties();
- Example of usingSync API in V12
BlobProperties blobProperties = containerClient.getProperties();
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-storage-blob</artifactId>
<version>12.0.0-preview.2</version>
</dependency>
There are 3 ways of authenticating the client.
In V12, we allow to build connection string through the builder.
BlockBlobClient client = new BlobClientBuilder()
.connectionstring("${connectionstring}").buildBlockBlobClient();
You can build the SAS token through the client builder endpoint
. Adds the sasToken from portal at the end of the endpoint. Refer the documentation for more info.
e.g.
https://${accountName}.blob.core.windows.net/?${sasToken}
The other way to do that is to use the generateSASToken
API
String identifier = "identifier";
FileSASPermission permissions = new FileSASPermission()
.read(true)
.create(true)
.delete(true)
.write(true);
OffsetDateTime startTime = OffsetDateTime.now().minusDays(1);
OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);
IPRange ipRange = new IPRange()
.ipMin("0.0.0.0")
.ipMax("255.255.255.255");
SASProtocol sasProtocol = SASProtocol.HTTPS_HTTP;
String cacheControl = "cache";
String contentDisposition = "disposition";
String contentEncoding = "encoding";
String contentLanguage = "language";
String contentType = "type";
String version = Constants.HeaderConstants.TARGET_STORAGE_VERSION;
String sas = fileClient.generateSAS(identifier, permissions, expiryTime, startTime, version, sasProtocol,
ipRange, cacheControl, contentDisposition, contentEncoding, contentLanguage, contentType);
SASTokenCredential credential = SASTokenCredential.fromSASTokenString(sas);
In V12, you need to use the client builder to build the clients. Constructor pattern is not available. Create client in v10:
final BlockBlobURL blobURL = new BlockBlobURL(
new URL("https://" + accountName + ".blob.core.windows.net/mycontainer/myimage.jpg"),
StorageURL.createPipeline(creds, new PipelineOptions())
);
Build Sync client in v12:
final BlockBlobClient blobClient = new BlobClientBuilder().endpoint("<your-storage-blob-url>")
.credential("<your-sasToken>")
.buildBlockBlobClient();
Build Async client in v12:
final BlockBlobAsyncClient blobAsyncClient = new BlobClientBuilder().endpoint("<your-storage-blob-url>")
.credential("<your-sasToken>")
.buildBlockBlobAsyncClient();
For most of async APIs in V10, we will find corresponding sync APIs.
E.g. Async API getProperties()
in V10:
Single<BlobGetPropertiesResponse> response = blobURL.getProperties();
Corresponding sync API in V12:
BlobProperties blobProperties = containerClient.getProperties();
In V12, we have provided single event Async API (Mono
) and Multiple event Async API (PageFlux
)
E.g. Single event in V10:
E.g. Multiple events in V10:
E.g. Single event in V12:
E.g. Multiple events in V12:
Instead of Single<ListT>
in V10, V12 provids two Pagination class PagedIterable<T>
over Sync and PageFlux<T>
over Async.
With the addition of Sync APIs, BlobInputStream
and BlobOutputStream
fit nicely within this story. Customers who have long depended on these types will find the same interface and will require minimal upgrade. We will also be adding Client-Side Encryption as we bring the library to full parity.