[translation] update docs to include managed identity option (#22366)

* update dt docs to include managed identity option

* fix readme formatting

* remove word

* fix typo

Author: kristapratico

sdk/translation/azure-ai-translation-document/README.md

@@ -120,14 +120,14 @@ document_translation_client = DocumentTranslationClient(
 ## 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
+a target container where the translated documents can be written. 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]
-
+- Allow access to your storage account with either of the following options:
+    - Generate [SAS tokens][sas_token] to your containers (or files) with the appropriate [permissions][sas_token_permissions]
+    - Create and use a [managed identity][managed_identity] to grant access to your storage account
 
 ### DocumentTranslationClient
 
@@ -456,7 +456,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [custom_subdomain]: https://docs.microsoft.com/azure/cognitive-services/authentication#create-a-resource-with-a-custom-subdomain
 [azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity
 [default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential
-
+[managed_identity]: https://aka.ms/azsdk/documenttranslation/managed-identity
 [sdk_logging_docs]: https://docs.microsoft.com/azure/developer/python/azure-sdk-logging
 
 [sample_authentication]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/translation/azure-ai-translation-document/samples/sample_authentication.py

sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_client.py

@@ -125,12 +125,16 @@ def begin_translation(
         For supported languages and document formats, see the service documentation:
         https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/overview
 
-        :param str source_url: The source SAS URL to the Azure Blob container containing the documents
-            to be translated. See the service documentation for the supported SAS permissions for accessing
-            source storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions
-        :param str target_url: The target SAS URL to the Azure Blob container where the translated documents
-            should be written. See the service documentation for the supported SAS permissions for accessing
-            target storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions
+        :param str source_url: The source URL to the Azure Blob container containing the documents to be translated.
+            This can be a SAS URL (see the service documentation for the supported SAS permissions for accessing
+            source storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions) or a managed
+            identity can be created and used to access documents in your storage account
+            (see https://aka.ms/azsdk/documenttranslation/managed-identity).
+        :param str target_url: The target URL to the Azure Blob container where the translated documents
+            should be written. This can be a SAS URL (see the service documentation for the supported SAS permissions
+            for accessing target storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions)
+            or a managed identity can be created and used to access documents in your storage account
+            (see https://aka.ms/azsdk/documenttranslation/managed-identity).
         :param str target_language_code: This is the language you want your documents to be translated to.
             See supported language codes here:
             https://docs.microsoft.com/azure/cognitive-services/translator/language-support#translate

sdk/translation/azure-ai-translation-document/azure/ai/translation/document/_models.py

@@ -32,10 +32,13 @@ def convert_status(status, ll=False):
 class TranslationGlossary(object):  # pylint: disable=useless-object-inheritance
     """Glossary / translation memory to apply to the translation.
 
-    :param str glossary_url: Required. Location of the glossary file. This should be a SAS URL to
-        the glossary file in the storage blob container. If the translation language pair is
-        not present in the glossary, it will not be applied. See the service documentation for the
-        supported SAS permissions: https://aka.ms/azsdk/documenttranslation/sas-permissions
+    :param str glossary_url: Required. Location of the glossary file. This should be a URL to
+        the glossary file in the storage blob container. The URL can be a SAS URL (see the
+        service documentation for the supported SAS permissions for accessing storage
+        containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions) or a managed identity
+        can be created and used to access documents in your storage account
+        (see https://aka.ms/azsdk/documenttranslation/managed-identity). Note that if the translation
+        language pair is not present in the glossary, it will not be applied.
     :param str file_format: Required. Format of the glossary file. To see supported formats,
         call the :func:`~DocumentTranslationClient.get_supported_glossary_formats()` client method.
     :keyword str format_version: File format version. If not specified, the service will
@@ -44,10 +47,13 @@ class TranslationGlossary(object):  # pylint: disable=useless-object-inheritance
     :keyword str storage_source: Storage Source. Default value: "AzureBlob".
         Currently only "AzureBlob" is supported.
 
-    :ivar str glossary_url: Required. Location of the glossary file. This should be a SAS URL to
-        the glossary file in the storage blob container. If the translation language pair is
-        not present in the glossary, it will not be applied. See the service documentation for the
-        supported SAS permissions: https://aka.ms/azsdk/documenttranslation/sas-permissions
+    :ivar str glossary_url: Required. Location of the glossary file. This should be a URL to
+        the glossary file in the storage blob container. The URL can be a SAS URL (see the
+        service documentation for the supported SAS permissions for accessing storage
+        containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions) or a managed identity
+        can be created and used to access documents in your storage account
+        (see https://aka.ms/azsdk/documenttranslation/managed-identity). Note that if the translation
+        language pair is not present in the glossary, it will not be applied.
     :ivar str file_format: Required. Format of the glossary file. To see supported formats,
         call the :func:`~DocumentTranslationClient.get_supported_glossary_formats()` client method.
     :ivar str format_version: File format version. If not specified, the service will
@@ -95,9 +101,10 @@ class TranslationTarget(object):  # pylint: disable=useless-object-inheritance
     """Destination for the finished translated documents.
 
     :param str target_url: Required. The target location for your translated documents.
-        This should be a container SAS URL to your target container/blob. See the service
-        documentation for the supported SAS permissions for accessing
-        target storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions
+        This can be a SAS URL (see the service documentation for the supported SAS permissions
+        for accessing target storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions)
+        or a managed identity can be created and used to access documents in your storage account
+        (see https://aka.ms/azsdk/documenttranslation/managed-identity).
     :param str language_code: Required. Target Language Code. This is the language
         you want your documents to be translated to. See supported languages here:
         https://docs.microsoft.com/azure/cognitive-services/translator/language-support#translate
@@ -108,9 +115,10 @@ class TranslationTarget(object):  # pylint: disable=useless-object-inheritance
         Currently only "AzureBlob" is supported.
 
     :ivar str target_url: Required. The target location for your translated documents.
-        This should be a container SAS URL to your target container/blob. See the service
-        documentation for the supported SAS permissions for accessing
-        target storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions
+        This can be a SAS URL (see the service documentation for the supported SAS permissions
+        for accessing target storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions)
+        or a managed identity can be created and used to access documents in your storage account
+        (see https://aka.ms/azsdk/documenttranslation/managed-identity).
     :ivar str language_code: Required. Target Language Code. This is the language
         you want your documents to be translated to. See supported languages here:
         https://docs.microsoft.com/azure/cognitive-services/translator/language-support#translate
@@ -165,13 +173,15 @@ def __repr__(self):
 class DocumentTranslationInput(object):  # pylint: disable=useless-object-inheritance
     # pylint: disable=C0301
     """Input for translation. This requires that you have your source document or
-    documents in an Azure Blob Storage container. Provide a SAS URL to the source file or
+    documents in an Azure Blob Storage container. Provide a URL to the source file or
     source container containing the documents for translation. The source document(s) are
     translated and written to the location provided by the TranslationTargets.
 
     :param str source_url: Required. Location of the folder / container or single file with your
-        documents. See the service documentation for the supported SAS permissions for accessing
-        source storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions
+        documents. This can be a SAS URL (see the service documentation for the supported SAS permissions
+        for accessing source storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions)
+        or a managed identity can be created and used to access documents in your storage account
+        (see https://aka.ms/azsdk/documenttranslation/managed-identity).
     :param targets: Required. Location of the destination for the output. This is a list of
         TranslationTargets. Note that a TranslationTarget is required for each language code specified.
     :type targets: list[~azure.ai.translation.document.TranslationTarget]
@@ -189,8 +199,10 @@ class DocumentTranslationInput(object):  # pylint: disable=useless-object-inheri
         Currently only "AzureBlob" is supported.
 
     :ivar str source_url: Required. Location of the folder / container or single file with your
-        documents. See the service documentation for the supported SAS permissions for accessing
-        source storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions
+        documents. This can be a SAS URL (see the service documentation for the supported SAS permissions
+        for accessing source storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions)
+        or a managed identity can be created and used to access documents in your storage account
+        (see https://aka.ms/azsdk/documenttranslation/managed-identity).
     :ivar targets: Required. Location of the destination for the output. This is a list of
         TranslationTargets. Note that a TranslationTarget is required for each language code specified.
     :vartype targets: list[~azure.ai.translation.document.TranslationTarget]

sdk/translation/azure-ai-translation-document/azure/ai/translation/document/aio/_client_async.py

@@ -134,12 +134,16 @@ async def begin_translation(
         For supported languages and document formats, see the service documentation:
         https://docs.microsoft.com/azure/cognitive-services/translator/document-translation/overview
 
-        :param str source_url: The source SAS URL to the Azure Blob container containing the documents
-            to be translated. See the service documentation for the supported SAS permissions for accessing
-            source storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions
-        :param str target_url: The target SAS URL to the Azure Blob container where the translated documents
-            should be written. See the service documentation for the supported SAS permissions for accessing
-            target storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions
+        :param str source_url: The source URL to the Azure Blob container containing the documents to be translated.
+            This can be a SAS URL (see the service documentation for the supported SAS permissions for accessing
+            source storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions) or a managed
+            identity can be created and used to access documents in your storage account
+            (see https://aka.ms/azsdk/documenttranslation/managed-identity).
+        :param str target_url: The target URL to the Azure Blob container where the translated documents
+            should be written. This can be a SAS URL (see the service documentation for the supported SAS permissions
+            for accessing target storage containers/blobs: https://aka.ms/azsdk/documenttranslation/sas-permissions)
+            or a managed identity can be created and used to access documents in your storage account
+            (see https://aka.ms/azsdk/documenttranslation/managed-identity).
         :param str target_language_code: This is the language you want your documents to be translated to.
             See supported language codes here:
             https://docs.microsoft.com/azure/cognitive-services/translator/language-support#translate