[text analytics] add logging param (#18729)

Author: iscai-msft

sdk/textanalytics/azure-ai-textanalytics/CHANGELOG.md

@@ -11,6 +11,7 @@
 **New Features**
 - Added enums `EntityConditionality`, `EntityCertainty`, and `EntityAssociation`.
 - Added `AnalyzeSentimentAction` as a supported action type for `begin_analyze_batch_actions`.
+- Added kwarg `disable_service_logs`. If set to true, you opt-out of having your text input logged on the service side for troubleshooting.
 
 ## 5.1.0b6 (2021-03-09)
 
@@ -114,7 +115,7 @@ used in conjunction with the Bing Entity Search API to fetch additional relevant
 - Removed `grapheme_offset` and `grapheme_length` from `CategorizedEntity`, `SentenceSentiment`, and `LinkedEntityMatch`
 - `TextDocumentStatistics` attribute `grapheme_count` has been renamed to `character_count`
 
-## 1.0.0b5 
+## 1.0.0b5
 
 - This was a broken release
 

sdk/textanalytics/azure-ai-textanalytics/azure/ai/textanalytics/_models.py

@@ -3,7 +3,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
-
+import copy
 from typing import (  # pylint: disable=unused-import
     Union,
     Optional,
@@ -157,6 +157,14 @@ def detect_language(  # type: ignore
             See here for more info: https://aka.ms/text-analytics-model-versioning
         :keyword bool show_stats: If set to true, response will contain document
             level statistics in the `statistics` field of the document-level response.
+        :keyword bool disable_service_logs: If set to true, you opt-out of having your text input
+            logged on the service side for troubleshooting. By default, Text Analytics logs your
+            input text for 48 hours, solely to allow for troubleshooting issues in providing you with
+            the Text Analytics natural language processing functions. Setting this parameter to true,
+            disables input logging and may limit our ability to remediate issues that occur. Please see
+            Cognitive Services Compliance and Privacy notes at https://aka.ms/cs-compliance for
+            additional details, and Microsoft Responsible AI principles at
+            https://www.microsoft.com/ai/responsible-ai.
         :return: The combined list of :class:`~azure.ai.textanalytics.DetectLanguageResult` and
             :class:`~azure.ai.textanalytics.DocumentError` in the order the original documents were
             passed in.
@@ -178,6 +186,9 @@ def detect_language(  # type: ignore
         docs = _validate_input(documents, "country_hint", country_hint)
         model_version = kwargs.pop("model_version", None)
         show_stats = kwargs.pop("show_stats", False)
+        disable_service_logs = kwargs.pop("disable_service_logs", None)
+        if disable_service_logs is not None:
+            kwargs['logging_opt_out'] = disable_service_logs
         try:
             return self._client.languages(
                 documents=docs,
@@ -228,6 +239,14 @@ def recognize_entities(  # type: ignore
             `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
             you can also pass in `Utf16CodePoint` or TextElement_v8`. For additional information
             see https://aka.ms/text-analytics-offsets
+        :keyword bool disable_service_logs: If set to true, you opt-out of having your text input
+            logged on the service side for troubleshooting. By default, Text Analytics logs your
+            input text for 48 hours, solely to allow for troubleshooting issues in providing you with
+            the Text Analytics natural language processing functions. Setting this parameter to true,
+            disables input logging and may limit our ability to remediate issues that occur. Please see
+            Cognitive Services Compliance and Privacy notes at https://aka.ms/cs-compliance for
+            additional details, and Microsoft Responsible AI principles at
+            https://www.microsoft.com/ai/responsible-ai.
         :return: The combined list of :class:`~azure.ai.textanalytics.RecognizeEntitiesResult` and
             :class:`~azure.ai.textanalytics.DocumentError` in the order the original documents
             were passed in.
@@ -256,6 +275,9 @@ def recognize_entities(  # type: ignore
         )
         if string_index_type:
             kwargs.update({"string_index_type": string_index_type})
+        disable_service_logs = kwargs.pop("disable_service_logs", None)
+        if disable_service_logs is not None:
+            kwargs['logging_opt_out'] = disable_service_logs
 
         try:
             return self._client.entities_recognition_general(
@@ -316,6 +338,14 @@ def recognize_pii_entities(  # type: ignore
             `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
             you can also pass in `Utf16CodePoint` or `TextElement_v8`. For additional information
             see https://aka.ms/text-analytics-offsets
+        :keyword bool disable_service_logs: If set to true, you opt-out of having your text input
+            logged on the service side for troubleshooting. By default, Text Analytics logs your
+            input text for 48 hours, solely to allow for troubleshooting issues in providing you with
+            the Text Analytics natural language processing functions. Setting this parameter to true,
+            disables input logging and may limit our ability to remediate issues that occur. Please see
+            Cognitive Services Compliance and Privacy notes at https://aka.ms/cs-compliance for
+            additional details, and Microsoft Responsible AI principles at
+            https://www.microsoft.com/ai/responsible-ai.
         :return: The combined list of :class:`~azure.ai.textanalytics.RecognizePiiEntitiesResult`
             and :class:`~azure.ai.textanalytics.DocumentError` in the order the original documents
             were passed in.
@@ -347,6 +377,9 @@ def recognize_pii_entities(  # type: ignore
         )
         if string_index_type:
             kwargs.update({"string_index_type": string_index_type})
+        disable_service_logs = kwargs.pop("disable_service_logs", None)
+        if disable_service_logs is not None:
+            kwargs['logging_opt_out'] = disable_service_logs
 
         try:
             return self._client.entities_recognition_pii(
@@ -407,6 +440,14 @@ def recognize_linked_entities(  # type: ignore
             `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
             you can also pass in `Utf16CodePoint` or `TextElement_v8`. For additional information
             see https://aka.ms/text-analytics-offsets
+        :keyword bool disable_service_logs: If set to true, you opt-out of having your text input
+            logged on the service side for troubleshooting. By default, Text Analytics logs your
+            input text for 48 hours, solely to allow for troubleshooting issues in providing you with
+            the Text Analytics natural language processing functions. Setting this parameter to true,
+            disables input logging and may limit our ability to remediate issues that occur. Please see
+            Cognitive Services Compliance and Privacy notes at https://aka.ms/cs-compliance for
+            additional details, and Microsoft Responsible AI principles at
+            https://www.microsoft.com/ai/responsible-ai.
         :return: The combined list of :class:`~azure.ai.textanalytics.RecognizeLinkedEntitiesResult`
             and :class:`~azure.ai.textanalytics.DocumentError` in the order the original documents
             were passed in.
@@ -428,6 +469,9 @@ def recognize_linked_entities(  # type: ignore
         docs = _validate_input(documents, "language", language)
         model_version = kwargs.pop("model_version", None)
         show_stats = kwargs.pop("show_stats", False)
+        disable_service_logs = kwargs.pop("disable_service_logs", None)
+        if disable_service_logs is not None:
+            kwargs['logging_opt_out'] = disable_service_logs
 
         string_index_type = _check_string_index_type_arg(
             kwargs.pop("string_index_type", None),
@@ -503,6 +547,14 @@ def begin_analyze_healthcare_entities(  # type: ignore
         :keyword int polling_interval: Waiting time between two polls for LRO operations
             if no Retry-After header is present. Defaults to 5 seconds.
         :keyword str continuation_token: A continuation token to restart a poller from a saved state.
+        :keyword bool disable_service_logs: If set to true, you opt-out of having your text input
+            logged on the service side for troubleshooting. By default, Text Analytics logs your
+            input text for 48 hours, solely to allow for troubleshooting issues in providing you with
+            the Text Analytics natural language processing functions. Setting this parameter to true,
+            disables input logging and may limit our ability to remediate issues that occur. Please see
+            Cognitive Services Compliance and Privacy notes at https://aka.ms/cs-compliance for
+            additional details, and Microsoft Responsible AI principles at
+            https://www.microsoft.com/ai/responsible-ai.
         :return: An instance of an AnalyzeHealthcareEntitiesLROPoller. Call `result()` on the this
             object to return a pageable of :class:`~azure.ai.textanalytics.AnalyzeHealthcareEntitiesResultItem`.
         :rtype:
@@ -529,22 +581,30 @@ def begin_analyze_healthcare_entities(  # type: ignore
         string_index_type = kwargs.pop("string_index_type", self._string_index_type_default)
 
         doc_id_order = [doc.get("id") for doc in docs]
+        my_cls = kwargs.pop(
+            "cls", partial(self._healthcare_result_callback, doc_id_order, show_stats=show_stats)
+        )
+        disable_service_logs = kwargs.pop("disable_service_logs", None)
+        polling_kwargs = kwargs
+        operation_kwargs = copy.copy(kwargs)
+        if disable_service_logs is not None:
+            operation_kwargs['logging_opt_out'] = disable_service_logs
 
         try:
             return self._client.begin_health(
                 docs,
                 model_version=model_version,
                 string_index_type=string_index_type,
-                cls=kwargs.pop("cls", partial(self._healthcare_result_callback, doc_id_order, show_stats=show_stats)),
+                cls=my_cls,
                 polling=AnalyzeHealthcareEntitiesLROPollingMethod(
                     text_analytics_client=self._client,
                     timeout=polling_interval,
                     lro_algorithms=[
                         TextAnalyticsOperationResourcePolling(show_stats=show_stats)
                     ],
-                    **kwargs),
+                    **polling_kwargs),
                 continuation_token=continuation_token,
-                **kwargs
+                **operation_kwargs
             )
 
         except ValueError as error:
@@ -595,6 +655,14 @@ def extract_key_phrases(  # type: ignore
             See here for more info: https://aka.ms/text-analytics-model-versioning
         :keyword bool show_stats: If set to true, response will contain document
             level statistics in the `statistics` field of the document-level response.
+        :keyword bool disable_service_logs: If set to true, you opt-out of having your text input
+            logged on the service side for troubleshooting. By default, Text Analytics logs your
+            input text for 48 hours, solely to allow for troubleshooting issues in providing you with
+            the Text Analytics natural language processing functions. Setting this parameter to true,
+            disables input logging and may limit our ability to remediate issues that occur. Please see
+            Cognitive Services Compliance and Privacy notes at https://aka.ms/cs-compliance for
+            additional details, and Microsoft Responsible AI principles at
+            https://www.microsoft.com/ai/responsible-ai.
         :return: The combined list of :class:`~azure.ai.textanalytics.ExtractKeyPhrasesResult` and
             :class:`~azure.ai.textanalytics.DocumentError` in the order the original documents were
             passed in.
@@ -616,6 +684,10 @@ def extract_key_phrases(  # type: ignore
         docs = _validate_input(documents, "language", language)
         model_version = kwargs.pop("model_version", None)
         show_stats = kwargs.pop("show_stats", False)
+        disable_service_logs = kwargs.pop("disable_service_logs", None)
+        if disable_service_logs is not None:
+            kwargs['logging_opt_out'] = disable_service_logs
+
         try:
             return self._client.key_phrases(
                 documents=docs,
@@ -672,6 +744,14 @@ def analyze_sentiment(  # type: ignore
             `UnicodeCodePoint`, the Python encoding, is the default. To override the Python default,
             you can also pass in `Utf16CodePoint` or `TextElement_v8`. For additional information
             see https://aka.ms/text-analytics-offsets
+        :keyword bool disable_service_logs: If set to true, you opt-out of having your text input
+            logged on the service side for troubleshooting. By default, Text Analytics logs your
+            input text for 48 hours, solely to allow for troubleshooting issues in providing you with
+            the Text Analytics natural language processing functions. Setting this parameter to true,
+            disables input logging and may limit our ability to remediate issues that occur. Please see
+            Cognitive Services Compliance and Privacy notes at https://aka.ms/cs-compliance for
+            additional details, and Microsoft Responsible AI principles at
+            https://www.microsoft.com/ai/responsible-ai.
         .. versionadded:: v3.1-preview
             The *show_opinion_mining* parameter.
             The *string_index_type* parameter.
@@ -697,6 +777,9 @@ def analyze_sentiment(  # type: ignore
         model_version = kwargs.pop("model_version", None)
         show_stats = kwargs.pop("show_stats", False)
         show_opinion_mining = kwargs.pop("show_opinion_mining", None)
+        disable_service_logs = kwargs.pop("disable_service_logs", None)
+        if disable_service_logs is not None:
+            kwargs['logging_opt_out'] = disable_service_logs
 
         string_index_type = _check_string_index_type_arg(
             kwargs.pop("string_index_type", None),