modify permission (#22960)

Author: maririos

sdk/translation/Azure.AI.Translation.Document/README.md

@@ -103,6 +103,14 @@ var client = new DocumentTranslationClient(new Uri(endpoint), new DefaultAzureCr
 ```
 
 ## Key concepts
+The Document Translation service requires that you upload your files to an Azure Blob Storage source container and provide
+a target container where the translated documents can be written. SAS tokens to the containers (or files) are used to
+access the documents and create the translated documents in the target container. Additional information about setting this up can be found in
+the service documentation:
+
+- [Set up Azure Blob Storage containers][source_containers] with your documents.
+- Optionally apply [glossaries][glossary] or a [custom model for translation][custom_model].
+- Generate [SAS tokens][sas_token] to your containers (or files) with the appropriate [permissions][sas_token_permissions].
 
 ### DocumentTranslationClient
 A `DocumentTranslationClient` is the primary interface for developers using the Document Translation client library.  It provides both synchronous and asynchronous methods to perform the following operations:
@@ -448,6 +456,11 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [azure_portal_create_DT_resource]: https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesTextTranslation
 [cognitive_resource_cli]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account-cli
 [dotnet_lro_guidelines]: https://azure.github.io/azure-sdk/dotnet_introduction.html#dotnet-longrunning
+[source_containers]: https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/get-started-with-document-translation?tabs=csharp#create-your-azure-blob-storage-containers
+[custom_model]: https://docs.microsoft.com/azure/cognitive-services/translator/custom-translator/quickstart-build-deploy-custom-model
+[glossary]: https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/overview#supported-glossary-formats
+[sas_token]: https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/create-sas-tokens?tabs=Containers#create-your-sas-tokens-with-azure-storage-explorer
+[sas_token_permissions]: https://aka.ms/azsdk/documenttranslation/sas-permissions
 
 [documenttranslation_client_class]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/translation/Azure.AI.Translation.Document/src/DocumentTranslationClient.cs
 [azure_identity]: https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/identity/Azure.Identity/README.md

sdk/translation/Azure.AI.Translation.Document/samples/Sample1_StartTranslation.md

@@ -19,10 +19,8 @@ To Start a translation operation for a single document or documents in a single
 
 To call `StartTranslationAsync` you need to initialize an object of type `DocumentTranslationInput` which contains the information needed to translate the documents.
 
-- The `sourceUri` is a SAS URI with read access for the document to be translated or read and list access for the blob container holding the documents to be translated.
-- The `targetUri` is a SAS URI with read and write access for the blob container to which the translated documents will be written.
-
-More on generating SAS Tokens [here](https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/get-started-with-document-translation?tabs=csharp#create-sas-access-tokens-for-document-translation)
+> The `sourceUri` and the `targetUri` are SAS URI with permissions that allow the service to access the content on the container/blob.
+See the [service documentation][Sas_token_permissions] for the supported SAS permissions.
 
 ```C# Snippet:StartTranslationAsync
 Uri sourceUri = new Uri("<source SAS URI>");
@@ -66,5 +64,6 @@ To see the full example source files, see:
 * [Synchronously StartTranslation ](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/translation/Azure.AI.Translation.Document/tests/samples/Sample_StartTranslation.cs)
 * [Asynchronously StartTranslation ](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/translation/Azure.AI.Translation.Document/tests/samples/Sample_StartTranslationAsync.cs)
 
+[Sas_token_permissions]: https://aka.ms/azsdk/documenttranslation/sas-permissions
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md
 [README]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/translation/Azure.AI.Translation.Document/README.md

sdk/translation/Azure.AI.Translation.Document/samples/Sample4_MultipleInputs.md

@@ -19,10 +19,8 @@ To Start a translation operation for documents in multiple blob containers, call
 
 To call `StartTranslationAsync` you need to initialize a list of `DocumentTranslationInput` which contains the information needed to translate the documents. Each `DocumentTranslationInput` contains a source container and a list of target containers. The `AddTarget` method is used to add targets to the input.
 
-- The `sourceUri` is a SAS URI with read access for the document to be translated or read and list access for the blob container holding the documents to be translated.
-- The `targetUri` is a SAS URI with read and write access for the blob container to which the translated documents will be written.
-
-More on generating SAS Tokens [here](https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/get-started-with-document-translation?tabs=csharp#create-sas-access-tokens-for-document-translation)
+> The `sourceUri` and the `targetUri` are SAS URI with permissions that allow the service to access the content on the container/blob.
+See the [service documentation][Sas_token_permissions] for the supported SAS permissions.
 
 ```C# Snippet:MultipleInputsAsync
 Uri source1SasUriUri = new Uri("<source1 SAS URI>");
@@ -74,5 +72,6 @@ To see the full example source files, see:
 * [Synchronously MultipleInputs ](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/translation/Azure.AI.Translation.Document/tests/samples/Sample_MultipleInputs.cs)
 * [Asynchronously MultipleInputs ](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/translation/Azure.AI.Translation.Document/tests/samples/Sample_MultipleInputsAsync.cs)
 
+[Sas_token_permissions]: https://aka.ms/azsdk/documenttranslation/sas-permissions
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md
 [README]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/translation/Azure.AI.Translation.Document/README.md

sdk/translation/Azure.AI.Translation.Document/src/DocumentTranslationInput.cs

@@ -19,8 +19,12 @@ public partial class DocumentTranslationInput
         /// <summary>
         /// Initializes a new instance of <see cref="DocumentTranslationInput"/>.
         /// </summary>
-        /// <param name="sourceUri">The SAS URI for the source container containing documents to be translated. Read and List permissions are needed.</param>
-        /// <param name="targetUri">The SAS URI for the target container to which the translated documents will be written. Read and Write permissions are needed.</param>
+        /// <param name="sourceUri">The SAS URI for the source container containing documents to be translated.
+        /// See the service documentation for the supported SAS permissions for accessing
+        /// source storage containers/blobs: <a href="https://aka.ms/azsdk/documenttranslation/sas-permissions"/>.</param>
+        /// <param name="targetUri">The SAS URI for the target container to which the translated documents will be written.
+        /// See the service documentation for the supported SAS permissions for accessing
+        /// target storage containers/blobs: <a href="https://aka.ms/azsdk/documenttranslation/sas-permissions"/>.</param>
         /// <param name="targetLanguageCode">Language code to translate documents to. For supported languages see
         /// <a href="https://docs.microsoft.com/azure/cognitive-services/translator/language-support#translate"/>.</param>
         /// <param name="glossary">Custom <see cref="TranslationGlossary"/> to be used in the translation operation. For supported file types see
@@ -39,7 +43,9 @@ public DocumentTranslationInput(Uri sourceUri, Uri targetUri, string targetLangu
         /// <summary>
         /// Add a <see cref="TranslationTarget"/> to the translation input.
         /// </summary>
-        /// <param name="targetUri">The SAS URI for the target container to which the translated documents will be written. Read and Write permissions are needed.</param>
+        /// <param name="targetUri">The SAS URI for the target container to which the translated documents will be written.
+        /// See the service documentation for the supported SAS permissions for accessing
+        /// target storage containers/blobs: <a href="https://aka.ms/azsdk/documenttranslation/sas-permissions"/>.</param>
         /// <param name="languageCode">Language code to translate documents to. For supported languages see
         /// <a href="https://docs.microsoft.com/azure/cognitive-services/translator/language-support#translate"/>.</param>
         /// <param name="glossary">Custom <see cref="TranslationGlossary"/> to be used in the translation operation. For supported file types see

sdk/translation/Azure.AI.Translation.Document/src/TranslationSource.cs

@@ -14,7 +14,8 @@ public partial class TranslationSource
 
         /// <summary>
         /// Location of the folder / container or single file with your documents.
-        /// This should be a SAS Uri.
+        /// See the service documentation for the supported SAS permissions for accessing
+        /// source storage containers/blobs: <a href="https://aka.ms/azsdk/documenttranslation/sas-permissions"/>.
         /// </summary>
         [CodeGenMember("SourceUrl")]
         public Uri SourceUri { get; }

sdk/translation/Azure.AI.Translation.Document/src/TranslationTarget.cs

@@ -14,7 +14,8 @@ public partial class TranslationTarget
 
         /// <summary>
         /// Location of the container with your documents.
-        /// This should be a SAS Uri.
+        /// See the service documentation for the supported SAS permissions for accessing
+        /// target storage containers/blobs: <a href="https://aka.ms/azsdk/documenttranslation/sas-permissions"/>.
         /// </summary>
         [CodeGenMember("TargetUrl")]
         public Uri TargetUri { get; }

sdk/translation/Azure.AI.Translation.Document/tests/Infrastructure/DocumentTranslationLiveTestBase.cs

@@ -91,7 +91,7 @@ public async Task<Uri> CreateTargetContainerAsync(List<TestDocument> documents =
             }
 
             var expiresOn = DateTimeOffset.UtcNow.AddHours(1);
-            return containerClient.GenerateSasUri(BlobContainerSasPermissions.Read | BlobContainerSasPermissions.Write, expiresOn);
+            return containerClient.GenerateSasUri(BlobContainerSasPermissions.List | BlobContainerSasPermissions.Write, expiresOn);
         }
 
         private async Task UploadDocumentsAsync(BlobContainerClient containerClient, List<TestDocument> documents)

sdk/translation/Azure.AI.Translation.Document/tests/samples/Sample_StartTranslationWithAzureBlob.cs

@@ -81,7 +81,7 @@ This sample demonstrates how to use Azure Blob Storage to set up the necessary r
 
             // Generate SAS tokens for source & target
             Uri srcSasUri = sourceContainerClient.GenerateSasUri(BlobContainerSasPermissions.List | BlobContainerSasPermissions.Read, DateTime.UtcNow.AddMinutes(30));
-            Uri tgtSasUri = targetContainerClient.GenerateSasUri(BlobContainerSasPermissions.Read | BlobContainerSasPermissions.Write | BlobContainerSasPermissions.Delete, DateTime.UtcNow.AddMinutes(30));
+            Uri tgtSasUri = targetContainerClient.GenerateSasUri(BlobContainerSasPermissions.List | BlobContainerSasPermissions.Write | BlobContainerSasPermissions.Delete, DateTime.UtcNow.AddMinutes(30));
 
             // Submit the translation operation and wait for it to finish
             var operationRequest = new DocumentTranslationInput(srcSasUri, tgtSasUri, "es");