[storage] Add migration guide for storage packages#18305
Merged
EmmaZhu merged 4 commits intoAzure:mainfrom Dec 11, 2021
Merged
Conversation
EmmaZhu
requested review from
XiaoningLiu,
jeremymeng,
jiacfan,
ljian3377 and
vinjiang
as code owners
ghost
added
the
jeremymeng
reviewed
Oct 21, 2021
|
|
||
| There were several areas of consistent feedback expressed across the Azure client library ecosystem. One of the most important is that the client libraries for different Azure services have not had a consistent approach to organization, naming, and API structure. Additionally, many developers have felt that the learning curve was difficult, and the APIs did not offer a good, approachable, and consistent onboarding story for those learning Azure or exploring a specific Azure service. | ||
|
|
||
| To improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [TypeScript & JavaScript Guidelines](https://azure.github.io/azure-sdk/typescript_introduction.html) was also introduced to ensure that TypeScript clients have a natural and idiomatic feel with respect to the TypeScript and JavaScript ecosystems. The new `@azure/storage-blob` follows these guidelines. |
Member
There was a problem hiding this comment.
Suggested change
| To improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [TypeScript & JavaScript Guidelines](https://azure.github.io/azure-sdk/typescript_introduction.html) was also introduced to ensure that TypeScript clients have a natural and idiomatic feel with respect to the TypeScript and JavaScript ecosystems. The new `@azure/storage-blob` follows these guidelines. | |
| To improve the development experience across Azure services, a set of uniform [design guidelines](https://azure.github.io/azure-sdk/general_introduction.html) was created for all languages to drive a consistent experience with established API patterns for all services. A set of [TypeScript & JavaScript Guidelines](https://azure.github.io/azure-sdk/typescript_introduction.html) was also introduced to ensure that TypeScript clients have a natural and idiomatic feel with respect to the TypeScript and JavaScript ecosystems. The new `@azure/storage-blob` client library follows these guidelines. |
|
|
||
| ### Cross Service SDK improvements | ||
|
|
||
| The modern `@azure/storage-blob` client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as |
Member
There was a problem hiding this comment.
Suggested change
| The modern `@azure/storage-blob` client library also provides the ability to share in some of the cross-service improvements made to the Azure development experience, such as | |
| The modern `@azure/storage-blob` client library is also benefited from the cross-service improvements made to the Azure development experience, such as |
|
|
||
| The modern client library is named `@azure/storage-blob` and was released beginning with version 10. The legacy client library is named `azure-storage` with version of 2.x.x or below. | ||
|
|
||
| The legacy library `azure-storage` grouped functionality to work with multiple services in the same package such as `Blob`, `Queue`, `Files` and `Tables`. The new `@azure/storage-blob` is dedicated to `Blob` there are new generation packages for the other storage services `@azure/data-tables`, `@azure/storage-queue`, `@azure/storage-file-share` this provides more granular control on which dependencies to take on your project. |
Member
There was a problem hiding this comment.
Suggested change
| The legacy library `azure-storage` grouped functionality to work with multiple services in the same package such as `Blob`, `Queue`, `Files` and `Tables`. The new `@azure/storage-blob` is dedicated to `Blob` there are new generation packages for the other storage services `@azure/data-tables`, `@azure/storage-queue`, `@azure/storage-file-share` this provides more granular control on which dependencies to take on your project. | |
| The legacy library `azure-storage` grouped functionality to work with multiple services in the same package such as `Blob`, `Queue`, `Files` and `Tables`. The new `@azure/storage-blob` is dedicated to `Blob` service. New generation packages are available for the other storage services as well: `@azure/data-tables`, `@azure/storage-queue`, | |
| and `@azure/storage-file-share`. This provides more granular control on which dependencies to take in your project. |
|
|
||
| ### Uploading a blob to the container | ||
|
|
||
| Previously in `azure-storage`, A `BlobService` instance would be used for blob operations. `BlobService` has methods for blob operations for each blob type. `createBlockBlobFromLocalFile` would be used to upload from a local file to a block blob. |
Member
There was a problem hiding this comment.
Suggested change
| Previously in `azure-storage`, A `BlobService` instance would be used for blob operations. `BlobService` has methods for blob operations for each blob type. `createBlockBlobFromLocalFile` would be used to upload from a local file to a block blob. | |
| Previously in `azure-storage`, A `BlobService` instance would be used for blob operations. `BlobService` has methods for blob operations for each blob type. For example, `createBlockBlobFromLocalFile` would be used to upload from a local file to a block blob. |
|
|
||
| ### Listing blobs from the container | ||
|
|
||
| Previously in `azure-storage`, listing a container didn't provide a built in way to handle pagination, looking as follows. |
Member
There was a problem hiding this comment.
Suggested change
| Previously in `azure-storage`, listing a container didn't provide a built in way to handle pagination, looking as follows. | |
| Previously in `azure-storage`, there is no built-in way to handle pagination when listing blobs in a container. Users have to use `continuationToken` to get the next page of result then retrieve the items. |
Member
Author
|
Thanks a lot @jeremymeng for the comments. I've updated the change as your suggestion. Could you help to take a look? |
XiaoningLiu
reviewed
Oct 28, 2021
|
|
||
| The modern client library is named `@azure/storage-blob` and was released beginning with version 10. The legacy client library is named `azure-storage` with version of 2.x.x or below. | ||
|
|
||
| The legacy library `azure-storage` grouped functionality to work with multiple services in the same package such as `Blob`, `Queue`, `Files` and `Tables`. The new `@azure/storage-blob` is dedicated to `Blob` service. New generation packages are available for the other storage services as well: `@azure/data-tables`, `@azure/storage-queue` and `@azure/storage-file-share`. This provides more granular control on which dependencies to take on your project. |
Member
There was a problem hiding this comment.
We also have @azure/storage-file-datalake and changefeed packages.
XiaoningLiu
reviewed
Oct 28, 2021
|
|
||
| ### Creating a container | ||
|
|
||
| Previously in `azure-storage`, you would use a `BlobService` instance to create a container. The `createContainer` method would take a callback to execute once the blob container has been created. This forces sequential operations to be inside the callback, potentially creating a callback chain |
XiaoningLiu
reviewed
Oct 28, 2021
| }); | ||
| ``` | ||
|
|
||
| With `@azure/storage-blob` you have access to all container level operations directly from the `BlobServiceClient`. Because the blob service client is not affinitized to any one container, it is ideal for scenarios where you need to create, delete, or list more than one blob container. |
Member
There was a problem hiding this comment.
"you have access to" -> "you access to"
XiaoningLiu
approved these changes
Oct 28, 2021
Member
XiaoningLiu
left a comment
XiaoningLiu
left a comment
There was a problem hiding this comment.
Overall looks good and incredibly detailed and helpful.
Added minor comments and mostly for grammar and spelling issues. Better to have another check.
ramya-rao-a
reviewed
Nov 2, 2021
|
|
||
| ### Package name and structure | ||
|
|
||
| The modern client library is named `@azure/storage-blob` and was released beginning with version 10. The legacy client library is named `azure-storage` with version of 2.x.x or below. |
Contributor
There was a problem hiding this comment.
Why do we want to specify version 10 here? Won't it be confusing given that this guide is to migrate to v12? We can also skip mentioning the versions for azure-storage. That entire package is considered as legacy, so specifying versions here does not add any extra value
Contributor
There was a problem hiding this comment.
Unresolving this comment thread as I dont see what the resolution is
| @@ -0,0 +1,263 @@ | |||
| # Guide for migrating to `@azure/storage-blob` from `azure-storage` | |||
Contributor
There was a problem hiding this comment.
Should we specify v12 here because there is v10 for the same package and people might get confused?
Member
Author
There was a problem hiding this comment.
I'm trying to add version info here.
What do you think about:
Guide for migrating to @azure/storage-blob v12 from azure-storage
or
Guide for migrating to @azure/storage-blob with version 12.. from azure-storage
Contributor
There was a problem hiding this comment.
My vote is for the first option
| const blobService = azure.createBlobService("<connection-string>"); | ||
| ``` | ||
|
|
||
| Now, in `@azure/storage-blob`, we need a `BlobServiceClient` for service level operations. |
Contributor
There was a problem hiding this comment.
Suggested change
| Now, in `@azure/storage-blob`, we need a `BlobServiceClient` for service level operations. | |
| Now, in `@azure/storage-blob`, we will be creating an instance of `BlobServiceClient` for service level operations. |
|
|
||
| ### Uploading a blob to the container | ||
|
|
||
| Previously in `azure-storage`, A `BlobService` instance would be used for blob operations. `BlobService` has methods for blob operations for each blob type. For example, `createBlockBlobFromLocalFile` would be used to upload from a local file to a block blob. |
Contributor
There was a problem hiding this comment.
Suggested change
| Previously in `azure-storage`, A `BlobService` instance would be used for blob operations. `BlobService` has methods for blob operations for each blob type. For example, `createBlockBlobFromLocalFile` would be used to upload from a local file to a block blob. | |
| Previously in `azure-storage`, the `BlobService` class would have methods for operations for each blob type. For example, `BlobService.createBlockBlobFromLocalFile()` would be used to upload from a local file to a block blob. |
| }); | ||
| ``` | ||
|
|
||
| Now in the new `@azure/storage-blob` SDK, instances of `BlockBlobClient`, `PageBlobClient` and `AppendBlobClient` would be used for blob operations. Method `uploadFile` of a `BlockBlobClient` can be used to upload from a local file to a block blob. |
Contributor
There was a problem hiding this comment.
Suggested change
| Now in the new `@azure/storage-blob` SDK, instances of `BlockBlobClient`, `PageBlobClient` and `AppendBlobClient` would be used for blob operations. Method `uploadFile` of a `BlockBlobClient` can be used to upload from a local file to a block blob. | |
| Now in the new `@azure/storage-blob` SDK, we have dedicated classes `BlockBlobClient`, `PageBlobClient` and `AppendBlobClient` for each blob type. For example, `BlockBlobClient.uploadFile()` can be used to upload from a local file to a block blob. |
Contributor
|
@EmmaZhu Are there any plans on making further updates to this PR? |
ramya-rao-a
suggested changes
Dec 8, 2021
Contributor
ramya-rao-a
left a comment
ramya-rao-a
left a comment
There was a problem hiding this comment.
I have left some comments for the blob migration guide. Most of them will apply to the other migration guides as well. Please take a look
| @@ -0,0 +1,290 @@ | |||
| # Guide for migrating to `@azure/storage-blob` v12 from `azure-storage` | |||
|
|
|||
| This guide is intended to assist in the migration to `@azure/storage-blob` from the legacy `azure-storage` package. It will focus on side-by-side comparisons for similar operations between the two packages. | |||
Contributor
There was a problem hiding this comment.
Suggested change
| This guide is intended to assist in the migration to `@azure/storage-blob` from the legacy `azure-storage` package. It will focus on side-by-side comparisons for similar operations between the two packages. | |
| This guide is intended to assist in the migration to version 12 of `@azure/storage-blob` from the legacy `azure-storage` package. It will focus on side-by-side comparisons for similar operations between the two packages. |
|
|
||
| ### Package name and structure | ||
|
|
||
| The modern client library is named `@azure/storage-blob` . The legacy client library is named `azure-storage`. |
Contributor
There was a problem hiding this comment.
Suggested change
| The modern client library is named `@azure/storage-blob` . The legacy client library is named `azure-storage`. | |
| The modern client library is named `@azure/storage-blob` following the [naming conventions](https://azure.github.io/azure-sdk/typescript_design.html) for the new libraries across all Azure services. The legacy client library was named `azure-storage`. |
|
|
||
| The modern client library is named `@azure/storage-blob` . The legacy client library is named `azure-storage`. | ||
|
|
||
| The legacy library `azure-storage` grouped functionality to work with multiple services in the same package such as `Blob`, `Queue`, `Files` and `Tables`. The new `@azure/storage-blob` is dedicated to `Blob` service. New generation packages are available for the other storage services as well: `@azure/data-tables`, `@azure/storage-queue`, `@azure/storage-blob-changefeed`, `@azure/storage-file-datalake` and `@azure/storage-file-share`. This provides more granular control on which dependencies to take on your project. |
Contributor
There was a problem hiding this comment.
Suggested change
| The legacy library `azure-storage` grouped functionality to work with multiple services in the same package such as `Blob`, `Queue`, `Files` and `Tables`. The new `@azure/storage-blob` is dedicated to `Blob` service. New generation packages are available for the other storage services as well: `@azure/data-tables`, `@azure/storage-queue`, `@azure/storage-blob-changefeed`, `@azure/storage-file-datalake` and `@azure/storage-file-share`. This provides more granular control on which dependencies to take on your project. | |
| The legacy library `azure-storage` grouped functionality to work with multiple services such as `Blob`, `Queue`, `Files` and `Tables` in the same package. The new `@azure/storage-blob` package is dedicated to `Blob` service. Similary, dedicated packages are available for the other storage services as well: `@azure/data-tables`, `@azure/storage-queue`, `@azure/storage-blob-changefeed`, `@azure/storage-file-datalake` and `@azure/storage-file-share`. This reduces the bundle size if you were to use any of these packages in browser applications and provides more granular control on which dependencies to take on your project. |
|
|
||
| ### Constructing the clients with connection string | ||
|
|
||
| Previously in `azure-storage`, you would use `createBlobService` which can be used to get an instance of the `BlobService` in order to perform service level operations. |
Contributor
There was a problem hiding this comment.
Suggested change
| Previously in `azure-storage`, you would use `createBlobService` which can be used to get an instance of the `BlobService` in order to perform service level operations. | |
| Previously in `azure-storage`, you would pass the connection string to the function `createBlobService` to get an instance of the `BlobService` in order to perform operations on blobs and containers. |
| const blobService = azure.createBlobService("<connection-string>"); | ||
| ``` | ||
|
|
||
| Now, in `@azure/storage-blob`, we will be creating an instance of `BlobServiceClient` for service level operations. |
Contributor
There was a problem hiding this comment.
Suggested change
| Now, in `@azure/storage-blob`, we will be creating an instance of `BlobServiceClient` for service level operations. | |
| Now, in `@azure/storage-blob`, you can pass the connection string to the static method `BlobServiceClient.fromConnectionString` to create an instance of `BlobServiceClient` to perform operations on blobs and containers. |
|
|
||
| ### Constructing the clients with AAD token credentials | ||
|
|
||
| `azure-storage` or `@azure/storage-blob` supports to access `Blob` service with different types of credentials: anonymous, account key credentials, sas token, and AAD token credentials. This section shows samples to construct blob service clients with AAD token credentials. |
Contributor
There was a problem hiding this comment.
Suggested change
| `azure-storage` or `@azure/storage-blob` supports to access `Blob` service with different types of credentials: anonymous, account key credentials, sas token, and AAD token credentials. This section shows samples to construct blob service clients with AAD token credentials. | |
| Both `azure-storage` and `@azure/storage-blob` supports to access `Blob` service by creating the client with different types of credentials: anonymous, account key credentials, sas token, and AAD token credentials. This section shows the use of AAD token credentials. |
| ); | ||
| ``` | ||
|
|
||
| Now, for `@azure/storage-blob`, you can use a constructor of `BlobServiceClient` which accepts token credential classes provided in `@azure/identity` package to get a `BlobServiceClient` instance with AAD token credentials. In following sample, it creates an instance of `DefaultAzureCredential` which reads credentials from environment variables `AZURE_TENANT_ID`, `AZURE_CLIENT_ID` and `AZURE_CLIENT_SECRET`, and creates a `BlobServiceClient` to consume the credential instance. |
Contributor
There was a problem hiding this comment.
Suggested change
| Now, for `@azure/storage-blob`, you can use a constructor of `BlobServiceClient` which accepts token credential classes provided in `@azure/identity` package to get a `BlobServiceClient` instance with AAD token credentials. In following sample, it creates an instance of `DefaultAzureCredential` which reads credentials from environment variables `AZURE_TENANT_ID`, `AZURE_CLIENT_ID` and `AZURE_CLIENT_SECRET`, and creates a `BlobServiceClient` to consume the credential instance. | |
| Now, for `@azure/storage-blob`, you can pass any of the [credentials from the `@azure/identity` package](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/samples/AzureIdentityExamples.md) to the constructor of `BlobServiceClient` to make use of your AAD credentials. In following sample, it creates an instance of `DefaultAzureCredential` which reads credentials from environment variables `AZURE_TENANT_ID`, `AZURE_CLIENT_ID` and `AZURE_CLIENT_SECRET`, and creates a `BlobServiceClient` to consume the credential instance. |
ramya-rao-a
approved these changes
Dec 11, 2021
openapi-sdkautomation Bot
pushed a commit
to AzureSDKAutomation/azure-sdk-for-js
that referenced
this pull request
Mar 25, 2022
[Stream Analytics] Fix s360 for 2021 preview version (Azure#18305) * Add blockchain to latest profile * Add additional types * add azure function * add authenticationMode to blob input, AzFunction and DW ex files * update api version in 2021 preview ex files * fix api version * fix password * try to run model validation again * update pe to readonly * 2021 preview features * fix validation errors * more fixes * add aggregate func, which should be GA * rename new refreshType object Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com> Co-authored-by: Roslyn Lu <roslu@microsoft.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add migration guide from v2 to v12 storage packages: @azure/storage-blob, @azure/storage-file-share, @azure/storage-queue.