Fix the issue 10325: Readme content of Azure Storage File Data Lake is unclear and inconsistencey

sdk/storage/azure-storage-blob-cryptography/README.md

@@ -10,7 +10,7 @@ This package supports client side encryption for blob storage.
 
 ### Prerequisites
 
--  Java Development Kit (JDK) with version 8 or above
+- [Java Development Kit (JDK)][jdk] with version 8 or above
 - [Azure Subscription][azure_subscription]
 - [Create Storage Account][storage_account]
 
@@ -27,9 +27,9 @@ This package supports client side encryption for blob storage.
 [//]: # ({x-version-update-end})
 
 ### Create a Storage Account
-To create a Storage Account you can use the Azure Portal or [Azure CLI][storage_account_create_cli].
+To create a Storage Account you can use the [Azure Portal][storage_account_create_portal] or [Azure CLI][storage_account_create_cli].
 
-```Powershell
+```bash
 az storage account create \
     --resource-group <resource-group-name> \
     --name <storage-account-name> \
@@ -45,49 +45,53 @@ To make this possible you'll need the Account SAS (shared access signature) stri
 
 - **SAS Token**
 
-a. Use the [Azure CLI][azure_cli] snippet below to get the SAS token from the Storage account.
+a. Use the Azure CLI snippet below to get the SAS token from the Storage Account.
 
-```Powershell
-az storage blob generate-sas
-    --name {queue name}
-    --expiry {date/time to expire SAS token}
-    --permission {permission to grant}
-    --connection-string {connection string of the storage account}
-    --services {storage services the SAS allows}
+```bash
+az storage blob generate-sas \
+    --account-name {Storage Account name} \
+    --container-name {container name} \
+    --name {blob name} \
+    --permissions {permissions to grant} \
+    --expiry {datetime to expire the SAS token} \
+    --services {storage services the SAS allows} \
     --resource-types {resource types the SAS allows}
 ```
 
-```Powershell
+Example:
+
+```bash
 CONNECTION_STRING=<connection-string>
 
-az storage blob generate-sas
-    --name javasdksas
-    --expiry 2019-06-05
-    --permission rpau
-    --connection-string $CONNECTION_STRING
+az storage blob generate-sas \
+    --account-name MyStorageAccount \
+    --container-name MyContainer \
+    --name MyBlob \
+    --permissions racdw \
+    --expiry 2020-06-15
 ```
 
 b. Alternatively, get the Account SAS Token from the Azure Portal.
 
-```
-Go to your storage account -> Shared access signature -> Click on Generate SAS and connection string (after setup)
-```
+1. Go to your Storage Account
+2. Select `Shared access signature` from the menu on the left
+3. Click on `Generate SAS and connection string` (after setup)
 
-- **Shared Key Credential**
+##### **Shared Key Credential**
 
-a. Use account name and account key. Account name is your storage account name.
+a. Use Account name and Account key. Account name is your Storage Account name.
 
-```
-// Here is where we get the key
-Go to your storage account -> Access keys -> Key 1/ Key 2 -> Key
-```
+1. Go to your Storage Account
+2. Select `Access keys` from the menu on the left
+3. Under `key1`/`key2` copy the contents of the `Key` field
 
-b. Use the connection string
+or
 
-```
-// Here is where we get the key
-Go to your storage account -> Access Keys -> Keys 1/ Key 2 -> Connection string
-```
+b. Use the connection string.
+
+1. Go to your Storage Account
+2. Select `Access keys` from the menu on the left
+3. Under `key1`/`key2` copy the contents of the `Connection string` field
 
 ## Key concepts
 
@@ -100,8 +104,6 @@ Blob storage is designed for:
 - Storing data for backup and restore, disaster recovery, and archiving.
 - Storing data for analysis by an on-premises or Azure-hosted service.
 
-## Examples
-
 ## Troubleshooting
 
 When interacting with blobs using this Java client library, errors returned by the service correspond to the same HTTP
@@ -129,3 +131,10 @@ When you submit a pull request, a CLA-bot will automatically determine whether y
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
 
 ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fstorage%2Fazure-storage-blob-cryptography%2FREADME.png)
+
+[jdk]: https://docs.microsoft.com/java/azure/jdk/
+[azure_subscription]: https://azure.microsoft.com/free/
+[storage_account]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal
+[storage_account_create_cli]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-cli
+[storage_account_create_portal]: https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal
+[sas_token]: https://docs.microsoft.com/azure/storage/common/storage-dotnet-shared-access-signature-part-1

sdk/storage/azure-storage-file-datalake/README.md

@@ -38,7 +38,8 @@ Note: To use data lake, your account must have hierarchical namespace enabled.
 az storage account create \
     --resource-group <resource-group-name> \
     --name <storage-account-name> \
-    --location <location>
+    --location <location> \
+    --enable-hierarchical-namespace true
 ```
 
 Your storage account URL, subsequently identified as <your-storage-account-url>, would be formatted as follows
@@ -136,25 +137,27 @@ Note: This client library does not support hierarchical namespace (HNS) disabled
 ### URL format
 Paths are addressable using the following URL format:
 The following URL addresses a file:
-https://myaccount.dfs.core.windows.net/myfilesystem/myfile
+```
+https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${myfile}
+```
 
 #### Resource URI Syntax
 For the storage account, the base URI for datalake operations includes the name of the account only:
 
 ```
