[TA] merge Feature/textanalyticsv31 branch

sdk/textanalytics/Azure.AI.TextAnalytics/CHANGELOG.md

@@ -4,6 +4,10 @@
 ### New features
 - Added support for service version `3.0`. This can be specified in the `TextAnalyticsClientOptions` object under the `ServiceVersion` enum. By default the SDK targets latest supported service version.
 - Added value `None` to enum `PiiEntityDomainType` to allow user to specify no domain.
+- Added property `ActionName` to all `xxActions` input types so user can specify a name per action. If not provided, service will generate a name.
+- Added property `ActionName` to all `xxActionResult` output types that displays the name of each action.
+- Added new overload methods to all `xxActions` types that take a `xxOptions` object to facilitate a transition from a singular method to an actions method.
+- The parameter `CategoriesFilter` in `RecognizePiiEntitiesActions` has been enabled for `StartAnalyzeActions` methods.
 
 ### Breaking changes
 - Renamed `StartAnalyzeBatchActions` to `StartAnalyzeActions`.

sdk/textanalytics/Azure.AI.TextAnalytics/README.md

@@ -612,6 +612,7 @@ This functionality allows running multiple actions in one or more documents. Act
         int docNumber = 1;
         foreach (RecognizeEntitiesActionResult entitiesActionResults in entitiesResults)
         {
+            Console.WriteLine($" Action name: {entitiesActionResults.ActionName}");
             foreach (RecognizeEntitiesResult documentResults in entitiesActionResults.DocumentsResults)
             {
                 Console.WriteLine($" Document #{docNumber++}");
@@ -634,6 +635,7 @@ This functionality allows running multiple actions in one or more documents. Act
         docNumber = 1;
         foreach (RecognizePiiEntitiesActionResult piiActionResults in piiResults)
         {
+            Console.WriteLine($" Action name: {piiActionResults.ActionName}");
             foreach (RecognizePiiEntitiesResult documentResults in piiActionResults.DocumentsResults)
             {
                 Console.WriteLine($" Document #{docNumber++}");
@@ -656,6 +658,7 @@ This functionality allows running multiple actions in one or more documents. Act
         docNumber = 1;
         foreach (ExtractKeyPhrasesActionResult keyPhrasesActionResult in keyPhrasesResults)
         {
+            Console.WriteLine($" Action name: {keyPhrasesActionResult.ActionName}");
             foreach (ExtractKeyPhrasesResult documentResults in keyPhrasesActionResult.DocumentsResults)
             {
                 Console.WriteLine($" Document #{docNumber++}");
@@ -673,6 +676,7 @@ This functionality allows running multiple actions in one or more documents. Act
         docNumber = 1;
         foreach (RecognizeLinkedEntitiesActionResult linkedEntitiesActionResults in entityLinkingResults)
         {
+            Console.WriteLine($" Action name: {linkedEntitiesActionResults.ActionName}");
             foreach (RecognizeLinkedEntitiesResult documentResults in linkedEntitiesActionResults.DocumentsResults)
             {
                 Console.WriteLine($" Document #{docNumber++}");
@@ -704,6 +708,7 @@ This functionality allows running multiple actions in one or more documents. Act
         docNumber = 1;
         foreach (AnalyzeSentimentActionResult analyzeSentimentActionsResult in analyzeSentimentResults)
         {
+            Console.WriteLine($" Action name: {analyzeSentimentActionsResult.ActionName}");
             foreach (AnalyzeSentimentResult documentResults in analyzeSentimentActionsResult.DocumentsResults)
             {
                 Console.WriteLine($" Document #{docNumber++}");
@@ -720,7 +725,6 @@ This functionality allows running multiple actions in one or more documents. Act
 
 ### Known Issues
 - `StartAnalyzeHealthcareEntities` is in gated preview and can not be used with AAD credentials. For more information, see [the Text Analytics for Health documentation](https://docs.microsoft.com/azure/cognitive-services/text-analytics/how-tos/text-analytics-for-health?tabs=ner#request-access-to-the-public-preview).
-- The parameter `CategoriesFilter` in `RecognizePiiEntitiesOptions` is currently not working when used in `StartAnalyzeBatchActions`. [19237](https://github.com/Azure/azure-sdk-for-net/issues/19237).
 - At time of this SDK release, the `ModelVersion` option to `StartAnalyzeHealthcareEntities` is ignored by the service. The service always processes the operation using the `latest` model.
 
 ## Troubleshooting

sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample_AnalyzeActions.md

@@ -70,6 +70,7 @@ To run multiple actions in multiple documents, call `StartAnalyzeActionsAsync` o
         int docNumber = 1;
         foreach (RecognizeEntitiesActionResult entitiesActionResults in entitiesResults)
         {
+            Console.WriteLine($" Action name: {entitiesActionResults.ActionName}");
             foreach (RecognizeEntitiesResult documentResults in entitiesActionResults.DocumentsResults)
             {
                 Console.WriteLine($" Document #{docNumber++}");
@@ -92,6 +93,7 @@ To run multiple actions in multiple documents, call `StartAnalyzeActionsAsync` o
         docNumber = 1;
         foreach (RecognizePiiEntitiesActionResult piiActionResults in piiResults)
         {
+            Console.WriteLine($" Action name: {piiActionResults.ActionName}");
             foreach (RecognizePiiEntitiesResult documentResults in piiActionResults.DocumentsResults)
             {
                 Console.WriteLine($" Document #{docNumber++}");
@@ -114,6 +116,7 @@ To run multiple actions in multiple documents, call `StartAnalyzeActionsAsync` o
         docNumber = 1;
         foreach (ExtractKeyPhrasesActionResult keyPhrasesActionResult in keyPhrasesResults)
         {
+            Console.WriteLine($" Action name: {keyPhrasesActionResult.ActionName}");
             foreach (ExtractKeyPhrasesResult documentResults in keyPhrasesActionResult.DocumentsResults)
             {
                 Console.WriteLine($" Document #{docNumber++}");
@@ -131,6 +134,7 @@ To run multiple actions in multiple documents, call `StartAnalyzeActionsAsync` o
         docNumber = 1;
         foreach (RecognizeLinkedEntitiesActionResult linkedEntitiesActionResults in entityLinkingResults)
         {
+            Console.WriteLine($" Action name: {linkedEntitiesActionResults.ActionName}");
             foreach (RecognizeLinkedEntitiesResult documentResults in linkedEntitiesActionResults.DocumentsResults)
             {
                 Console.WriteLine($" Document #{docNumber++}");
@@ -162,6 +166,7 @@ To run multiple actions in multiple documents, call `StartAnalyzeActionsAsync` o
         docNumber = 1;
         foreach (AnalyzeSentimentActionResult analyzeSentimentActionsResult in analyzeSentimentResults)
         {
+            Console.WriteLine($" Action name: {analyzeSentimentActionsResult.ActionName}");
             foreach (AnalyzeSentimentResult documentResults in analyzeSentimentActionsResult.DocumentsResults)
             {
                 Console.WriteLine($" Document #{docNumber++}");

sdk/textanalytics/Azure.AI.TextAnalytics/src/AnalyzeActionsOperation.cs

@@ -300,10 +300,16 @@ async ValueTask<OperationState<AsyncPageable<AnalyzeActionsResult>>> IOperation<
 
             Response rawResponse = response.GetRawResponse();
 
-            // TODO - Remove PartiallySucceeded once service deploys this to WestUS2
+            if (response.Value.Status == TextAnalyticsOperationStatus.Failed)
+            {
+                if (CheckIfGenericError(response.Value))
+                {
+                    RequestFailedException requestFailedException = await ClientCommon.CreateExceptionForFailedOperationAsync(async, _diagnostics, rawResponse, response.Value.Errors).ConfigureAwait(false);
+                    return OperationState<AsyncPageable<AnalyzeActionsResult>>.Failure(rawResponse, requestFailedException);
+                }
+            }
+
             if (response.Value.Status == TextAnalyticsOperationStatus.Succeeded ||
-                response.Value.Status == TextAnalyticsOperationStatus.PartiallySucceeded ||
-                response.Value.Status == TextAnalyticsOperationStatus.PartiallyCompleted ||
                 response.Value.Status == TextAnalyticsOperationStatus.Failed)
             {
                 string nextLink = response.Value.NextLink;
@@ -315,5 +321,15 @@ async ValueTask<OperationState<AsyncPageable<AnalyzeActionsResult>>> IOperation<
 
             return OperationState<AsyncPageable<AnalyzeActionsResult>>.Pending(rawResponse);
         }
+
+        private static bool CheckIfGenericError(AnalyzeJobState jobState)
+        {
+            foreach (TextAnalyticsErrorInternal error in jobState.Errors)
+            {
+                if (string.IsNullOrEmpty(error.Target))
+                    return true;
+            }
+            return false;
+        }
     }
 }

sdk/textanalytics/Azure.AI.TextAnalytics/src/AnalyzeSentimentAction.cs

@@ -20,6 +20,19 @@ public AnalyzeSentimentAction()
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AnalyzeSentimentAction"/>
+        /// class based on the values of a <see cref="AnalyzeSentimentOptions"/>.
+        /// It sets the <see cref="ModelVersion"/>, the <see cref="DisableServiceLogs"/>,
+        /// and the <see cref="IncludeOpinionMining"/> properties.
+        /// </summary>
+        public AnalyzeSentimentAction(AnalyzeSentimentOptions options)
+        {
+            ModelVersion = options.ModelVersion;
+            DisableServiceLogs = options.DisableServiceLogs;
+            IncludeOpinionMining = options.IncludeOpinionMining;
+        }
+
         /// <summary>
         /// Gets or sets a value that, if set, indicates the version of the text
         /// analytics model that will be used to generate the result.  For supported
@@ -34,7 +47,7 @@ public AnalyzeSentimentAction()
         /// Setting this property to true, disables input logging and may limit our ability to investigate issues that occur.
         /// </summary>
         /// <remarks>
-        /// This property only applies for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_1_Preview_5"/> and up.
+        /// This property only applies for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_1"/> and up.
         /// </remarks>
         public bool? DisableServiceLogs { get; set; }
 
@@ -46,8 +59,13 @@ public AnalyzeSentimentAction()
         /// <para>Only available for service version v3.1-preview and up.</para>
         /// </summary>
         /// <remarks>
-        /// This property only has value for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_1_Preview_5"/> and up.
+        /// This property only has value for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_1"/> and up.
         /// </remarks>
         public bool? IncludeOpinionMining { get; set; }
+
+        /// <summary>
+        /// Gets or sets a name for this action. If not provided, the service will generate one.
+        /// </summary>
+        public string ActionName { get; set; }
     }
 }

sdk/textanalytics/Azure.AI.TextAnalytics/src/AnalyzeSentimentActionResult.cs

@@ -13,28 +13,20 @@ public class AnalyzeSentimentActionResult : TextAnalyticsActionResult
     {
         private readonly AnalyzeSentimentResultCollection _documentsResults;
 
-        internal AnalyzeSentimentActionResult(AnalyzeSentimentResultCollection result, DateTimeOffset completedOn, TextAnalyticsErrorInternal error)
-            : base(completedOn, error)
-        {
-            _documentsResults = result;
-        }
-
         /// <summary>
-        /// Intended for mocking purposes only.
+        /// Successful action.
         /// </summary>
-        internal AnalyzeSentimentActionResult(
-            AnalyzeSentimentResultCollection result,
-            DateTimeOffset completedOn) : base(completedOn)
+        internal AnalyzeSentimentActionResult(AnalyzeSentimentResultCollection result, string actionName, DateTimeOffset completedOn)
+            : base(completedOn, actionName)
         {
             _documentsResults = result;
         }
 
         /// <summary>
-        /// Intended for mocking purposes only.
+        /// Action with an error.
         /// </summary>
-        internal AnalyzeSentimentActionResult(TextAnalyticsErrorInternal error) : base(error)
-        {
-        }
+        internal AnalyzeSentimentActionResult(string actionName, DateTimeOffset completedOn, TextAnalyticsErrorInternal error)
+            : base(completedOn, actionName, error) { }
 
         /// <summary>
         /// Gets the result of the execution of an <see cref="AnalyzeSentimentAction"/> per each input document.

sdk/textanalytics/Azure.AI.TextAnalytics/src/AnalyzeSentimentOptions.cs

@@ -33,7 +33,7 @@ internal AnalyzeSentimentOptions(TextAnalyticsRequestOptions options)
         /// <para>Only available for service version v3.1-preview and up.</para>
         /// </summary>
         /// <remarks>
-        /// This property only has value for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_1_Preview_5"/> and up.
+        /// This property only has value for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_1"/> and up.
         /// </remarks>
         public bool? IncludeOpinionMining { get; set; }
     }

sdk/textanalytics/Azure.AI.TextAnalytics/src/ExtractKeyPhrasesAction.cs

@@ -20,6 +20,17 @@ public ExtractKeyPhrasesAction()
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ExtractKeyPhrasesAction"/>
+        /// class based on the values of a <see cref="TextAnalyticsRequestOptions"/>.
+        /// It sets the <see cref="ModelVersion"/> and <see cref="DisableServiceLogs"/> properties.
+        /// </summary>
+        public ExtractKeyPhrasesAction(TextAnalyticsRequestOptions options)
+        {
+            ModelVersion = options.ModelVersion;
+            DisableServiceLogs = options.DisableServiceLogs;
+        }
+
         /// <summary>
         /// Gets or sets a value that, if set, indicates the version of the text
         /// analytics model that will be used to generate the result.  For supported
@@ -34,8 +45,13 @@ public ExtractKeyPhrasesAction()
         /// Setting this property to true, disables input logging and may limit our ability to investigate issues that occur.
         /// </summary>
         /// <remarks>
-        /// This property only applies for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_1_Preview_5"/> and up.
+        /// This property only applies for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_1"/> and up.
         /// </remarks>
         public bool? DisableServiceLogs { get; set; }
+
+        /// <summary>
+        /// Gets or sets a name for this action. If not provided, the service will generate one.
+        /// </summary>
+        public string ActionName { get; set; }
     }
 }

sdk/textanalytics/Azure.AI.TextAnalytics/src/ExtractKeyPhrasesActionResult.cs

@@ -13,28 +13,20 @@ public class ExtractKeyPhrasesActionResult : TextAnalyticsActionResult
     {
         private readonly ExtractKeyPhrasesResultCollection _documentsResults;
 
-        internal ExtractKeyPhrasesActionResult(ExtractKeyPhrasesResultCollection result, DateTimeOffset completedOn, TextAnalyticsErrorInternal error)
-            : base(completedOn, error)
-        {
-            _documentsResults = result;
-        }
-
         /// <summary>
-        /// Intended for mocking purposes only.
+        /// Successful action.
         /// </summary>
-        internal ExtractKeyPhrasesActionResult(
-            ExtractKeyPhrasesResultCollection result,
-            DateTimeOffset completedOn) : base(completedOn)
+        internal ExtractKeyPhrasesActionResult(ExtractKeyPhrasesResultCollection result, string actionName, DateTimeOffset completedOn)
+            : base(completedOn, actionName)
         {
             _documentsResults = result;
         }
 
         /// <summary>
-        /// Intended for mocking purposes only.
+        /// Action with an error.
         /// </summary>
-        internal ExtractKeyPhrasesActionResult(TextAnalyticsErrorInternal error) : base(error)
-        {
-        }
+        internal ExtractKeyPhrasesActionResult(string actionName, DateTimeOffset completedOn, TextAnalyticsErrorInternal error)
+            : base(completedOn, actionName, error) { }
 
         /// <summary>
         /// Gets the result of the execution of an <see cref="ExtractKeyPhrasesAction"/> per each input document.