-https://myaccount.dfs.core.windows.net
+https://${myaccount}.dfs.core.windows.net
 ```
 
 For a file system, the base URI includes the name of the account and the name of the file system:
 
 ```
-https://myaccount.dfs.core.windows.net/myfilesystem
+https://${myaccount}.dfs.core.windows.net/${myfilesystem}
 ```
 
 For a file/directory, the base URI includes the name of the account, the name of the file system and the name of the path:
 
 ```
-https://myaccount.dfs.core.windows.net/myfilesystem/mypath
+https://${myaccount}.dfs.core.windows.net/${myfilesystem}/${mypath}
 ```
 
 Note that the above URIs may not hold for more advanced scenarios such as custom domain names.
@@ -164,13 +167,15 @@ Note that the above URIs may not hold for more advanced scenarios such as custom
 The following sections provide several code snippets covering some of the most common Azure Storage Blob tasks, including:
 
 - [Create a `DataLakeServiceClient`](#create-a-datalakeserviceclient)
-- [Create a `DataLakeFileSystemClient`](#create-a-filesystemclient)
-- [Create a `DataLakeFileClient`](#create-a-fileclient)
-- [Create a `DataLakeDirectoryClient`](#create-a-directoryclient)
-- [Create a file system](#create-a-filesystem)
-- [Upload a file from a stream](#upload-a-file-from-a-stream)
-- [Read a file to a stream](#read-a-file-to-a-stream)
+- [Create a `DataLakeFileSystemClient`](#create-a-datalakefilesystemclient)
+- [Create a `DataLakeFileClient`](#create-a-datalakefileclient)
+- [Create a `DataLakeDirectoryClient`](#create-a-datalakedirectoryclient)
+- [Create a file system](#create-a-file-system)
 - [Enumerate paths](#enumerate-paths)
+- [Rename a file](#rename-a-file)
+- [Rename a directory](#rename-a-directory)
+- [Get file properties](#get-file-properties)
+- [Get directory properties](#get-directory-properties)
 - [Authenticate with Azure Identity](#authenticate-with-azure-identity)
 
 ### Create a `DataLakeServiceClient`
@@ -189,6 +194,7 @@ or
 
 <!-- embedme ./src/samples/java/com/azure/storage/file/datalake/ReadmeSamples.java#L32-L34 -->
 ```java
+// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
 DataLakeServiceClient dataLakeServiceClient = new DataLakeServiceClientBuilder()
     .endpoint("<your-storage-account-url>" + "?" + "<your-sasToken>")
     .buildClient();
@@ -220,6 +226,7 @@ or
 
 <!-- embedme ./src/samples/java/com/azure/storage/file/datalake/ReadmeSamples.java#L50-L52 -->
 ```java
+// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
 DataLakeFileSystemClient dataLakeFileSystemClient = new DataLakeFileSystemClientBuilder()
     .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "?" + "<your-sasToken>")
     .buildClient();
@@ -252,6 +259,7 @@ or
 
 <!-- embedme ./src/samples/java/com/azure/storage/file/datalake/ReadmeSamples.java#L69-L71 -->
 ```java
+// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
 DataLakeFileClient fileClient = new DataLakePathClientBuilder()
     .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "myfile" + "?" + "<your-sasToken>")
     .buildFileClient();
@@ -284,6 +292,7 @@ or
 
 <!-- embedme ./src/samples/java/com/azure/storage/file/datalake/ReadmeSamples.java#L88-L90 -->
 ```java
+// Only one "?" is needed here. If the sastoken starts with "?", please removing one "?".
 DataLakeDirectoryClient directoryClient = new DataLakePathClientBuilder()
     .endpoint("<your-storage-account-url>" + "/" + "myfilesystem" + "/" + "mydir" + "?" + "<your-sasToken>")
     .buildDirectoryClient();
@@ -324,6 +333,7 @@ Rename a file using a `DataLakeFileClient`.
 
 <!-- embedme ./src/samples/java/com/azure/storage/file/datalake/ReadmeSamples.java#L108-L110 -->
 ```java
+//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
 DataLakeFileClient fileClient = dataLakeFileSystemClient.getFileClient("myfile");
 fileClient.create();
 fileClient.rename("new-file-system-name", "new-file-name");
@@ -335,6 +345,7 @@ Rename a directory using a `DataLakeDirectoryClient`.
 
 <!-- embedme ./src/samples/java/com/azure/storage/file/datalake/ReadmeSamples.java#L114-L116 -->
 ```java
+//Need to authenticate with azure identity and add role assignment "Storage Blob Data Contributor" to do the following operation.
 DataLakeDirectoryClient directoryClient = dataLakeFileSystemClient.getDirectoryClient("mydir");
 directoryClient.create();
 directoryClient.rename("new-file-system-name", "new-directory-name");